calmtechltd/calm-craft

Surface the open questions in the current work and put them to the user as structured choices. Use whenever the user says "ask questions", "ask me questions", "what do you need to know", "what's still open", "any open questions?", "quiz me on this", "check with me before you build", or otherwise invites being asked rather than guessed at — mid-design, before implementing, or when the conversation has accumulated unresolved decisions. Also use when the user wants the open questions on the current branch or plan reviewed. Never invents answers or options.

Turn a design document and its specs into a chunked implementation plan an agent can execute one reviewable pass at a time, with dependencies, acceptance criteria, and explicit out-of-scope fences. Use when the user says "turn this design into a plan", "break this into chunks", "write an implementation plan", or before starting a large feature. Plans only — never implements.

Find and clean up merged branches, stale worktrees, and fully-merged Graphite stacks. Use whenever the user wants to tidy up branches or worktrees — "clean up my branches", "delete merged branches", "I've got too many branches", "prune worktrees", "what's safe to delete", "did this ever get merged", or after PRs land and they ask what's left to clear out. Handles squash-merges (which git branch --merged silently misses), Graphite stacks, and worktrees left behind by Claude Code and Codex/Cursor sessions. Always reports before deleting, separates what is provably merged from what needs a decision, and never touches remote branches.

Review this branch's committed changes against the merge-base for functional bugs, permission and tenancy holes, and risky code paths, like a review bot would, before anyone else sees it. Use when the user says "review my branch", "find issues in my changes", "what could break here", or before opening a pull request. Reports only — never edits product code and never runs the gates.

Fix a bug by writing a failing test that reproduces it first, then fixing the code until green, leaving a durable regression test with the bug narrative in its file header. Use when the user says "write a regression test", "red test first", "fix this bug properly", "make sure this never breaks again", or when fixing incorrect behaviour with no test covering the broken path.

Implement CodeRabbit review fixes from a completed triage under .active/coderabbit-pr-*-review/, using parallel background subagents for independent fix batches. Stays local — does not commit, push, submit, or resolve GitHub review comments. Use after coderabbit-review-triage when the user wants the obvious fixes applied in the worktree. Use coderabbit-review-implement-all when they also want those fixes published and the review threads resolved.

Publish CodeRabbit review fixes and resolve the review. Runs coderabbit-review-implement first if the local fixes are not done, commits and publishes them to the current PR, resolves inline threads with GraphQL, and when necessary posts one PR-level @coderabbitai resolve summary for completed review-body-only findings. Never resolves before the remote has the fixes. Use only when the user explicitly asks to implement all, fix and resolve, or ship the review and resolve.

Download CodeRabbit PR review feedback, save raw comments under .active/, verify findings against the codebase, and produce a triage breakdown of obvious fixes, skips, and items needing user input. Fetch via GitHub GraphQL review threads — never GitHub MCP addComment, never gh pr comment, never REST POST of new PR comments. Use when the user wants to process a CodeRabbit review, triage PR bot comments, or prepare review feedback before implementing fixes. Never invents verdicts.

Check a diff or directory against the decisions in .engineering/conventions.yaml, reporting only violations the linter cannot catch. Use when the user says "check this against our conventions", "does this follow our standards", "audit this code", or before opening a pull request on a repo with recorded conventions. Reports only — never edits code.

Interview the user through the code-convention question bank, record the decisions in .engineering/conventions.yaml, and generate lint config plus ambient agent rules from them. Use when the user says "decide our conventions", "set up coding standards", "we keep arguing about style", "write our conventions down", or after engineering-setup on a repo with no recorded conventions.

A convention decision changed — find the code that violates it and fix it in reviewable batches, then tighten the lint rule from warning to error. Use when the user says "we changed the export rule", "migrate the code to match", "we decided to ban X, go fix it", or after conventions-decide reports existing violations blocking a rule from being an error.

Periodic review of recorded conventions — surface defaults nobody ever examined, rules a linter could enforce but doesn't, rules riddled with ignores, and drift between the decisions file and the generated config. Use when the user says "review our conventions", "are our standards still right", "what conventions did we never actually decide", or on a periodic cadence. Proposes; changes nothing.

Detect this repo's toolchain and write .engineering/config.yaml, the configuration every other skill in this plugin reads. Use when first installing the engineering-system plugin, when the user says "set up the engineering system", "bootstrap specs", "configure the plugin", "my test command changed", or when any other skill reports that .engineering/config.yaml is missing or stale.

Run the same quality gates CI runs — types, lint, dead code, tests — and fix what fails until the branch would pass. Then mark the current branch's GitHub PR ready for review if it is still a draft. Use only when the user explicitly says "ready for PR", "run the checks", "is this ready to ship", or "will CI pass". A bare implementation, commit, submit, PR update, or PR opening request does not run this suite.

Complete the incomplete behaviours in current scope — read the scoped specs, build a queue, and keep working across turns until the definition of done is satisfied. Use when the user says "run the implementation plan", "continue the plan", "finish the scoped work", "complete the incomplete behaviours", "ship B4", or names a chunk ID.

Finish the current implementation plan — one chunk per pass, then the next, across turns until the plan is done. Use when the user says "run them all", "finish the plan", "run-implementation-plan-all", or starts /goal without naming a single chunk.

Audit a feature spec against the test suite to find which behaviours, invariants, decision-table rows, and flow transitions have tests and which do not. Use when the user says "what's untested here", "which parts of this spec have tests", "where should I focus testing", or before trusting a spec's implemented badges. Pairs with spec-audit-drift, which asks whether the spec matches the code.

Audit a feature spec against the actual implementation to find where behaviours or user-flow contracts no longer match the code. Use when the user says "is this spec still accurate", "check the spec against the code", "I think this wizard bypasses the documented flow", or before relying on a spec that hasn't been touched in a while. Reports only. Pairs with spec-assess-coverage, which asks whether tests exist.

Author a feature spec by working backwards from existing code and tests, capturing what the product actually does today including a user-flow contract for journeys that already exist. Use when the user says "spec this existing feature", "document how this works", "we need a spec for X that's already built", or when backfilling a spec estate on an existing codebase. Pairs with spec-author-greenfield for design-first authoring.

Author a feature spec design-first, for something not yet built, including a user-flow contract when a journey warrants one. Use when the user says "let's spec this before we build it", "capture the design for this feature", "think through the edge cases first", or is planning a new feature and wants intent, paths, and open questions recorded before code. Pairs with spec-author-from-impl for features that already exist.

Write tests from a feature spec, treating the spec and its flow contract as the source of truth, stubbing pending tests where implementation is missing and halting when code and spec disagree. Use when the user says "write tests from this spec", "fill the coverage gaps", "prove this wizard works", or after spec-assess-coverage identifies what is untested.

Sweep every spec in the estate for maintenance debt — partial behaviours with no ticket, ageing future behaviours, roll-up statuses that disagree with their behaviours, long-standing open questions, and modules with no specs at all. Use when the user asks "what state are our specs in", "review the spec estate", "which open questions are blocking work", or on a periodic cadence. Reports only.

Read an issue thread or pull request review discussion and propose what the governing spec should absorb from it — answered open questions, new edge cases, decisions, defects, and scope changes. Use when the user says "read the comments on issue 42", "what came out of that discussion", "harvest the PR thread", "catch the spec up with what people said", or after a long conversation on a tracked item. Proposes only — never edits the spec.

Update a feature spec when work changes its state — a partial behaviour ships, a future behaviour is prioritised, an open question is answered, or a journey changes. Use when the user says "this shipped, update the spec", "we decided X, record it", "mark B4 done", or as part of a pull request that changes documented behaviour. Pairs with spec-audit-drift to verify the update is honest.

Search the existing spec estate for overlap, conflict, or existing coverage before authoring a new spec, then propose where the new one should live and what it should cover. Use when the user says "this isn't specced", "we need a spec for X", "is there a spec covering Y", or before starting any new spec. Pairs with spec-author-greenfield and spec-author-from-impl for the writing.

Storyboard and improve a spec-governed product journey using an Apple-inspired UX review lens and authoritative flow contracts. Use for "review this flow", "improve this wizard", "storyboard this journey", or enhancing the UX of an existing multi-step feature before implementation.

Classify an inbound bug report against the relevant spec — confirmed bug, expected behaviour, spec gap, spec drift, out of scope, or no spec exists — before anyone changes code. Use when a user, support ticket, or stakeholder reports unexpected behaviour and you need to decide what kind of problem it is. Pairs with bug-regression-red-green for confirmed bugs.

Open the local CalmCraft visualizer for a spec estate or branch review. Use when the user asks to browse, visualize, search, or review the specs in a checkout or worktree.

Write or update the current branch's GitHub PR title and description via the gh CLI, grounded in the branch diff and commits, preserving existing ticket references. Use for a full rewrite before or after opening a PR, an incremental sync after new commits, or a title-only fix — "update my PR", "refresh the PR description", "sync PR with my changes", "fix the PR title", "write the PR description", "tidy up this PR". This skill is the authority on PR title and body format.

Decide whether a test is worth writing, and at which layer, before adding one. Use when writing, generating, or filling tests; when the user says "don't test this", "skip tests", "that's too many tests", or "over the top"; and whenever an agent is about to add *.test.*, *.spec.*, or component tests. Prefer fewer tests that lock behaviour over coverage padding.