open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(humanizer): update action command templates [skip-docs]

Browse source 
Wave 5 Step 15. Threads --raw plumbing through all seven action
command templates and adds a shape test covering structural plumbing
plus help.md's plain-language vocabulary.

- commands/fix.md: --raw flag parsed; fix-plan rendering groups by
  userActionLanguage; humanized title/description/recommendation are
  rendered verbatim from the cross-referenced scan envelope.
- commands/rollback.md: terminology pass — "manifest" → "list of
  changes" in user-facing copy; the file name manifest.yaml is kept
  as the machine contract; --raw threaded through.
- commands/plan.md: --raw forwarded to the planner-agent's prompt;
  agent now instructed to group actions by userImpactCategory and
  lead with userActionLanguage; bash block added for flag parsing.
- commands/implement.md: --raw forwarded to the implementer-agent's
  prompt; progress-log lines now reference the humanized titles
  already present in the action plan.
- commands/cleanup.md: --raw accepted as no-op (cleanup is
  file-management only, no findings prose); bash block added.
- commands/help.md: full plain-language pass — "PreToolUse" and
  "frontmatter" jargon removed from user-facing copy; new
  vocabulary table surfaces the humanized userImpactCategory and
  userActionLanguage labels ("Configuration mistake", "Conflict",
  "Wasted tokens", "Missed opportunity", "Dead config" / "Fix this
  now", "Fix soon", "Fix when convenient", "Optional cleanup",
  "FYI"); --raw documented as global pass-through flag.
- commands/interview.md: --raw accepted as no-op; "unused hooks"
  question phrased as "unused automation that runs at specific
  events" in user-facing copy.

tests/commands/action-commands-shape.test.mjs (new, +6 tests, 780 → 786):
  - structural: bash block + Read tool + --raw/$ARGUMENTS plumbing
    across all 7 files
  - help.md vocabulary: ≥3 userImpactCategory labels and ≥3
    userActionLanguage phrases present
  - help.md jargon: no bare "PreToolUse" or "frontmatter" in copy
This commit is contained in:
Kjell Tore Guttormsen 2026-05-01 19:50:47 +02:00
commit 347d4a2c4c
8 changed files with 228 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

29
plugins/config-audit/commands/fix.md
View file

@ -15,6 +15,7 @@ Auto-fix deterministic configuration issues. Scans, plans fixes, backs up origin
- `$ARGUMENTS` may contain:
- A target path (default: current working directory)
- `--dry-run`: Show fix plan without applying
- `--raw`: Pass-through to scanners; produces v5.0.0 verbatim envelope (bypasses the humanizer) for byte-stable diff tooling
## Implementation
@ -28,44 +29,50 @@ Tell the user:
Scanning for auto-fixable issues...
```
Run scanners silently:
Parse flags and run scanners silently. Default mode emits humanized JSON — each finding carries `userImpactCategory`, `userActionLanguage`, and `relevanceContext` alongside the v5.0.0 fields:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <path> --output-file /tmp/config-audit-fix-scan-$$.json [--global] 2>/dev/null; echo $?
RAW_FLAG=""
if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
node ${CLAUDE_PLUGIN_ROOT}/scanners/scan-orchestrator.mjs <path> --output-file /tmp/config-audit-fix-scan-$$.json [--global] $RAW_FLAG 2>/dev/null; echo $?
```
Exit code 3 → tell user: "Scanner error. Try `/config-audit posture` to check your configuration."
### Step 2: Plan fixes
Run fix planner silently:
Run fix planner silently. The fix-cli emits humanized prose to stderr in default mode and v5.0.0-shape JSON to stdout when `--json` is set; we use `--json` here for structured data and let the humanizer-aware rendering layer (this command's prose output below) supply the plain-language wording from the scan envelope above:
```bash
node ${CLAUDE_PLUGIN_ROOT}/scanners/fix-cli.mjs <path> --json 2>/dev/null
```
Read the JSON output. Categorize fixes into auto-fixable and manual.
Read the JSON output using the Read tool. Cross-reference each fix-plan entry against the humanized scan envelope (`/tmp/config-audit-fix-scan-$$.json`) by finding ID to recover the humanized `title`/`description`/`recommendation` plus `userImpactCategory`/`userActionLanguage` for grouping.
### Step 3: Present fix plan
Show what will be fixed and what needs manual attention:
Show what will be fixed and what needs manual attention. Group by `userActionLanguage` so the urgency phrasing stays consistent with the rest of the toolchain:
```markdown
### Fix Plan
**Auto-fixable ({N} issues):**
**Auto-fixable ({N} issues), grouped by impact:**
{For each userActionLanguage bucket in priority order — "Fix this now" → "Fix soon" → "Fix when convenient" → "Optional cleanup" → "FYI":}
#### {userActionLanguage}
| # | ID | Issue | File |
|---|-----|-------|------|
| 1 | CA-SET-003 | Add $schema to settings.json | .claude/settings.json |
| 2 | ... | ... | ... |
| 1 | {id} | {humanized title} | {file} |
**Manual ({M} issues — require human judgment):**
**Manual ({M} issues — require human judgment), grouped by impact:**
{Same userActionLanguage grouping. Render humanized title and recommendation verbatim — the humanizer already produced plain-language strings, do not paraphrase.}
| # | ID | Issue | Recommendation |
|---|-----|-------|----------------|
| 1 | CA-CML-003 | CLAUDE.md exceeds 200 lines | Split content into @imports or .claude/rules/ |
| ... | ... | ... | ... |
| 1 | {id} | {humanized title} | {humanized recommendation} |
```
### Step 4: Confirm with user