A skill does not appear
Confirm the matching adapter exists. Codex, GitHub Copilot, and Google
Antigravity use .agents/skills/. Claude Code uses .claude/skills/, while
OpenCode can use either tree. Do not add .opencode/skills/ or an
Antigravity-specific skill tree. Restart Claude Code if the adapter was
installed while the session was already open.
Update reports managed file conflicts
Run npx create-ai-blueprint@latest update --dry-run and review every listed path. A conflict means the file differs from its recorded Blueprint version, or a legacy install has no baseline for it. Run the normal update interactively to approve backup and replacement, or pass --force in non-interactive use only when replacement is intentional. Project plans, context, history, AGENTS.md, and CLAUDE.md are outside the updater’s managed boundary.
Overview refuses to run
Replace template placeholders with real project decisions and feature-sized outcomes. Overview formats clear feature lists into checkboxes automatically. If the build plan is missing or only a stub, approve its proposed checklist from the project plan before continuing.
Implement says there is no spec
Run feature for planned work, fix for an unplanned bug, or rollback for a completed feature reversal. Review the resulting current-feature.md, then implement.
Git blocks the workflow
Blueprint expects a Git repository and a matching feature/, fix/, or
rollback/ branch. Resolve unrelated working-tree changes before starting an
automated run. Never discard changes merely to satisfy the workflow.
Rollback reports a dependency or patch conflict
Read the later commit and shared path named in the report. Do not force the patch, reset the repository, or silently include another feature in the rollback. Either approve a compatibility edit already covered by the rollback spec or stop and plan the dependent reversal separately.
Build passes but behavior is wrong
Run check against the feature’s done-when criteria. Use browser, CLI, or API evidence that exercises the actual behavior instead of relying on compilation alone.
Verify and GitHub run different checks
Run doctor to confirm whether AGENTS.md, the project Verify command, and .github/workflows/verify.yml agree. Then run $ci or /ci to review and align them. Existing workflows are preserved, and any change to existing CI requires review.
If Verify fails locally, fix the failing typecheck, test, or build command. Do not remove a legitimate check merely to make the GitHub workflow green.
The GitHub check is not required before merge
/ci creates or aligns the local workflow, but it does not push it or change repository settings. Publish the workflow only with explicit approval. Requiring the resulting check is a separate GitHub ruleset choice.
Setup still feels wrong
Run doctor for a read-only health report. It checks files, adapters, commands, optional verification and CI alignment, plan readiness, overview freshness, and common drift.
npm reports EBADDEVENGINES in a pnpm project
If the error says the required package manager is pnpm but the current one is
npm, the project rejected npx before Blueprint ran. Keep the project policy
and run pnpm dlx create-ai-blueprint@latest update instead.
The update runs an older version or has no adapter picker
Compare the printed version with the published releases.
Cached package resolution may be stale. Use an explicit version, such as
pnpm dlx create-ai-blueprint@1.11.0 update, to run that release. The adapter
picker requires 1.8.0 or newer, an interactive terminal, and no adapter flags
or --yes. Decline any offer from an older updater to downgrade a newer global
CLI. See update recovery.