Development Workflow

User Guide

18 skills for structured, multi-phase development with Claude Code

Quick Reference

The workflow has 18 skills in five groups. Each runs on the model best suited to its job: Opus for reasoning-heavy work, Sonnet for efficient execution, Haiku for structured template tasks.

Planning & Design

CommandWhat it doesModel
/init_workflowOne-time project bootstrap. Creates .workflow_artifacts/ structure, configures permissions, runs /discover.Opus
/discoverScans all repos, builds inventory, architecture map, and git log. Run once on setup. Also populates .workflow_artifacts/cache/ with per-repo and per-module code summaries (knowledge cache) for faster subsequent skill runs.Opus
/architectDeep system design. Spawns scan agents in parallel, then synthesizes on Opus. Produces architecture.md.Opus
/thorough_planOrchestrates the plan-critic-revise loop. Auto-triages tasks as Small/Medium/Large.Opus
/planCreates the initial detailed plan. Reads lessons-learned.md. Can be used standalone.Opus
/criticReviews plan in a fresh session against actual code. Reads lessons-learned.md.Opus
/reviseAddresses critic feedback. Used in Large/strict mode (all-Opus).Opus
/revise-fastAddresses critic feedback. Used in Medium mode (cost-efficient).Sonnet

Execution & Review

CommandWhat it doesModel
/implementWrites code from the plan. Requires your explicit command. Never auto-invoked.Sonnet
/reviewVerifies implementation vs plan. Integration safety, risk assessment.Opus
/end_of_taskFinalizes accepted work. Commits, pushes branch. Does NOT create PR. Requires your explicit command.Sonnet

Safety Controls

CommandWhat it doesModel
/gateRuns automated checks (tests, lint, secrets scan) and STOPS for your approval between every phase.Sonnet
/rollbackMaps commits to plan tasks. Shows what would revert. Requires your confirmation before acting.Sonnet
/expandUser-facing escape hatch to read terse workflow artifacts in English. Resolves .original.md side-files for contract artifacts, or does a lossy LLM re-expansion (banner-flagged) for ephemeral files. Invoke as /expand <path>.Sonnet

Session Management

CommandWhat it doesModel
/start_of_dayReads daily cache, checks git state, presents briefing with exactly where to resume.Haiku
/end_of_daySaves session state, consolidates unfinished work, promotes insights to lessons-learned.Haiku
/weekly_reviewAggregates the week's progress, decisions, and outcomes into a structured review.Haiku

Knowledge Capture

CommandWhat it doesModel
/capture_insightLogs a pattern, gotcha, or decision rationale to .workflow_artifacts/memory/daily/insights-<date>.md without interrupting your current task.Haiku

Task Profiles

/thorough_plan auto-triages every task into one of three profiles. You can override with a prefix: small: add health endpoint, large: rewrite auth layer. When in doubt, Medium is the default.

ProfileWhen to usePlanningCritic loopTypical cost
Small 1-3 files, single module, no integration risk (bug fix, config change, simple endpoint) Single /plan pass Skipped ~$2.49
Medium Multiple files, 1-2 modules, some integration points /plan + critic loop (/revise-fast on Sonnet) Up to 4 rounds ~$2.99-$4.00
Large Cross-service, high risk, data migrations, auth changes /plan + critic loop (/revise on Opus) Up to 5 rounds ~$4.65+

Important: /architect is a separate, optional phase you run before /thorough_plan when the task needs system-level design. /thorough_plan does not call /architect. Typically only Large tasks need it.

Scenario 1: First Time Setup

You just cloned your repos into a project folder and want to set up the workflow.

Run /init_workflow

/init_workflow
Creating .workflow_artifacts/ structure... Configuring .claude/settings.json permissions... Running /discover...
Scanning the project folder... Found 4 repositories: api-gateway (TypeScript/NestJS), payment-service (Go), user-service (Python/FastAPI), notification-service (TypeScript/Node). Mapping integrations...
Done. Saved to .workflow_artifacts/memory/: repos-inventory.md, architecture-overview.md, dependencies-map.md, git-log.md. The API gateway routes to all three backend services. Payment and notification communicate via Kafka. 47 recent commits captured. Also wrote .workflow_artifacts/cache/ with repo and module summaries (~5–20K tokens) to speed up /plan, /implement, and /review.

That's it for setup. The memory files persist across sessions. Re-run /discover only when repos change significantly.

Scenario 2: Planning a Large Feature

You need to add a refund flow that touches the payment service, API gateway, and notification service.

Step 1: /architect

/architect — I need to add customer-initiated refunds. Should go through the gateway, hit the payment service which calls Stripe, and notify the customer.
Reading .workflow_artifacts/memory/architecture-overview.md for baseline context... Reading payment-service source code, Stripe SDK usage, existing transaction flow... Searching web for Stripe refund API best practices...
[Asks 2-3 clarifying questions: partial refunds? refund window? admin override?]
Yes to partial refunds, 30-day window, admin can override the window.
Architecture document saved to .workflow_artifacts/refund-flow/architecture.md. Decomposed into 3 stages: (1) Payment service refund logic + Stripe integration, (2) Gateway endpoint + validation, (3) Notification templates + Kafka consumer. Each stage is independently deployable.

Step 2: Gate

Running gate: architect → thorough_plan. Architecture document exists and covers objective, service map, integration points, 3 decomposed stages. 6/6 checks passed.

Action required: type /thorough_plan to proceed, or tell me what to adjust.
/thorough_plan

Step 3: Thorough plan (automatic loop)

Task triaged as Large (cross-service, Stripe integration, Kafka messaging). Running all-Opus convergence loop, up to 5 rounds.
Invoking /plan Opus for stage 1 (payment service refund logic)...
Plan created: 7 tasks covering Stripe refund client, refund domain model, idempotency handling, event publishing, error mapping, and tests. Saved to .workflow_artifacts/refund-flow/current-plan.md.
Invoking /critic Opus in fresh session (round 1)...
Round 1 complete — critic found 1 MAJOR issue: plan doesn't handle Stripe's async refund status (refunds can be pending for days). Verdict: REVISE.
Invoking /revise Opus to address critic feedback...
Plan revised: added Task 4a (webhook handler for refund.updated events) and updated risk table. Invoking /critic round 2...
Round 2 complete. Critic verdict: PASS. No critical or major issues.

Step 4: Gate → you decide to /implement

Running gate: thorough_plan → implement. Plan has PASS verdict, 8 tasks with file paths and acceptance criteria, integration analysis covers Stripe + Kafka + gateway, risk mitigations are concrete. 8/8 checks passed.

The plan is ready at .workflow_artifacts/refund-flow/current-plan.md. It took 2 rounds. Main revision: added async refund status handling via Stripe webhooks.

Action required: type /implement to start coding.

Notice: Claude stops here and waits. It will not start writing code until you explicitly say so.

/implement

Step 5: Implementation

Reading .workflow_artifacts/refund-flow/current-plan.md... Sonnet Which tasks would you like me to start with? The plan suggests Tasks 1-3 first (core refund logic), then 4a (webhook), then 5-8 (tests + integration).
Do tasks 1-4a
[Implements each task, makes small commits, runs tests after each]
Tasks 1-4a complete. 5 commits on branch feat/refund-flow. All existing tests pass. Running gate...

Step 6: Gate → /review

Gate: implement → review. Tests: 47 passed, 0 failed. Lint: clean. No debug code. No secrets in diff. 6/6 checks passed.

Action required: type /review to proceed.
/review
Opus [Reads the diff, traces data flow, checks Stripe error handling, verifies Kafka event schema...]
Review saved to .workflow_artifacts/refund-flow/review-1.md. Verdict: CHANGES_REQUESTED.
1 major issue: refund amount validation doesn't check against original transaction amount — could refund more than was paid. Suggested fix included.
/implement — fix the review issue
[Fixes the validation, adds test for over-refund case, commits]
/review
Review round 2. Verdict: APPROVED. All issues resolved. Tests pass.

Step 7: Gate → /end_of_task

Gate: review → end_of_task. Review is APPROVED, tests pass, no merge conflicts, branch up to date.

Action required: type /end_of_task to finalize, commit, and push the branch.

Again, Claude stops and waits. It won't push until you explicitly accept the work. PR creation is a separate step you do when ready.

/end_of_task
Pre-flight checks: review APPROVED, tests passing, working tree clean, branch up to date, no secrets.

Pushed feat/refund-flow to origin.

Anything that surprised you, or that the workflow should handle differently next time?

Next: when you're ready, create a PR from the branch.
The critic catching async refund patterns was great. For payment integrations, always check webhook/async patterns.
Added to .workflow_artifacts/memory/lessons-learned.md. Task refund-flow marked as completed.

Scenario 3: Medium Feature

You need to add rate limiting to the API gateway. Touches multiple files but stays within one service.

/thorough_plan — add rate limiting to the API gateway with per-user and per-endpoint limits
Task triaged as Medium (multiple files in one service, integration points with Redis for state). Running plan-critic-revise loop with Sonnet revise, up to 4 rounds.
/plan Opus: 5 tasks — Redis connection, rate limit middleware, per-user config, per-endpoint config, tests. Saved to .workflow_artifacts/api-rate-limiting/current-plan.md.
/critic Opus round 1: 1 issue — plan uses fixed-window algorithm, should use sliding window to prevent burst at window boundaries. Verdict: REVISE.
/revise-fast Sonnet: Updated to sliding window with Redis sorted sets. Round 2 critic: PASS.
Gate passed. Action required: type /implement to start coding.

Medium tasks use Sonnet for /revise-fast (cost-efficient) while keeping /critic on Opus (thorough). This balances cost and quality.

Scenario 4: Bug Fix

A bug comes in: refunds are failing silently for amounts under $1.

There's a bug: refunds under $1 fail silently. Can you investigate?
Reading payment-service refund code... Found it: in refund.service.go:84, the amount is cast to int before sending to Stripe, so $0.50 becomes $0. Stripe rejects $0 refunds but the error is swallowed at line 91.

For small, well-understood fixes, /thorough_plan auto-triages as Small and runs a single-pass plan with no critic loop:

/thorough_plan — fix the sub-dollar refund bug. Keep it simple.
Task triaged as Small (2 files, single module, well-understood fix). Running single-pass plan, no critic loop.
Plan: 2 tasks. (1) Change amount type from int to int64 (cents), add validation for amount > 0. (2) Add test cases for $0.50, $0.01, and $0 refunds. Files: refund.service.go, refund_test.go.
Gate: smoke checks passed. Action required: type /implement.
/implement
[Fixes the type, adds validation, writes 3 test cases, commits]
Gate: tests pass, lint clean. Action required: type /review.
/review
APPROVED. Clean fix, tests cover edge cases, no integration impact (Stripe already accepts int64 cents).

Action required: type /end_of_task to finalize.
/end_of_task
Pushed fix/sub-dollar-refund to origin. Task complete.
Next: create a PR when you're ready.

Scenario 5: Rolling Back

The implementation went wrong and you want to undo it.

/rollback
Reading current plan and git log... Found 5 commits for refund-flow tasks 1-4a on branch feat/refund-flow.

What would you like to roll back?
Revert tasks 3 and 4a only
Rollback preview:
Will revert commits e4f5g6 (task 3: event publishing) and h7i8j9 (task 4a: webhook handler).
Removes 2 files, modifies 1. Tasks 1-2 preserved. No other branches depend on these commits.

Confirm? [waiting for your explicit yes]
Yes
Reverted. Branch feat/refund-flow is now at commit c3d4e5. Tasks 3 and 4a marked as pending in the plan. Tests pass.

Scenario 6: Start and End of Day

Ending your day

/end_of_day
Haiku Saving session state for refund-flow to .workflow_artifacts/memory/... Current stage: implement (tasks 1-4a done, tasks 5-8 pending). Branch: feat/refund-flow. Updating git-log.md with 12 commits from today...
Anything that surprised you today, or that should work differently next time?
The critic caught the async refund thing which I totally missed. Plans for payment integrations should always ask about async/webhook patterns.
Added to .workflow_artifacts/memory/lessons-learned.md. Daily cache saved to .workflow_artifacts/memory/daily/2026-03-17.md. 1 session active (refund-flow, in-progress). Tomorrow's priority: finish tasks 5-8 (tests) and run /review.

Run /start_of_day when you're back.

Starting the next day

/start_of_day
Haiku Good morning. Reading daily cache from 2026-03-17...

Since last session: no new commits from others, CI green, no PR reviews.

Unfinished work:
• refund-flow — implement phase, tasks 5-8 pending (tests + integration). Branch: feat/refund-flow. Resume at: write unit tests for refund.service.go (Task 5 in .workflow_artifacts/refund-flow/current-plan.md).

Key context from yesterday: Added async refund handling via Stripe webhooks after critic caught it in round 1. Amount type changed to int64 cents.

Suggested priority: finish the tests (tasks 5-8), then /review. Want to resume with /implement?
/implement

Scenario 7: Parallel Tasks

You're mid-way through the refund feature but an urgent fix comes in.

I need to pause refund-flow and fix a production auth bug. Different task.
Got it. I'll save the current refund-flow session state (tasks 1-4a complete, 5-8 pending, branch feat/refund-flow).
/thorough_plan for auth-token-fix — tokens aren't refreshing when the clock skew exceeds 30s
Task triaged as Small. Single-pass plan: 2 tasks in auth-token-fix/ subfolder.
/implement
[Implements, tests pass, review passes, branch pushed — all in auth-token-fix/ context]

When you're ready to go back:

Back to refund-flow
Restoring refund-flow context. You're on branch feat/refund-flow, tasks 1-4a done, tasks 5-8 pending. Ready for /implement.

End of day captures both sessions:

/end_of_day
2 sessions today: auth-token-fix (completed, pushed), refund-flow (in-progress, tasks 5-8 remaining). Daily cache saved. Only refund-flow carries forward to tomorrow.

Key Rules to Remember

1. /implement and /end_of_task never run automatically. You must type them. Claude stops after planning converges (waiting for /implement) and after review approves (waiting for /end_of_task). Nothing gets written or shipped without your conscious decision.
2. Gates run between every phase. They run automated checks and present results. You approve before the next phase starts. Even if all checks pass, Claude waits. Gate intensity scales with task profile — smoke for Small, standard for Medium, full for Large.
3. /critic always runs in a fresh session. This prevents bias from having just written the plan. It reads the actual code, not just the plan's claims about it.
4. Lessons learned accumulate. /end_of_day prompts you for insights. /plan and /critic read them at the start. Over time, the workflow gets smarter about your specific codebase and patterns.
5. /thorough_plan is the universal entry point for planning. It auto-triages tasks as Small (single-pass, no critic), Medium (critic loop with Sonnet revise), or Large (all-Opus critic loop). You can override with a prefix. /architect is a separate, optional phase you run before /thorough_plan when the task needs system-level design.
6. /rollback is always available. It maps commits to plan tasks, shows what will change, and requires your confirmation. Safe to use at any point.
7. Each task gets its own folder. .workflow_artifacts/refund-flow/, .workflow_artifacts/auth-token-fix/ — parallel tasks never mix. Descriptive kebab-case names. Completed tasks move to .workflow_artifacts/finalized/ via /end_of_task.

Three-Tier Memory

The workflow accumulates knowledge at three levels:

Tier 1 — Daily scratchpad (.workflow_artifacts/memory/daily/insights-<date>.md): Claude writes here automatically during task work — patterns, gotchas, decision rationale. Use /capture_insight to log something explicitly.
Tier 2 — Lessons learned (.workflow_artifacts/memory/lessons-learned.md): Promoted from Tier 1 at /end_of_day with your confirmation. Planning and review skills read this automatically to avoid repeating past mistakes.
Tier 3 — Workflow suggestions (.workflow_artifacts/memory/workflow-suggestions.md): Insights about the workflow itself. Surfaced at /end_of_day for you to apply to the workflow repo manually.

Session Management: One Command Per Session

Context windows fill up. This is expected and the workflow is designed for it. Each skill can run in its own chat session — the files on disk are the shared memory between sessions.

How it works

Every skill has a "session bootstrap" step. When it starts in a fresh session, it reads what it needs from disk:

SkillReads on startup
/architectCLAUDE.md, .workflow_artifacts/memory/lessons-learned.md, /discover memory files, .workflow_artifacts/<task-name>/
/planCLAUDE.md, .workflow_artifacts/memory/lessons-learned.md, .workflow_artifacts/<task-name>/architecture.md, prior critic responses
/criticCLAUDE.md, .workflow_artifacts/memory/lessons-learned.md, .workflow_artifacts/<task-name>/current-plan.md, actual source code
/reviseCLAUDE.md, .workflow_artifacts/<task-name>/current-plan.md, latest critic-response
/implementCLAUDE.md, .workflow_artifacts/memory/lessons-learned.md, .workflow_artifacts/memory/sessions/ state, .workflow_artifacts/<task-name>/current-plan.md, source code
/reviewCLAUDE.md, .workflow_artifacts/memory/lessons-learned.md, .workflow_artifacts/<task-name>/current-plan.md, .workflow_artifacts/<task-name>/architecture.md, git diff + full files

You never have to re-explain context. If it's in the files, the skill reads it.

Recommended session pattern

Large feature (multi-session)

Session 1: /architect — design the refund flow

Claude saves architecture.md. Close this session.

Session 2: /thorough_plan — plan stage 1

Claude reads architecture.md from disk, runs plan-critic-revise loop. Saves current-plan.md. Close.

Session 3: /implement — tasks 1-4

Fresh context! Clean session means Claude focuses on code, not planning noise. Reads the plan from disk. Close when tasks are done.

Session 4: /review

Fresh eyes on the diff. Reads plan + code, no implementation bias. Close when done.

Small bug fix (single session)

Same session: /thorough_plan → /implement → /review

Short enough to fit in one context. No need to split.

Resuming mid-task

New session: /implement — continue with refund-flow
Reading session state... you completed tasks 1-4a last session. Tasks 5-8 remaining. Branch: feat/refund-flow. Picking up at Task 5.

The session state file tells the new session exactly where you left off.

When to split vs stay

Split when: you've been going for a while and responses are getting slower or less focused, you're moving to a different phase (plan→implement), or you want unbiased review.
Stay when: the task is small, you're in a quick thorough_plan→implement→review flow, or you're iterating on implementation fixes within the same phase.
Always split for: /critic (by design — it must be a fresh session), /review (fresh eyes catch more).

Workflow Diagram

Full pipeline (Large tasks):

/discover → /architect → GATE → /thorough_plan → GATE → /implement → GATE → /review → GATE → /end_of_task

Medium/Small tasks (skip /architect):

/thorough_plan → GATE → /implement → GATE → /review → GATE → /end_of_task

Inside /thorough_plan (Medium and Large only):

/plan Opus → /critic Opus → /revise → /critic → … → PASS Medium: up to 4 rounds (Sonnet revise) · Large: up to 5 rounds (Opus revise)

Session lifecycle:

/start_of_day Haiku → [ work ] → /end_of_day Haiku

Available at any time:

/rollback — undo implementation work safely

File Structure

What gets created in your project folder:

~/.claude/ ← user-level, shared across all projects
├ CLAUDE.md ← workflow rules, auto-loaded everywhere
└ skills/ ← all 17 workflow skills

project-folder/
├ .claude/settings.json ← project permissions
├ .workflow_artifacts/ ← all workflow artifacts (hidden at project root)
│ ├ memory/ ← project knowledge
│ │ ├ repos-inventory.md ← from /discover
│ │ ├ architecture-overview.md ← from /discover
│ │ ├ dependencies-map.md ← from /discover
│ │ ├ git-log.md ← rolling commit log
│ │ ├ lessons-learned.md ← accumulated insights
│ │ ├ workflow-suggestions.md ← workflow improvement ideas
│ │ ├ sessions/ ← per-session state files
│ │ ├ daily/ ← daily rollups + insight scratchpads
│ │ └ weekly/ ← weekly reviews
│ ├ refund-flow/ ← active task subfolder
│ │ ├ architecture.md
│ │ ├ current-plan.md
│ │ ├ critic-response-1.md … critic-response-N.md
│ │ └ review-1.md … review-N.md
│ └ finalized/ ← completed tasks (archived by /end_of_task)
├ service-a/ ← your repos
├ service-b/
└ frontend/