Doctor

What doctor checks

• Required Blueprint files and context wiring
• blueprint/config.json validity and supported settings
• Logical adapter selections, including Google Antigravity
• Compatible .agents/skills/ and .claude/skills/ trees without duplicate tool-specific skills
• Project commands and coding-standard fit
• Alignment between AGENTS.md, the project Verify command, and GitHub workflow
• Root README placement and ignore rules
• Plan readiness and overview freshness
• Current feature state and git drift
• Findings-ledger and independent-review file health
• Claude Code’s imported-file size and installed skill-description size
• Generated dashboard activity in blueprint/.state/run.json

When to run it

Run doctor after onboarding, after moving Blueprint files, when the dashboard reports malformed activity, or when a skill cannot find expected project state.

For Claude Code, Doctor reports file-size diagnostics for automatic imports and skill descriptions. The current layout imports only AGENTS.md at startup and lets explicit skills load project context on demand. Doctor flags legacy direct imports of project-overview.md, current-feature.md, coding-standards.md, or ai-interaction.md, gives the exact lines to remove, and points to /context all for Claude’s live token breakdown. It also reports the overview size and flags a file at or above 20,000 bytes so it can be regenerated before Feature loads it. File sizes are not presented as token estimates.

Result

Doctor classifies findings and points to the corrective workflow. It recommends $ci or /ci when the documented Verify command and automatic workflow disagree. Missing optional CI alone is informational.

Doctor is diagnostic by default. If the generated dashboard activity file is malformed, it explains that resetting it removes only the last-command record and offers to remove that exact file after approval. The next tracked Blueprint command recreates it through the packaged activity helper. The helper validates the complete state before replacing the file, so invalid updates cannot corrupt the previous valid record. Doctor never repairs project files automatically, commits, or changes the application.

Preserved project guidance

Doctor checks existing AGENTS.md for substantive proportional-engineering guidance, accepting equivalent customized wording. Missing or incomplete guidance is a warning, not a setup blocker. Updates preserve AGENTS.md, so merge only the missing guidance manually; Doctor never replaces the file. Keep existing project rules and local-only visibility intact.