--- name: flow-mode description: Takes a feature from idea to merged PR through a spec, a plan, a review by a different model, implementation, a real run, a code review and a journal entry. Use when the user says "flow mode" or "flow-mode", or asks to build a feature "the usual way" or "with the flow". Do not use for small fixes unless the user asks. --- # Flow mode How a new feature goes from an idea to a merged PR. Each step ends in a commit or a decision the user can see. Skip a step only when the user says so, or when it plainly can't apply (a docs-only change needs no real run), and say which you skipped and why. Before starting, read the project's agent instructions for where specs and plans live, which checks CI runs, how to run the product for real, and what costs money. If they don't say, ask once and offer to write the answer down. This skill uses `sol-loop`, `file-pr` and `babysit-pr` from [tstack](https://github.com/t3dotgg/tstack). `unslop` and `working-with-agents` are optional. If one is missing, say so and do that step by hand. Don't skip the review. ## 1. Spec, with the user Read the code before asking anything. Then bring the user only the decisions that are theirs, as multiple-choice questions with a recommended option first. Write the spec to the project's specs folder, or `docs/specs/--design.md` if it has none: why, what exists, decisions, known traps, checks, non-goals. Mark each decision **(user)** or **(my call)**. Correct a past spec in place when the code proves it wrong, and say so. ## 2. Plan Write the plan beside the spec: goal, architecture, global constraints, review focus, then tasks. Each task names its files and how it is checked, and ends in a commit. ## 3. A different model reviews the plan Before any code, have a different model review the spec and plan against the actual code. Read-only. Ask for findings with file:line evidence, ordered by importance, and for the scope the plan doesn't need. Check each finding yourself. Fold the ones that hold into a "Changes from review" section that wins over the tasks below it, update the spec to match, and push back with evidence on the rest. Branch off the default branch, then commit the spec and plan. ## 4. Implement, task by task Tests first where they fit, then the code, then the service's own checks, run the way CI runs them. A subset can pass while CI fails. One commit per task. Fix the case that happened, not every case that could. Keep generated files in step. For anything that claims to hide or filter data, test against a captured real payload, not a fixture written from what you assume the shape is. ## 5. Prove it in real use Pick the cheapest run that actually exercises the change: an end-to-end suite for logic, the real system for anything a mock can't show. Ask before the first thing in a session that costs money. Try a cheap smoke test before paying for a build when one can prove the same path. Record times, resource use and comparison output in the spec's "Checked" section. Tear down what you started and restore anything you set aside. ## 6. Code review Run `sol-loop` on the diff from the default branch. Fix real findings with the smallest change and prove each fix. Decline the rest with a reason. ## 7. PR File it with `file-pr`, with the description run through `unslop` if you have it. Say what changed, how it was proven, and what's left for the user. Leave the merge to the user unless they said to merge. ## 8. Merge, when asked Watch the PR with `babysit-pr`. Before calling it ready, read every check's result yourself, including the ones a path filter only sometimes runs. A mergeable PR with a red check is not ready. Rebase onto the latest default branch when another PR landed first, rerun the affected checks on the combined code, and push with `--force-with-lease`. Merge once every check is green, then pull the default branch, delete the branch, and stop watching. ## 9. Journal If the project keeps a journal, write the entry: what happened, what was learned, an honest self-assessment, how it felt. Say so in one line. `working-with-agents` sets one up. ## Always the user's Production changes, environment and secret changes, pushing images or releases, merges unless told otherwise, and new spend. Commit and push only on this flow's branch.