dev-doctor

namespace	aiwg
name	dev-doctor
description	Run a development-focused health check on the AIWG repository structure
platforms	["all"]

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)