thoughtsre Claude Code Workflows

⚙ Configure

Teach the workflows about your project.

• Run /init-workflows. It fingerprints the repo and writes .claude/project-profile.json — test commands, infra, GitHub labels, docs, models.
• The sprints hard-fail until this file exists — there are no silent defaults.
• Commit the profile so your whole team shares one configuration.

1 Spec the MVP

Write the MVP or phase as a single GitHub specs issue.

• Capture the scope, deliverables, and acceptance criteria — this issue is the source of truth the whole phase is built from.
• Use the /think skill to reason through scope, tradeoffs, and acceptance criteria with Claude before writing the issue — it's a read-only discussion mode, so nothing gets changed while you shape the spec.
• Titled so the milestone is clear, e.g. [MVP 1] ….

2 Break down into sub-issues

Split the spec into small, dependency-ordered pieces.

• The spec-breakdown agent reads the specs issue and your design docs, then proposes granular sub-issues (each ~a single focused session).
• It also specifies the dependencies between issues — which sub-issue is blocked by which — and, on your approval, records them on GitHub as sub-issue links and blocked-by relationships. Together these form the dependency graph the Implement phase schedules against.
• Shallow trees are preferred, so more independent sub-issues can be delivered in parallel.

3 Update docs — optional

Capture any design upgrades or ADRs in main before implementation starts.

• Spec'ing and breaking down the MVP often surfaces decisions worth recording — new or revised architecture, conventions, or trade-offs.
• Write these up and merge them into main before implementation begins, so every sub-issue — and the milestone worktree, cut fresh from main — starts from the same up-to-date source of truth.
• See the docs structure guide for what belongs where — project guide, decision records, or user docs.

🌳 Create the milestone worktree

A one-time, manual step per milestone — before the delivery loop can start.

• /feature-sprint never creates this worktree itself — it hard-requires running from inside one, on a non-default branch with a clean tree.
• From the main repo checkout: git worktree add ../repo-mvp1 -b mvp1 main — creates a sibling checkout on a fresh mvp1 branch off main.
• cd into it, then run /feature-sprint <specs#> from there — every sub-issue's per-issue worktree, and the final milestone branch, build on top of this one.

1 Plan

A planner and an architect negotiate an approved plan for the sub-issue.

• Planner drafts → architect approves or returns revisions, up to 6 rounds. Ambiguity is decided autonomously.
• Grounded in your project guide and decision records; written to .claude/plans/issue-N.md.

2 Implement

Build strictly to the plan — no redesign, no scope creep.

• Works on an isolated branch, cut fresh off the up-to-date base, and runs the unit suite to green before committing.
• Never pushes, opens a PR, or merges — the workflow owns delivery.

3 Review

The /code-review rubric, applied to the diff.

• Checks correctness, security, faithfulness to the design, and reuse/simplification.
• HIGH + MEDIUM findings block the merge and are fixed in up to 3 passes. LOW is reported, not blocking.

4 Test

The authoritative gate before merge.

• The unit suite runs always. The full / integration suite runs when the change needs it and the profile enables infra.
• Up to 3 fix-and-retest attempts before the sub-issue is handed to Escalate.

5 Merge

Deliver the change and close the issue — then the loop pulls the next one.

⚠ Escalate — fail-soft

A failure never stops the run.

• Any failure at review, test, or merge gets one max-effort fixer pass — rebase a conflict, or fix the root cause — then re-enters at Test.
• If it still fails, the sub-issue is stranded (a diagnosis comment + a best-effort label) and the sprint keeps delivering everything else.
• Stranded work returns on the next run. (Feature: the stranded issue's dependent subtree waits with it.)

1 Open the PR

Raise the milestone → default branch pull request.

• By now every sub-issue has merged and the sprint's automated whole-diff milestone review is clean — the milestone branch is “ready.”
• Run the /pr skill to open the PR; it links and auto-closes the related issues.

2 Manual UAT

Put on the user's hat and exercise the MVP end-to-end.

• Clear the context first — start fresh so the review isn't coloured by the implementation session.
• Run manual user-acceptance testing against the running app: walk the MVP's flows as a real user would and confirm the acceptance criteria hold.

3 PR review

A human-gated code review of the whole PR.

• Review the PR with the /review skill; fix any issues it surfaces before merging.

4 Bug-fix sprint — optional

Clear anything UAT or review turned up.

• If UAT or the PR review filed bugs as GitHub issues, run /bug-fix-sprint to deliver them through the Implement loop.
• Once the PR is clean, merge it — the MVP is shipped, and it's back to Design for the next MVP / phase.