Dev Workflow

Dev Workflow: Strict Orchestration over ECC

Pure orchestration skill. Does not define agents or prompts — delegates to ECC's existing agents and commands. Adds strict sequencing, phase gates, plan tracking, and iterative loop protocols.

ECC components used

All agents are defined in ECC's agents/ directory. Do NOT write custom prompts. Use the slash commands — they invoke the correct agent with the correct tools.

---

Plan directory: .claude/plan/

All planning artifacts live in .claude/plan/ at the project root. This directory is the source of truth for what should be built and what actually changed during implementation.

.claude/plan/
├── plan.md              # The implementation plan (Phase 2 output)
├── deviations.md        # Log of every plan change during execution
└── research-summary.md  # Codebase context from Phase 1 (optional)

plan.md

Created by the planner agent in Phase 2. Contains:

• Approach and rationale (with alternatives considered)
• Test plan (what tests to write first)
• Implementation steps with file paths and dependencies
• Acceptance criteria (checkboxes)
• Out of scope

deviations.md

Created automatically at the start of Phase 3. Updated whenever implementation diverges from plan.md. Each entry records:

## Deviation [N]: [short title]
- **Phase**: [which phase discovered this]
- **Planned**: [what plan.md said]
- **Actual**: [what we're doing instead]
- **Reason**: [why the change was necessary]
- **Impact on acceptance criteria**: [which criteria changed, added, or removed]
- **Approved**: [yes/no — user confirmed, or auto if trivial]

Rules for deviations:

• ANY change to scope, approach, file list, or acceptance criteria gets logged
• Trivial deviations (renaming a variable, minor refactor) = auto-approved
• Significant deviations (new endpoint, changed API contract, dropped feature)

= STOP and ask the user before proceeding

• The reviewer reads deviations.md to distinguish intentional changes from drift

---

Phase execution

Phase 1: EXPLORE

Built-in Explore subagent (auto-delegates on read-heavy tasks). No slash command needed — describe the task and the orchestrator routes to Explore.

If the task is complex, ask Explore to write findings to .claude/plan/research-summary.md. Otherwise, Explore returns a summary to the main context directly.

Gate: enough context to plan (relevant files, patterns, dependencies, risks).

Phase 2: PLAN (THINK HARD)

/plan "[task description]"

The planner creates .claude/plan/plan.md. Use extended thinking.

The plan MUST address 6 aspects: 1. Problem space — what exactly needs to change, scope, boundaries 2. Approach analysis — at least 2 approaches, tradeoffs, why this one 3. Failure modes — what could go wrong, edge cases, regressions 4. Dependency chain — what must be done first, what can parallelize 5. Test strategy — what tests exist before implementation starts 6. Acceptance criteria — concrete, verifiable, each one testable

If any aspect is missing, the plan isn't ready. Keep thinking.

If architectural decisions needed (new services, schema, API contracts), also invoke the architect agent.

After plan.md is created, initialize .claude/plan/deviations.md.

Gate: plan.md exists with all 6 aspects covered. If open blockers, STOP and ask user.

Phase 3: IMPLEMENT (TDD)

/tdd

Tell the tdd-guide to read .claude/plan/plan.md for what to build.

During implementation, whenever the approach diverges from plan: 1. Log the deviation in .claude/plan/deviations.md 2. If significant → STOP, explain to user, get approval 3. If trivial → auto-approve and continue 4. Update acceptance criteria in plan.md if needed

Gate: all planned tests pass + no unapproved deviations. Then:

/verify

Phase 4: STRICT REVIEW LOOP

Read references/loops.md for the complete protocol.

The reviewer has THREE inputs: 1. The code changes (git diff) 2. .claude/plan/plan.md (what was intended) 3. .claude/plan/deviations.md (what changed and why)

Review checklist includes plan compliance:

• Does the implementation fulfill every acceptance criterion in plan.md?
• Are all deviations logged and justified?
• Are there unlisted deviations (code changes with no plan entry)?
• Did the deviations compromise the original intent?

loop:
  /code-review + /security-scan  ← IN PARALLEL
  (reviewer reads plan.md + deviations.md for context)
  merge findings
  if ZERO high+medium → /verify → exit
  fix ALL high + medium (log deviation if fix changes approach)
  /verify
  re-review ALL changes
  repeat until clean (max 5 iterations)

Phase 5: STRICT TEST LOOP (Minimum 3 Rounds)

Read references/loops.md for the complete protocol.

Before starting, ask user which cost tier:

• Strict (default): 3 rounds, ~15-20 spawns
• Standard: 2 rounds, ~10-12 spawns
• Quick: 1 round, ~4-6 spawns

Each round: expand → review test scripts → run+fix → /verify gate.

ROUND 1 — Edge cases & boundary values
  /tdd → expand (min 3 new tests: empty, max, zero, off-by-one)
  /code-review → review TEST SCRIPTS only (loop until clean)
  run suite → build-error-resolver if failures (loop until pass)
  /verify gate

ROUND 2 — Negative paths & error handling
  /tdd → expand (min 3 new tests: bad input, permissions, timeouts)
  /code-review → review test scripts (loop until clean)
  run + fix loop
  /verify gate

ROUND 3 — Integration & regression
  /tdd → expand (min 3 new tests: cross-module, regressions for review fixes)
  /e2e → Playwright critical flows (if applicable)
  /code-review → review ALL test files CUMULATIVE (loop until clean)
  run + fix loop
  /verify + /test-coverage (must hit 80%+)
  if coverage < 80% → add Round 4 targeting uncovered files

POST-TEST — Final review loop
  /code-review on ALL changes (production + tests) → loop until PASS
  /verify + /test-coverage → final gate
  → DONE

Cleanup

After Phase 5:

• refactor-cleaner removes dead code (auto-delegates)
• doc-updater syncs documentation (auto-delegates)
• Update .claude/plan/plan.md: check off completed acceptance criteria
• Finalize .claude/plan/deviations.md with summary
• Suggest conventional commit message (feat:/fix:/refactor:)

The .claude/plan/ directory stays in the repo as documentation.

---

Phase gates

Every transition runs /verify:

Phase 3 → /verify → Phase 4
Phase 4 → /verify → Phase 5
Each test round → /verify → next round
Final → /verify + /test-coverage → done

---

Overrides

• "Skip to phase N" — jump directly
• "Just implement it" — skip phases 1-2, do 3-5
• "Skip tests" — phases 1-3 only (warn: not recommended)
• "Quick fix" — skip entire workflow
• "Standard/Quick test mode" — reduce Phase 5 rounds

---

Progress reporting

After each phase (2-3 sentences):

• Which phase completed
• Key output or findings
• Deviation count (if any)
• What comes next

---

Hooks

Four hooks enforce the workflow automatically. They fire on lifecycle events — if .claude/plan/ exists, the hooks are active.

---

Enforcement: making CC actually follow the workflow

The skill alone is NOT enough — CC reads it but shortcuts phases. Three mechanisms enforce full compliance:

1. Rule file: rules/dev-workflow.md

Loaded into context EVERY session (rules are stronger than skills). Contains:

• Mandatory checklist that CC must print before starting any multi-file task
• Explicit "do NOT skip phases, do NOT combine phases"
• Plan quality requirements (6 aspects that must be covered)
• Clear criteria for when skipping IS allowed

Install: loaded automatically as part of this plugin.

2. Slash command: /dev

Explicit trigger that creates a numbered todo list CC must work through. Usage: /dev Add OAuth2 login with Google provider

Creates full checklist + instructs "think hard" during plan phase.

3. Hooks

• commit-gate blocks shipping if plan incomplete
• deviation-detector catches unlisted changes
• phase-tracker keeps the orchestrator on track

Why all three?

---

Reference files

• references/loops.md — Strict loop protocols for Phase 4 and Phase 5,

including plan-compliance review, inner loops, exit criteria, cost tiers.

• rules/dev-workflow.md — Rule enforcing workflow compliance on every session.
• commands/dev.md — Slash command for explicit workflow trigger with checklist.
• hooks/hooks.json — Hook configuration wiring all hooks to lifecycle events.

You are starting a strict phased development workflow. Follow every phase in order. Do NOT skip phases. Do NOT combine phases.

Task: $ARGUMENTS

Step 1: Create the checklist

Print this checklist NOW, before doing anything else:

## Dev workflow: $ARGUMENTS
- [ ] Phase 1: Explore — gather context
- [ ] Phase 2: Plan — .claude/plan/plan.md (think hard)
- [ ] Phase 3: /tdd — tests first, then implement
- [ ] Phase 3 gate: /verify
- [ ] Phase 4a: /code-review — loop until PASS
- [ ] Phase 4b: /security-scan — loop until PASS
- [ ] Phase 4 gate: /verify
- [ ] Phase 5 R1: /tdd edge cases → review test scripts → run → /verify
- [ ] Phase 5 R2: /tdd negative paths → review test scripts → run → /verify
- [ ] Phase 5 R3: /tdd integration → review ALL tests → run → /verify + /test-coverage
- [ ] Phase 5 final: /code-review ALL changes → loop until PASS
- [ ] Phase 5 gate: /verify + /test-coverage (80%+)
- [ ] Cleanup: refactor-cleaner + doc-updater
- [ ] Commit: conventional format

Step 2: Phase 1 — Explore

Use the built-in Explore subagent to gather context. Investigate:

• All files relevant to this task
• Existing patterns and conventions
• Dependencies and integration points
• Risks and edge cases

After exploring, check off Phase 1 and report findings.

Step 3: Phase 2 — Plan (THINK HARD)

This is the most important phase. Use extended thinking.

Initialize .claude/plan/ directory if it doesn't exist.

Think through these aspects BEFORE writing the plan:

Aspect 1 — Problem space: What exactly needs to change? What's the scope? What are the boundaries of this change? What is explicitly OUT of scope?

Aspect 2 — Approach analysis: What are at least 2 different approaches? What are the tradeoffs of each? Why is the chosen approach better?

Aspect 3 — Failure modes: What could go wrong? What edge cases exist? What happens if a dependency is unavailable? What about concurrent access? What about data migration? What about backwards compatibility?

Aspect 4 — Dependency chain: What must be done first? What can be parallelized? What has external dependencies (APIs, packages, services)?

Aspect 5 — Test strategy: What tests must exist BEFORE implementation? What's the minimum set that proves the feature works? What edge case tests would catch the failure modes from Aspect 3?

Aspect 6 — Acceptance criteria: Write concrete, verifiable criteria. Each criterion must be testable — "works correctly" is NOT a criterion. "Returns 401 for unauthenticated requests" IS a criterion.

Write the complete plan to .claude/plan/plan.md. Initialize .claude/plan/deviations.md. Check off Phase 2 and report the plan summary.

Step 4: Execute remaining phases

For each subsequent phase, follow the dev-workflow skill and references/loops.md exactly. Check off each item as you complete it.

CRITICAL RULES:

• After EVERY phase, update the checklist showing what's done
• If you discover the plan needs to change, log it in deviations.md
• Significant deviations → STOP and ask the user
• Review loops continue until PASS — do NOT exit on first attempt
• Test loop has 3 MANDATORY rounds — do NOT stop after 1
• /verify runs at every gate — do NOT skip gates

Strict Loop Protocols

All loops have hard exit criteria. No early exits. No skipping rounds. The orchestrator drives all loops — subagents don't loop themselves.

Reviewers always read THREE inputs: 1. Code changes (git diff or modified files) 2. .claude/plan/plan.md (what was intended) 3. .claude/plan/deviations.md (what changed and why)

---

Phase 4: Strict Review Loop

Exit: ZERO high/medium findings from BOTH code-reviewer AND security-reviewer in the SAME iteration. No partial passes.

iteration = 0
max_iterations = 5

loop:
  iteration += 1

  # 1. Spawn BOTH reviewers in parallel
  /code-review → code-reviewer (opus)
    - Review all changes since task began
    - Read .claude/plan/plan.md for intended behavior
    - Read .claude/plan/deviations.md for approved changes
    - PLAN COMPLIANCE CHECK (see below)
    - Write to review-comments.md

  /security-scan → security-reviewer (opus) IN PARALLEL
    - OWASP Top 10, secrets, dependency audit
    - Write to security-comments.md

  # 2. Merge findings, categorize HIGH / MEDIUM / LOW

  # 3. Evaluate
  if ZERO high + medium across both:
    → /verify gate
    → exit loop → Phase 5

  if iteration >= max_iterations:
    report findings to user
    ask: "Not converged after {max_iterations}. Continue or ship?"

  # 4. Fix ALL high + medium findings
  If a fix changes the implementation approach:
    → log deviation in .claude/plan/deviations.md
    → if significant, ask user before proceeding

  # 5. /verify — confirm fixes didn't break anything
  if /verify fails → build-error-resolver → fix → re-verify

  # 6. Delete old review files, re-review EVERYTHING
  repeat loop

Plan compliance check

The code-reviewer MUST evaluate these in addition to standard code quality:

1. Acceptance criteria coverage: For each criterion in plan.md, is there code that fulfills it? Flag any unmet criteria as HIGH.

2. Unlisted changes: Are there code changes that don't correspond to any plan step or logged deviation? Flag as MEDIUM.

3. Deviation justification: For each entry in deviations.md, is the reason valid and the impact accurately described? Flag unjustified or under-documented deviations as MEDIUM.

4. Plan intent preservation: Did the deviations collectively compromise the original goal? Flag as HIGH if the implementation no longer achieves what was planned.

Tell the code-reviewer explicitly:

"In addition to code quality, check plan compliance:
 - Read .claude/plan/plan.md and verify every acceptance criterion is met
 - Read .claude/plan/deviations.md and verify all deviations are logged
 - Flag any code changes not covered by plan.md or deviations.md
 - Flag any unmet acceptance criteria"

Review loop rules

• Orchestrator makes fixes, not the reviewer (reviewers are read-only)
• Fix ALL high + medium before re-running
• Each re-review covers ALL changes, not just fixes
• /verify between fix and re-review catches mechanical breakage
• Both reviewers must PASS in same iteration
• Deviation log must be updated if fixes change the approach

---

Phase 5: Strict Test Loop (Minimum 3 Rounds)

Three mandatory rounds with specific focus areas. Each round follows the same protocol:

ROUND PROTOCOL:
  a. /tdd         → expand tests (focus area, min 3 new tests)
  b. test-review  → inner loop: review test scripts until clean
  c. test-run     → inner loop: run suite, fix failures until pass
  d. /verify      → gate

Round 1: Edge cases and boundary values

Focus for tdd-guide:

• Edge cases, boundary values, off-by-one errors
• Empty inputs, max values, zero, negative values
• Unicode, special characters, very long strings
• MINIMUM 3 new test cases
• Cross-reference: plan.md acceptance criteria — each criterion

should have at least one test that verifies it directly

Round 2: Negative paths and error handling

Focus for tdd-guide:

• Bad/malformed inputs, missing required fields
• Permission denied, unauthorized access attempts
• Network failures, timeouts, service unavailable
• Database constraint violations, duplicate keys
• MINIMUM 3 new test cases
• Log any discovered behavior not in plan as deviation

Round 3: Integration and regression

Focus for tdd-guide:

• Cross-module interactions between changed and existing code
• Regression tests for every bug found during Phase 4 review
• Regression tests for every fix made during Rounds 1-2
• End-to-end flows if applicable (/e2e for Playwright)
• MINIMUM 3 new test cases

Round 3 review is CUMULATIVE — all test files, not just new ones. Checks for duplication, gaps, flaky patterns.

Round 3 gate:

/verify
/test-coverage (must hit 80%+)
if coverage < 80% → Round 4 targeting uncovered files

Acceptance criteria test mapping

During Round 1, create a mapping in the test review:

For each acceptance criterion in .claude/plan/plan.md:
  → Which test(s) verify this criterion?
  → If no test exists → flag as HIGH finding in test review

---

Inner Loop: Test Script Review

Used in step (b) of each round.

test_review_iteration = 0
test_review_max = 3

loop:
  test_review_iteration += 1

  /code-review targeting TEST FILES ONLY:
    - "Review ONLY test files. Do NOT review production code."
    - "Are assertions testing the right thing?"
    - "Are test names descriptive?"
    - "Is each test independent (no shared mutable state)?"
    - "Do mocks/stubs match real behavior?"
    - "Does every acceptance criterion from plan.md have a test?"
    - "Are there obvious gaps?"

  if clean → exit
  if findings:
    if test_review_iteration >= test_review_max → escalate to user
    fix test script issues
    repeat loop

---

Inner Loop: Test Run + Fix

Used in step (c) of each round.

run_iteration = 0
run_max = 5

loop:
  run_iteration += 1
  run full test suite

  if all pass → exit
  if failures:
    if run_iteration >= run_max → escalate to user
    build-error-resolver:
      - Read error output
      - Check plan.md for intended behavior
      - Is the test wrong or the code wrong?
      - Fix with minimal change
      - Log deviation if fix changes approach
      - Re-run to confirm
    repeat loop

---

Post-Test: Final Review Loop

After all rounds complete:

/code-review on ALL changes (production + tests):
  "Final review. All production code AND test files.
   Verify plan compliance: every acceptance criterion met,
   all deviations logged, no unlisted changes."

if findings → fix → re-review → loop until PASS

/verify + /test-coverage → final gate

if pass + coverage >= 80% → DONE → cleanup
if failures → back to test run+fix loop

Plan finalization (during cleanup)

After DONE: 1. Update plan.md: check off completed acceptance criteria 2. Finalize deviations.md: add summary section at top

## Summary
- Total deviations: [N]
- User-approved: [N]
- Auto-approved (trivial): [N]
- Plan completion: [X/Y acceptance criteria met]
- Unmet criteria: [list any, with explanation]

3. The .claude/plan/ directory stays in the repo as documentation

---

Cost Tiers

Default: Strict. Ask BEFORE starting Phase 5.

Development workflow enforcement

For ANY task that modifies production code across multiple files or introduces new behavior, you MUST follow the dev-workflow skill phases in order. Do NOT skip phases. Do NOT combine phases. Do NOT shortcut.

Mandatory phase sequence

Before writing any code, create a checklist in your response:

## Workflow checklist
- [ ] Phase 1: Explore — gather codebase context
- [ ] Phase 2: Plan — write .claude/plan/plan.md (use extended thinking)
- [ ] Phase 3: Implement — /tdd (tests first, then code)
- [ ] Phase 3 gate: /verify
- [ ] Phase 4: Review loop — /code-review + /security-scan until PASS
- [ ] Phase 4 gate: /verify
- [ ] Phase 5: Test loop — 3 rounds minimum (edge → negative → integration)
- [ ] Phase 5 gate: /verify + /test-coverage
- [ ] Cleanup: refactor-cleaner + doc-updater + commit

Check off each item as you complete it. Do NOT proceed to the next phase until the current phase is complete and its gate passes.

When to skip the workflow

ONLY skip if ALL of these are true:

• Change is a single file
• Change is under 20 lines
• No new behavior introduced
• User explicitly says "quick fix" or "just do it"

If in doubt, follow the workflow.

Plan phase requirements

The plan phase is the most important phase. Do NOT rush it. Use extended thinking (think hard) when creating the plan. The plan MUST address these aspects before you write any code:

1. What exactly needs to change and why (problem definition) 2. What approaches were considered and why this one was chosen 3. What could go wrong (failure modes, edge cases, regressions) 4. What the dependency chain looks like (order matters) 5. What tests need to exist before implementation starts 6. What the acceptance criteria are (concrete, verifiable)

If the plan doesn't cover all 6, it's not ready. Keep thinking.