/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>