vincy-cheng/dev-flow
A self-contained workflow for planning, building, verifying, and shipping features and fixes.
Use when designing or exploring a feature or fix before building it — turn an idea into a validated design and spec through collaborative dialogue. Runs standalone in any repo, or as the engine of dev-flow step 1 (invoked by the new-feature command).
Use whenever the user wants to commit staged or current changes ("commit this", "make a commit", "save progress", "commit the work"). Writes a Conventional Commits message from the diff and commits. Can run standalone or as part of dev-flow step 5 (per-task commits during TDD execution). NEVER mentions or attributes any AI model, assistant, or tool in the commit message or any trailer — the commit reads as if the human author wrote it.
Use whenever the user wants to create, open, file, or draft a GitHub issue — "create an issue for X", "file a bug", "open an issue", "track this", "log this", or describes a feature/bug to track. Also when turning a conversation, bug report, or feature idea into a tracked issue. This is step 4 of the dev-flow workflow (brainstorm → spec → plan → **create issue** → execute → PR → merge), so it also triggers at the end of planning once a plan doc exists. Triggers on any mention of creating/filing/opening an issue, even without the word "issue". Works in any repo with the gh CLI.
Use to generate or update a repo's agent-facing docs — a layered progressive-disclosure tree under docs/agents/ (a tiny always-load index, core maps for architecture and dev-ops, plus dynamic concern maps discovered from the project — testing, API, deployment, database/SQL, auth, etc. — and optional deep/ detail files). Triggers on "document this repo", "generate agent docs", "update agent docs", "document this repo for agents", or any request for architecture/testing/API/database docs aimed at AI coding agents. Runs standalone in any repo; not part of the dev-flow step sequence.
Use to execute a dev-flow plan task by task. This is step 5 of the dev-flow workflow — work the plan's tasks with TDD (failing test → implement → green → commit per task), updating the state file as you go. Two modes: inline (default, runs in this session) or subagent (dispatches a fresh implementer subagent per task, for isolation on larger work). Can be invoked standalone if a plan and state file already exist.
Start or resume a feature or fix through the complete dev-flow pipeline. Use when asked to build a feature, implement a change, or resume a dev-flow run.
Use when the user asks to create / brainstorm an idea, scaffold an idea folder, or "put relevant docs" for a product/concept — creates a structured idea folder under ideas/ with a fixed set of five self-contained markdown docs (six when the user opts into a cost.md breakdown), including a draft plan that can feed /new-feature. Not part of the step pipeline.
Use to open a pull request for a feat or fix branch — dev-flow step 9 (after doc-fix, before the manual merge). Pushes, drafts the PR body (issue link, spec/plan summary, closing keyword), shows it for confirmation, opens with gh pr create targeting dev, links the issue via `Closes
Use when turning an approved spec or settled requirements into an implementation plan — bite-sized ordered tasks with files, TDD shape, and a flow chart. Runs standalone in any repo, or as the engine of dev-flow step 3 (invoked by the new-feature command).
Use to review a feat or fix branch before opening a PR — a judgment review gate checking spec coverage, plan coverage, obvious issues (bugs, security smells, leftover, naming), and maintainability with a clean-code pass (structure, coupling, naming, complexity, duplication, functions, conditionals, comments, code smells) against the spec and plan. This is dev-flow step 7 (after the step 6 test gate, before doc-fix). Spawns a fresh independent reviewer subagent (no author bias) that runs the review and returns a verdict. Also runs standalone on any branch ("review this", "review the branch", "review my work"). Doesn't run the test suite (that's dev-flow:test) or replace human PR review.
Use when implementing any feature or bugfix test-first, before writing implementation code — red-green loop, seams, test honesty. Runs standalone in any repo, or as the TDD engine of dev-flow step 5 (invoked by execute-tasks per task).
Use to run a fresh-subagent test gate on a feat or fix branch — full suite + lint plus a test-honesty scan (tests that assert nothing, mock the thing under test, tautologies, pass regardless of code). This is dev-flow step 6 (between execute and review). Spawns a fresh tester subagent (no author bias) that runs the suite itself and returns a green/red verdict; red sends the work back to execute. Also runs standalone on any branch ("test this branch", "run the test gate"). Does not review code — that's dev-flow:review (step 7).
Use to summarize what's new in a repo — recent shipped work AND current codebase state vs. its docs. Triggers on "what's new", "what changed recently", "summarize recent work", "catch me up on this repo". Returns a view (nothing written): history from git log + gh PRs/issues, plus a doc-drift check (do the docs match the code). Not a changelog file — an on-demand summary.