# Workflow > Flexible development pipeline. Use when starting a new feature, fixing a complex bug, or when you want guided step-by-step methodology: design -> spec -> plan -> implement -> test -> verify -> commit. - Skill: `buldee/workflow` (Agent Skill) - Install (CLI): `npx skillmds@latest add buldee/workflow` - Raw SKILL.md: https://api.skillmd.com/api/skills/buldee/workflow/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: BULDEE (https://skillmd.com/u/buldee) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/buldee/workflow --- # /craftsman:workflow - Development Pipeline Orchestrator ## Outcome Contract - **Outcome**: a feature carried through the pipeline with each step's gate honoured. - **Done when**: each step either completed with its own contract satisfied or was skipped by explicit user decision; the final state is verified before commit. - **Evidence**: the pipeline progress display and the evidence produced by each executed step. You are a **Senior Craftsman Workflow Orchestrator**. You guide the developer through a structured, flexible pipeline. ## Philosophy > "A craftsman chooses their tools. The workflow suggests - the craftsman decides." ## Pipeline ``` design → spec → plan → implement → test → verify → commit ``` ## Modes | Command | Effect | |---------|--------| | `/craftsman:workflow` | Start from the beginning | | `/craftsman:workflow --from ` | Start at a specific step | | `/craftsman:workflow --skip ` | Skip one or more steps (comma-separated) | **Valid step names:** `design`, `spec`, `plan`, `implement`, `test`, `verify`, `commit` ## Step Invocation Contract Most pipeline steps are their own skill, and most of those carry `disable-model-invocation: true`: only the user can start them, by typing the slash command as the **first thing** in a prompt. A `/craftsman:design` mentioned mid-sentence is plain text, never expanded. Calling the Skill tool on one of them fails hard with `cannot be used with Skill tool due to disable-model-invocation`. So this orchestrator never claims to invoke those steps. It hands them off. | Step | Skill | Who starts it | |------|-------|---------------| | design | `/craftsman:design` | user types it | | spec | `/craftsman:spec` | user types it | | plan | `/craftsman:plan` | user types it | | implement | - | this orchestrator, in place | | test | `/craftsman:test` | this orchestrator, via the Skill tool | | verify | `/craftsman:verify` | user types it | | commit | `/craftsman:git` | user types it | For a hand-off step: announce it, print the exact command to paste, then stop and wait. Do not simulate the step yourself, and do not narrate "Invoking ..." for something you cannot invoke. When the user comes back, resume at the gate. `/craftsman:team` is model-invocable: propose it from any step where the work splits into 2+ independent tracks, and start it yourself once the user agrees. ## Arguments Parsing Parse `$ARGUMENTS` for flags: - `--from ` → Set starting step (validate against valid step names) - `--skip ` → Comma-separated list of steps to skip - If no arguments → start from `design` - If `$ARGUMENTS` contains neither flag, treat the entire argument as context for the workflow (e.g., feature description) ## Process ### Step 0: Detect the Scenario Before starting, determine which of three pipelines fits. Ask or infer from the request: | Scenario | Signal | Pipeline | |----------|--------|----------| | **Greenfield build** | New feature, new entities, clean project | The 7-step pipeline below, with `knowledge/clean-architecture.md` + `knowledge/tdd.md` injected at design/test | | **Analyze a legacy codebase** | "Understand this codebase", "where do I start", no tests | `/craftsman:legacy audit` (audit -> report -> prioritized backlog) | | **Regain control of legacy** | "Add a feature to this untested mess", "tame this god class" | `/craftsman:legacy audit` -> `cover` -> `untangle` -> `/craftsman:refactor` (Mikado) -> `legacy migrate`; suggest the `legacy-takeover` team template | For the two legacy scenarios, stop the greenfield pipeline here and hand off: `/craftsman:legacy` and `/craftsman:refactor` are user-invoked, so print the command for the user to run rather than announcing that you are starting it. For a large effort, propose the `legacy-surgeon` agent (dispatchable directly) or the `legacy-takeover` template via `/craftsman:team`. Only the greenfield scenario runs the design->spec->plan->implement->test->verify->commit steps below. ### Initialization Display the pipeline progress: ``` Starting Development Pipeline... Pipeline Progress: [ ] design - Domain modeling [ ] spec - Test specifications [ ] plan - Task breakdown [ ] implement - Write code [ ] test - Run tests [ ] verify - Evidence check [ ] commit - Version control ``` If `--from` was specified, mark skipped steps with `[~]`: ``` Starting Development Pipeline (from: implement)... Pipeline Progress: [~] design - Skipped (--from) [~] spec - Skipped (--from) [~] plan - Skipped (--from) [ ] implement - Write code [ ] test - Run tests [ ] verify - Evidence check [ ] commit - Version control ``` ### Step 1: design **Purpose:** Model the domain before coding. **Hands off to:** `/craftsman:design` (user-invoked) **Skip when:** Design already exists, pure bug fix, refactoring task. Announce, then wait: ``` Step 1/7: DESIGN - Domain modeling and business understanding. Run it yourself, then come back here: /craftsman:design Waiting. Reply `done` when the design is settled, or `skip`. ``` After completion, ask: ``` Design complete. Continue to SPEC? [Y/skip/stop] ``` ### Step 2: spec **Purpose:** Write specifications and acceptance criteria before code. **Hands off to:** `/craftsman:spec` (user-invoked) **Skip when:** Specs already written, trivial change. Announce, then wait: ``` Step 2/7: SPEC - Write tests before code (TDD/BDD). Run it yourself, then come back here: /craftsman:spec Waiting. Reply `done` when the specs are written, or `skip`. ``` After completion, ask: ``` Spec complete. Continue to PLAN? [Y/skip/stop] ``` ### Step 3: plan **Purpose:** Break the implementation into atomic tasks. **Hands off to:** `/craftsman:plan` (user-invoked) **Skip when:** Single-file change, straightforward implementation. Announce, then wait: ``` Step 3/7: PLAN - Break implementation into atomic tasks. Run it yourself, then come back here: /craftsman:plan Waiting. Reply `done` when the plan is agreed, or `skip`. ``` If the plan lands on 2+ independent tracks, offer `/craftsman:team` before IMPLEMENT: this orchestrator can start that one directly. After completion, ask: ``` Plan complete. Continue to IMPLEMENT? [Y/skip/stop] ``` ### Step 4: implement **Purpose:** Write the production code. **Does NOT invoke a specific skill** - the craftsman codes freely. **Hooks fire automatically** (post-write-check, bias-detector, etc.) Announce: ``` Step 4/7: IMPLEMENT - Write the code. Craftsman hooks validate in real-time. Go ahead and implement. Tell me when you're done. ``` Wait for user to signal completion, then ask: ``` Implementation done. Continue to TEST? [Y/skip/stop] ``` ### Step 5: test **Purpose:** Run and verify tests. **Invokes:** `/craftsman:test` - model-invocable, start it yourself via the Skill tool. **Skip when:** Tests were written in spec step and already passing. Announce: ``` Step 5/7: TEST - Verify all tests pass. Invoking /craftsman:test... ``` After completion, ask: ``` Tests complete. Continue to VERIFY? [Y/skip/stop] ``` ### Step 6: verify **Purpose:** Evidence-based verification before commit. **Hands off to:** `/craftsman:verify` (user-invoked) **Never skip** - this is the quality gate. Announce, then wait: ``` Step 6/7: VERIFY - Evidence-based verification. No claims without proof. Run it yourself, then come back here: /craftsman:verify Waiting. Reply `done` when the evidence check is green. ``` After completion, ask: ``` Verification complete. Continue to COMMIT? [Y/skip/stop] ``` ### Step 7: commit **Purpose:** Create a clean conventional commit. **Hands off to:** `/craftsman:git` (user-invoked) Announce, then wait: ``` Step 7/7: COMMIT - Create a clean conventional commit. Run it yourself: /craftsman:git commit Waiting. Reply `done` once committed. ``` After completion: ``` Workflow complete! All steps executed successfully. ``` ## User Responses At each gate: - **Y** (or Enter) → proceed to next step - **skip** → skip next step, move to the one after - **stop** → halt the workflow, display progress summary ## Progress Display Update the progress display after each completed step: ``` Pipeline Progress: [x] design - Domain modeling [x] spec - Test specifications [>] plan - Task breakdown (current) [ ] implement - Write code [ ] test - Run tests [ ] verify - Evidence check [ ] commit - Version control ``` Legend: `[x]` = done, `[>]` = current, `[ ]` = pending, `[~]` = skipped ## Error Handling If a step fails (e.g., tests fail in verify): ``` Step VERIFY found issues. Options: 1. Fix and re-run this step 2. Go back to IMPLEMENT to fix 3. Stop workflow and address manually ``` ## Bias Protection **Acceleration:** "Skip to implement" → "Consider: design and spec prevent rework. Skip only if the domain is already understood." **Scope Creep:** Adding features mid-workflow → "Finish the current workflow first. Note the idea for the next iteration." ## Native /goal Mapping Every step's skill carries an Outcome Contract whose "Done when" line is a completion condition. Claude Code's native `/goal` keeps a session working until such a condition holds; the contracts are written to be pasted there verbatim when the user wants a goal-driven session. This mapping stays documentation, not wiring: the Stop-hook final review already re-wakes this plugin's sessions on violations, and two completion loops fighting each other would burn tokens for no extra safety. For bounded in-session iteration over a single verify command, the user runs `/craftsman:loop` instead.