--- 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//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): ```bash 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 `@` 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: ```bash 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: ```bash 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 ` in any bash block or instruction text 3. Flag any matches as circular call violations ### Report Format ``` AIWG Dev Doctor Run at: Repo: 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//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)