A skill does not appear
Confirm the matching adapter exists. Codex and GitHub Copilot use
.agents/skills/; Claude Code uses .claude/skills/; OpenCode can use either
tree. Do not add a duplicate .opencode/skills/ copy. 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 in both planning files. The build plan must contain real feature-sized checkbox items, not examples such as Feature one.
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.