jmagly/dev-doctor

Dev Doctor

You run a comprehensive development-environment health check on the AIWG repository, checking structural integrity across all addons and frameworks, catching orphaned and misplaced components, and validating TypeScript compilation and test coverage gates. You produce a structured health report with pass/fail per check and actionable remediation steps for every failure.

Triggers

• "run dev doctor" → full health check
• "check aiwg dev health" → full health check
• "are there any placement violations" → run placement check section only
• "find orphaned skills" → run orphan check section only
• "is the repo in a good state" → full health check
• "pre-commit health check" → run dev-doctor before committing
• "dev health" → full health check

Trigger Patterns Reference

| Pattern | Example | Action | |---------|---------|--------| | Full check | "run dev doctor" | All sections | | Placement focus | "placement violations?" | Placement check only | | Orphan focus | "find orphaned skills" | Orphan detection only | | Pre-commit | "pre-commit health check" | Full check | | TypeScript | "does TypeScript compile" | Compilation check only | | Quick | "dev health" | Full check, condensed output |

Process

Run the following checks in sequence. Collect all results before generating the report.

Section 1: agentic/code/ Structure Integrity

1. Read agentic/code/addons/ — list all addon directories
2. For each addon directory:
   • manifest.json present and valid JSON
   • manifest.json has id, type, name, version, description
   • README.md present
3. Read agentic/code/frameworks/ — list all framework directories
4. For each framework directory:
   • manifest.json present and valid JSON
   • Required fields present

Section 2: Manifest vs Filesystem Consistency (Orphan Detection)

For each addon and framework:

Orphaned skills (SKILL.md exists but not in manifest):

• List all skills/*/SKILL.md files under the addon
• For each: verify the skill name appears in manifest.json skills array
• Any SKILL.md without a manifest entry is an orphan

Missing skills (in manifest but SKILL.md absent):

• For each entry in manifest.json skills array: verify skills/<name>/SKILL.md exists
• Any manifest entry without a corresponding SKILL.md is a missing skill

Repeat the same orphan/missing check for agents and rules.

Section 3: Placement Violations

For each provider directory that exists in the repository:

• .claude/skills/, .claude/agents/, .claude/commands/, .claude/rules/
• .github/agents/, .github/prompts/, .github/instructions/
• .cursor/skills/, .cursor/agents/, .cursor/commands/, .cursor/rules/

For each file found in a provider directory:

• Attempt to locate the corresponding source in agentic/code/
• If no source found: flag as a potential placement violation (note: some files like CLAUDE.md, settings.json, .gitignore are intentionally in provider directories and are not violations)
• Skills, agents, commands, and rule files with no agentic/code/ source are violations

Section 4: @file Reference Check (Full Classification)

All @file references in distributable skills and agents are checked against the full linking contract. Three categories of violations are reported:

Step 1: Build the Tier 2 normalized allowlist from installed manifests:

• Read all manifest.json files in agentic/code/
• Collect all memory.creates[*].path values
• Combine with Tier 1: .aiwg/AIWG.md, .aiwg/frameworks/

Step 2: Scan for .aiwg/ violations (Section 4a):

grep -rn "@\.aiwg/" agentic/code/ --include="*.md"

For each ref found: check against allowlist.

• Starts with a Tier 1/2 prefix → PASS
• Not in allowlist → FAIL (repo-local path)

Step 3: Scan for bare AIWG-core refs (Section 4b — legacy migration):

Use Grep tool to search for bare AIWG-core ref patterns — refs to agentic/code/, src/, docs/, tools/ that lack the $AIWG_ROOT/ token prefix — in agentic/code/ markdown files. Each match → WARN: legacy bare ref, needs $AIWG_ROOT/ prefix.

Note: No backtick or code-block escaping exists — any @<path> pattern in deployed skills is processed as a file reference regardless of surrounding markup.

Step 4: Scan for forbidden deployment-target refs (Section 4c):

Use Grep tool to search for @.claude/ in agentic/code/ markdown files. Each match → FAIL: deployment target ref, forbidden in distributable source.

Report format:

SECTION 4 — @file Reference Check

  4a — .aiwg/ References
  PASS  sdlc-complete/agents/requirements-analyst.md  .aiwg/requirements/ (normalized)
  FAIL  my-addon/skills/my-skill.md  .aiwg/planning/my-design.md
        → non-normalized path: only exists in AIWG dev repo

  4b — Bare AIWG-core References (legacy)
  WARN  research-complete/agents/workflow-agent.md  agentic/code/frameworks/research-complete/...
        → add $AIWG_ROOT/ prefix

  4c — Deployment-Target References (forbidden)
  (none)

Section 5: TypeScript Compilation

Run TypeScript type checking:

npx tsc --noEmit

• PASS: exit code 0, no errors
• FAIL: exit code non-zero, report the error count and first 5 error lines

Section 6: Test Suite

Run the test suite:

npm test

• PASS: exit code 0
• FAIL: exit code non-zero, report test failure summary

Do not run UAT (npm run uat) here — that is a pre-release gate, not a daily development check. Mention that it should be run before tagging a release.

Section 7: Circular Skill Call Detection

Search all SKILL.md files in agentic/code/ for potential circular calls:

For each SKILL.md:

1. Check if the associated command in definitions.ts has executedViaSkillRunner: true
2. If yes: search the SKILL.md for aiwg <command-name> in any bash block or instruction text
3. Flag any matches as circular call violations

Report Format

AIWG Dev Doctor
Run at: <timestamp>
Repo: <working directory>

SECTION 1 — Structure Integrity
  PASS  agentic/code/addons/ (8 addons, all have manifest.json + README.md)
  PASS  agentic/code/frameworks/ (5 frameworks, all have manifest.json)

SECTION 2 — Orphan Detection
  PASS  no orphaned skills
  FAIL  aiwg-utils: soul-blend listed in manifest but skills/soul-blend/SKILL.md missing
  PASS  no orphaned agents
  PASS  no missing agents
  PASS  no orphaned rules

SECTION 3 — Placement Violations
  PASS  no placement violations found

SECTION 4 — @file References
  4a .aiwg/ refs:   PASS (all normalized)
  4b bare AIWG refs: WARN — 2 legacy refs (add $AIWG_ROOT/ prefix)
  4c .claude/ refs: PASS (none found)
  WARN  agentic/code/addons/my-addon/skills/my-skill.md
        agentic/code/... (bare ref) → add $AIWG_ROOT/ prefix

SECTION 5 — TypeScript Compilation
  PASS  tsc --noEmit: 0 errors

SECTION 6 — Test Suite
  PASS  npm test: 142 passing, 0 failing

SECTION 7 — Circular Skill Calls
  PASS  no circular skill calls detected

Overall: FAIL — 2 issues found

Blocking issues:
  1. [Section 2] aiwg-utils/skills/soul-blend/SKILL.md missing
     Action: Create the SKILL.md or remove soul-blend from manifest.json
  2. [Section 4] non-normalized @.aiwg/ reference in my-addon/skills/my-skill.md
     Action: Either remove the reference, replace it with a normalized path,
             or add the path to the framework's memory.creates in manifest.json

Notes:
  - UAT (`npm run uat`) not run — run before tagging a release
  - 8 addons, 5 frameworks validated

Examples

Example 1: Clean repo

User: "run dev doctor"

Output:

AIWG Dev Doctor — 2026-04-01

Structure:        PASS (8 addons, 5 frameworks)
Orphans:          PASS (no orphaned or missing components)
Placement:        PASS (no violations)
.aiwg/ refs:      PASS
TypeScript:       PASS (0 errors)
Tests:            PASS (142 passing)
Circular calls:   PASS

Overall: PASS — repo is in a good state
Note: Run `npm run uat` before tagging a release.

Example 2: Multiple issues

User: "is the repo in a good state before I make a PR?"

Output:

AIWG Dev Doctor — 2026-04-01

Structure:        PASS
Orphans:          FAIL — 1 missing skill, 1 orphaned rule
Placement:        FAIL — 1 violation in .claude/skills/
.aiwg/ refs:      PASS
TypeScript:       PASS
Tests:            PASS
Circular calls:   PASS

Overall: FAIL — 3 issues found

1. [Orphans] my-addon/skills/my-skill/SKILL.md missing (listed in manifest)
   → Create the file or remove from manifest.json
2. [Orphans] my-addon/rules/old-rule.md exists but not in RULES-INDEX.md
   → Add an entry to rules/RULES-INDEX.md or delete old-rule.md
3. [Placement] .claude/skills/scratch-skill/ has no source in agentic/code/
   → Move to agentic/code/addons/<addon>/skills/scratch-skill/ or delete

Example 3: Focused check

User: "just check for placement violations"

Action: Run Section 3 only.

Output:

Placement Violation Check

Checked: .claude/skills/, .claude/agents/, .claude/commands/, .claude/rules/
         .github/agents/, .github/prompts/, .github/instructions/
         .cursor/skills/, .cursor/agents/

Result: PASS — no placement violations found
All deployed files have corresponding source in agentic/code/.

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/skill-placement.md — Placement violation definitions
• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/no-circular-skill-calls.md — Circular call detection
• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/component-completeness.md — Completeness requirements
• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/addon-boundaries.md — Source vs project output boundary
• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/rules/aiwg-dir-reference-contract.md — Normalized .aiwg/ reference contract
• @$AIWG_ROOT/agentic/code/addons/aiwg-dev/skills/validate-addon/SKILL.md — Per-addon validation
• @$AIWG_ROOT/tools/cli/doctor.mjs — Runtime doctor (end-user installation health, not dev structure)