agent-surface-forge

Agent surface forge

Contract

Inputs

• target (optional): path to audit; defaults to .. Taken from the first non-flag argument.
• --apply (optional flag): apply only HIGH-certainty findings with autoFix: yes. Absent means report only.
• --verbose (optional flag): include MEDIUM and LOW findings. Default output shows HIGH plus MEDIUM/LOW summary counts.
• --focus=<type> (optional): comma-separated subset of plugin, agent, skill, docs, prompt, claudemd, hooks, cross-file. Unknown values are rejected.

Procedure

1. Parse intent. Extract target, --apply, --verbose, --focus. Reject unknown focus values against the valid set above before any file access. Done when: target and flags are parsed and unknown focus values are rejected.
2. Discover files per analyzer family using these globs; keep concrete path lists and never pass globs to workers as the target contract:
   • plugin: plugins/*/.claude-plugin/plugin.json, .claude-plugin/plugin.json, **/.claude-plugin/plugin.json
   • agent: **/agents/*.md
   • skill: **/SKILL.md
   • claudemd: CLAUDE.md, AGENTS.md, **/CLAUDE.md, **/AGENTS.md
   • docs: docs/**, README.md, CHANGELOG.md
   • prompt: commands/**, prompts/**, **/commands/*.md, **/prompts/*.md
   • hooks: hooks/**, **/hooks/**
   • cross-file: enabled only when two or more of plugin/agent/skill/claudemd/prompt are present Skip analyzers with no discovered files. Under --focus, skip every non-focused family even if files exist. Done when: concrete file lists are discovered per analyzer family with non-focused families skipped.
3. Launch parallel analyzers in one task batch. Dispatch one generic task worker for each analyzer family that has files. Give each worker the analyzer name, exact file list, --verbose state, check catalog below, and required JSON return shape. Parallelize by analyzer family, never by file shards, because cross-surface consistency depends on seeing all relevant files for a family. Done when: one task worker is dispatched per analyzer family with files.
4. Check catalog per family. Every finding needs file, line or section, observed evidence, and a concrete fix; classify each by issue label: excess surface, duplication, structure, or correctness.
   • plugin: manifest fields explicit and bounded; name and description present; no excess or duplicated permissions; structure valid.
   • agent: frontmatter parses; name and description present and bounded; no duplicated or contradictory directives; structure valid.
   • skill: frontmatter parses; name matches the directory; description present and bounded; no excess surface, duplication, or structural drift; sections internally consistent.
   • claudemd: directives explicit and bounded; no duplicated or contradictory rules; no stale aliases; structure valid.
   • docs: referenced paths exist; no duplicated or contradictory content; structure valid.
   • prompt: command and prompt definitions explicit and bounded; no duplicated commands; structure valid.
   • hooks: hook scripts explicit and bounded; no duplicated handlers; structure and syntax valid.
   • cross-file: links between surfaces resolve; no duplicated or contradictory definitions across families; names referenced in one surface exist in the target surface. Done when: each analyzer family has its check catalog applied.
5. Analyzer contract. Each worker reports only observed findings as JSON:

   {
     "analyzer": "plugin|agent|skill|docs|prompt|claudemd|hooks|cross-file",
     "findings": [
       {"file":"path","line":1,"check":"missing_description","certainty":"HIGH","autoFix":false,"evidence":"...","fix":"..."}
     ],
     "summary": {"high":0,"medium":0,"low":0,"autoFixableHigh":0}
   }
   

   Use native tools directly: find and read for presence and frontmatter; search scoped to discovered files for regex and field checks; ast-grep for command snippets, shell patterns, and hook bodies where syntax matters; codegraph MCP for cross-file symbols, callers, and impact when indexed, falling back to ast-grep plus scoped text search; repomix (pack_codebase or pnpm dlx repomix --compress) only for large repos to build a digest for the workers. Done when: each worker returns findings in the required JSON shape.
6. Deduplicate. Stable key: analyzer|file|line|check|normalized evidence. If two analyzers report the same underlying defect, keep the higher certainty; if equal, keep the one with narrower file/line evidence. Done when: findings are deduplicated by stable key.
7. Aggregate. Sort by certainty HIGH then MEDIUM then LOW, then analyzer, file, line. Count totals by analyzer and certainty. Done when: findings are sorted and totals are counted.
8. Report. Default output: executive summary table, all HIGH findings, MEDIUM/LOW counts, and the HIGH auto-fixable list. Under --verbose, include MEDIUM and LOW sections with issue labels. Done when: the report is emitted with the correct verbosity.
9. Apply guarded fixes, only when --apply is present: filter to certainty === HIGH && autoFix === true; group by analyzer; edit the minimal lines required; re-read changed files after each edit; never apply MEDIUM or LOW fixes automatically. Done when: all HIGH autoFixable findings are applied (under --apply) or listed as safe edits (without --apply).
10. Verify the fix set. Re-run only the analyzers whose files changed. A fix passes if the exact HIGH finding is gone and no new HIGH finding appears in the changed file. If a fix introduces a new HIGH issue, revert that fix and keep the finding in the report as manual. Done when: every applied fix is verified with no new HIGH findings, or reverted findings are labeled manual.