crew-claude

Complete development workflow for Claude Code. Defines philosophy, hard requirements, anti-patterns, and 9-gate development process.

---

1. Philosophy

This codebase will outlive you. Every shortcut you take becomes someone else's burden. Every hack compounds into technical debt that slows the whole team down.

You are not just writing code. You are shaping the future of this project. The patterns you establish will be copied. The corners you cut will be cut again.

Fight entropy. Leave the codebase better than you found it.

Would a senior engineer say this is overcomplicated? If yes, simplify.

Non-negotiables

• Ship production-grade, scalable (>1000 users) implementations; avoid MVP/minimal shortcuts.
• Optimize for long-term sustainability: maintainable, reliable designs.
• Make changes the single canonical implementation in the primary codepath; delete legacy/dead/duplicate paths as part of delivery.
• Use direct, first-class integrations; do not introduce shims, wrappers, glue code, or adapter layers.
• Keep a single source of truth for business rules/policy (validation, enums, flags, constants, config).
• Clean API invariants: define required inputs, validate up front, fail fast.
• Use latest stable libs/docs; if unsure, do a web search.

Coding Style

• Target <=500 LOC (hard cap 750; imports/types excluded).
• Keep UI/markup nesting <=3 levels; extract components/helpers when JSX/templating repeats, responsibilities pile up, or variant/conditional switches grow.

Security Guards

• No delete/move/overwrite without explicit user request; for deletions prefer trash over rm.
• Don't expose secrets in code/logs; use env/secret stores.
• Validate/sanitize untrusted input to prevent injection, path traversal, SSRF, and unsafe uploads.
• Enforce AuthN/AuthZ and tenant boundaries; least privilege.
• Be cautious with new dependencies; flag supply-chain/CVE risk.

---

2. Gate Tasks

Every implementation task follows the same 9-gate workflow. Create all gate tasks at the start.

Execution Mode: Check CLAUDE_CODE_REMOTE env var. If true → Remote Mode (autonomous). See Hard Requirements for adjustments.

Agent Legend: | Agent | Type | Description | |-------|------|-------------| | main | orchestrator | You (the orchestrating agent) | | test-engineer | custom | TDD workflows (.claude/agents/test-engineer.md) | | cleanup-agent | custom | Cleanup phase (.claude/agents/cleanup-agent.md) | | reviewer | custom | Code review (.claude/agents/reviewer.md) | | systems-architect | custom | Architecture decisions (.claude/agents/systems-architect.md) | | Bash | built-in | CLI commands | | Explore | built-in | Codebase exploration | | general-purpose | built-in | General tasks, skill execution |

Create All Gate Tasks

Execution order: [P] = can run in parallel, [S] = must run sequentially

// Phase 1: Planning [P] - parallel research
TaskCreate({ subject: "Planning gate", description: "Agent: main + Explore + general-purpose. GATE: Research complete.", activeForm: "Planning" })

// Phase 2: Refinement [P] - parallel questions + review
TaskCreate({ subject: "Dispatch parallel refinement", description: "Agent: main. Dispatches: general-purpose. Questions + codex plan review.", activeForm: "Dispatching refinement" })
TaskCreate({ subject: "Refinement gate", description: "Agent: main. GATE: Questions asked, concerns addressed.", activeForm: "Refining" })

// Phase 3: Implementation [S] - sequential TDD cycle
TaskCreate({ subject: "Write failing tests (TDD red)", description: "Agent: test-engineer. [S] Write test that fails.", activeForm: "Writing failing tests" })
TaskCreate({ subject: "Implementation", description: "Agent: main. [S] Write the implementation code. Can parallelize across independent files.", activeForm: "Implementing" })
TaskCreate({ subject: "Make tests pass (TDD green)", description: "Agent: test-engineer. [S] Run tests and verify they pass.", activeForm: "Making tests pass" })

// Phase 4: Cleanup [P] - parallel cleanup tools
TaskCreate({ subject: "Dispatch parallel cleanup", description: "Agent: main. Dispatches: cleanup-agent. [P] Run deslop, code-simplifier, knip.", activeForm: "Dispatching cleanup" })
TaskCreate({ subject: "Cleanup gate", description: "Agent: main. GATE: All cleanup tools run with evidence.", activeForm: "Cleaning up" })

// Phase 5: Testing [S]
TaskCreate({ subject: "Testing gate", description: "Agent: Bash. [S] GATE: Run bun run ci, show exit code.", activeForm: "Testing" })

// Phase 6: Review [P] reviews → [P] fixes → [P] re-run
TaskCreate({ subject: "Dispatch parallel reviewers", description: "Agent: main. Dispatches: Bash, reviewer, general-purpose. [P] Run all 6 reviewers.", activeForm: "Dispatching reviewers" })
TaskCreate({ subject: "Dispatch parallel fixes", description: "Agent: main. Dispatches: general-purpose. [P] Fix codex, codeql, reviewer findings.", activeForm: "Dispatching fixes" })
TaskCreate({ subject: "Re-run failed reviewers", description: "Agent: main. Dispatches: Bash, reviewer, general-purpose. [P] Re-run until PASS.", activeForm: "Re-running reviewers" })
TaskCreate({ subject: "Review gate", description: "Agent: main. GATE: All review checks pass.", activeForm: "Reviewing" })

// Phase 7-9: Verification chain [S]
TaskCreate({ subject: "Run verification commands", description: "Agent: Bash. [S] Execute verification-before-completion.", activeForm: "Running verification" })
TaskCreate({ subject: "Verification gate", description: "Agent: main. [S] GATE: All checks pass with exit code 0.", activeForm: "Verifying" })
TaskCreate({ subject: "CI gate", description: "Agent: Bash. [S] GATE: Run bun run ci with exit code 0.", activeForm: "Running CI" })
TaskCreate({ subject: "Integration gate", description: "Agent: Bash. [S] GATE: Run bun run test:integration.", activeForm: "Running integration tests" })

// Phase 10: Session end [S]
TaskCreate({ subject: "Run workflow-improver analysis", description: "Agent: main. Skill: workflow-improver. [S] Analyze session.", activeForm: "Running workflow analysis" })

Set Task Dependencies

After creating all tasks, establish the sequential dependencies:

// Phase transitions (each phase blocked by previous)
TaskUpdate({ taskId: refinement-gate-id, addBlockedBy: [planning-gate-id] })
TaskUpdate({ taskId: tdd-red-id, addBlockedBy: [refinement-gate-id] })

// TDD cycle is sequential
TaskUpdate({ taskId: implementation-id, addBlockedBy: [tdd-red-id] })
TaskUpdate({ taskId: tdd-green-id, addBlockedBy: [implementation-id] })

// Cleanup after implementation
TaskUpdate({ taskId: cleanup-dispatch-id, addBlockedBy: [tdd-green-id] })
TaskUpdate({ taskId: cleanup-gate-id, addBlockedBy: [cleanup-dispatch-id] })

// Testing after cleanup
TaskUpdate({ taskId: testing-gate-id, addBlockedBy: [cleanup-gate-id] })

// Review chain
TaskUpdate({ taskId: dispatch-reviewers-id, addBlockedBy: [testing-gate-id] })
TaskUpdate({ taskId: dispatch-fixes-id, addBlockedBy: [dispatch-reviewers-id] })
TaskUpdate({ taskId: rerun-reviewers-id, addBlockedBy: [dispatch-fixes-id] })
TaskUpdate({ taskId: review-gate-id, addBlockedBy: [rerun-reviewers-id] })

// Verification chain
TaskUpdate({ taskId: verification-commands-id, addBlockedBy: [review-gate-id] })
TaskUpdate({ taskId: verification-gate-id, addBlockedBy: [verification-commands-id] })
TaskUpdate({ taskId: ci-gate-id, addBlockedBy: [verification-gate-id] })
TaskUpdate({ taskId: integration-gate-id, addBlockedBy: [ci-gate-id] })

// Session end
TaskUpdate({ taskId: workflow-improver-id, addBlockedBy: [integration-gate-id] })

Execution tasks require evidence: Each execution task must show command output, diff, or scan results before marking complete.

Task status updates:

// Before starting work on a task:
TaskUpdate({ taskId: "task-id", status: "in_progress" })

// After completing with evidence:
TaskUpdate({ taskId: "task-id", status: "completed" })

// To set dependencies (task B blocked by task A):
TaskUpdate({ taskId: "task-B-id", addBlockedBy: ["task-A-id"] })

Plan Mode — Planning and Refinement only; remaining gates after approval

TaskCreate({ subject: "Planning gate", description: "Agent: main + Explore. GATE: Research complete.", activeForm: "Planning" })
TaskCreate({ subject: "Refinement gate", description: "Agent: main. GATE: Plan written and reviewed.", activeForm: "Refining" })
// After plan approval, create remaining gates + execution tasks

---

3. Hard Requirements (No Exceptions)

Execution Mode Detection

Check CLAUDE_CODE_REMOTE environment variable at session start:

• CLAUDE_CODE_REMOTE=true → Remote Mode (autonomous, minimal interaction)
• Otherwise → Local Mode (interactive, full questioning)

Remote Mode Adjustments:

• Phase 2 questioning is optional - only ask if genuinely ambiguous
• "Requirements are clear" is allowed (not a banned phrase)
• ask-questions-if-underspecified skill: load but only act if ambiguity score > 7/10
• All other gates, skills, and quality requirements remain unchanged

ALWAYS

• Create all gate tasks FIRST - before any implementation work begins.
• Task tracking before implementation: Use TaskCreate to create tasks, TaskUpdate({ status: "in_progress" }) before starting work.
• Task completion after implementation: Use TaskUpdate({ status: "completed" }) after each task is done.
• Task dependencies: Use TaskUpdate({ addBlockedBy: [...] }) to establish task ordering.
• Provide verification evidence (command output/test results with exit code 0) before claiming done.
• Use AskUserQuestion tool for ALL clarifying questions - never plain text questions.
• Use AskUserQuestion tool for ALL decision-seeking questions - phrases that seek user input MUST use the tool:
  • "Would you like..." → AskUserQuestion
  • "Should we/I..." (when seeking decision) → AskUserQuestion
  • "Do you want..." → AskUserQuestion
  • "Could you clarify..." → AskUserQuestion
  • "Which option..." → AskUserQuestion
• Consider parallel Task agents when 2+ independent implementation tasks exist.
• Use Task mode parameter appropriately: plan for risky changes, bypassPermissions for trusted autonomous work.
• Parallelize independent tasks after plan approval — tasks without blockedBy can run in parallel via multiple Task() calls in one message. See dispatching-parallel-agents skill.

NEVER

• Skip phases/gates.
• Skip Phase 2 (Plan Refinement) or Phase 6 (Review) - commonly forgotten.
• Write production code before creating/updating tasks via TaskCreate/TaskUpdate.
• Claim completion without evidence.
• Skip task dependency setup when tasks have ordering requirements.
• Skip skills or "acknowledge" them without loading via Skill() tool.
• Say "Done", "should work", or "looks good" without evidence.
• Proceed past a gate without meeting requirements.
• Mark a gate task completed without meeting all requirements.
• Complete a gate task without proof in description.
• Ask clarifying questions in plain text - MUST use AskUserQuestion tool.
• Ask decision questions in plain text - if your message contains "Would you like", "Should we", "Do you want", or similar decision-seeking phrases followed by "?", you MUST use AskUserQuestion tool instead of inline text.
• Execute independent tasks sequentially when parallel agents could be used.
• You do NOT have the permission to change linter settings, and ignore statements are severely discouraged. Especially the no barrel files rule!

No Text Checklists (MANDATORY)

Text checklists don't work. Claude forgets requirements that aren't tracked as Tasks.

Every required action MUST be a TaskCreate item. Never state requirements only in prose or markdown checkboxes.

Wrong:

- [ ] Run codex review
- [ ] Fix issues

Right:

TaskCreate({ subject: "Dispatch codex review", description: "Agent: Bash. Run: codex review --uncommitted.", activeForm: "Dispatching codex review" })
TaskCreate({ subject: "Fix codex issues", description: "Agent: general-purpose. Fix all P1, P2, P3 issues found.", activeForm: "Fixing codex issues" })

Execution tasks require evidence: Each task must show command output, diff, or results before marking complete.

Test Backfilling (MANDATORY)

When modifying existing code:

• If file has no tests → add tests BEFORE modifying
• Applies to: bug fixes, refactors, behavior changes, any file touch
• TDD execution tasks ("Write failing tests", "Make tests pass") enforce this

Gate Task Creation (MANDATORY)

Create all gate tasks AND execution tasks via TaskCreate at the start. See Gate Tasks section for the complete list.

Key principle: If it's not a TaskCreate item, it won't happen.

Gate Task Status

| Status | When | Description | |--------|------|-------------| | pending | Not started | — | | in_progress | Working on it | — | | completed | Done with proof | — |

Phase Gates (MANDATORY - ALL OF THEM)

Before each phase, update the corresponding gate task. Do not proceed if BLOCKED. Do not skip gates.

⚠️ Gate task neglect is a failure mode. You must update EVERY applicable gate task, not just early ones.

⚠️ Gate rushing is a failure mode. Each gate completed requires proof in the description.

Gate requirements (gate cannot complete until execution tasks show evidence):

• Planning: PASS: Research=[tools used]

  • Requirements: research complete (mcp__octocode__* for code, mcp__context7__* for docs, mcp__exa__* for web).

• Refinement: PASS: Questions=[count or N/A if Remote]

  • Requirements: "Ask clarifying questions" task completed with evidence. Local: AskUserQuestion tool used. Remote: questions optional unless genuinely ambiguous.

• Implementation: PASS: TDD=[red+green done] | Backfill=[done/N/A]

  • Requirements: "Write failing tests (TDD red)" task completed + "Make tests pass (TDD green)" task completed + backfill check done.

• Cleanup: PASS: Deslop=[done] | Simplifier=[done]

  • Requirements: "Run deslop on changed files" task completed with diff shown + "Run code-simplifier" task completed.

• Testing: PASS: Tests=[N passed, N failed] | Exit=[code]

  • Requirements: test output with exit code shown.

• Review: PASS: Reviewers=[dispatched] | Fixes=[dispatched] | Rerun=[done or N/A]

  • Requirements: "Dispatch parallel reviewers" + "Dispatch parallel fixes" + "Re-run failed reviewers" all completed with evidence.

• Verification: PASS: Commands=[run] | Exit=[0]

  • Requirements: "Run verification commands" task completed with exit code 0 shown.

• CI: PASS: CI=[command] | Exit=[0]

  • Requirements: bun run ci executed with exit code 0 shown.
  • NOTE: CI commands use turborepo—run from repository root folder.
  • NOTE: Infrastructure services may be required—launch with bun dev:up.
  • NOTE: When package.json does not exist (non-Node repos), substitute: shellcheck for .sh files, markdownlint for .md files. Document the substitution.

• Integration: PASS: Integration=[Exit 0 or N/A]

  • Requirements: bun run test:integration executed with exit code 0 (or N/A if unavailable).
  • Prerequisite: CI must pass first.
  • NOTE: When package.json does not exist, document N/A with justification.

• Session End: PASS: Workflow-improver=[done]

  • Requirements: "Run workflow-improver analysis" task completed with session analysis output shown.

Execution ≠ Loading: Calling Skill() just loads instructions. The execution task tracks actually DOING what the skill documents.

Pre-Completion Gate

Before claiming done, the task list must show all gate tasks as completed. No exceptions.

Banned phrases: "looks good", "should work", "Done!", "it's just a port", "manual review", "pre-existing", "not related to my changes"

Failure deflection (ZERO TOLERANCE): Any claim that failures are "pre-existing" or "not related to my changes" is FORBIDDEN. Main always passes. If anything fails, you broke it.

Plan Mode Integration

When system-reminder indicates "Plan mode is active":

1. First: Create Planning and Refinement gate tasks
2. Then: Update Planning to in_progress, do research, then completed
3. Then: Update Refinement to in_progress, write plan, then completed
4. Finally: Call ExitPlanMode when plan is complete
5. After approval: Create remaining gate tasks

Plan Mode maps to workflow phases:

• Planning → Phase 1 (Planning)
• Refinement → Phase 2 (Plan Refinement)
• After approval → Phase 3+ (Implementation onwards)

Plan Mode does NOT exempt you from:

• Gate task creation (create Planning and Refinement minimum, rest after approval)
• Skill loading (ask-questions-if-underspecified before Refinement completion)
• AskUserQuestion tool usage (never plain text questions)

---

4. Anti-Patterns (Never)

Workflow Bypass

• Workflow skip: "task is simple" to skip gates -> follow ALL gates, no exceptions.
• Direct implementation: code before task tracking -> call TaskCreate + TaskUpdate({ status: "in_progress" }) first.
• Task dependency skip: ignoring task ordering -> use TaskUpdate({ addBlockedBy: [...] }) for dependent tasks.
• Task status neglect: not updating task status -> always set in_progress before work, completed after.
• False task completion: marking a task as completed without performing the work -> NEVER mark a task completed without doing it. If not applicable, mark completed with clear N/A justification AND output why before marking.
• Rush-to-completion: marking workflow-improver or any final-phase task as completed to finish faster -> final-phase tasks exist for a reason; skipping them is a violation.

Text Checklist Theater (CRITICAL)

Text checklists don't work. Claude forgets requirements that aren't tracked as Tasks.

• Text requirements: stating requirements in prose without creating tasks → EVERY requirement must be a TaskCreate item
• Markdown checkboxes: outputting - [ ] Do X without calling TaskCreate → call TaskCreate, not markdown
• Self-check in context: "search context for X" → use TaskCreate execution tasks, not context search
• Gate without execution tasks: creating Review gate without "Run codex review" task → execution must be tracked
• Skill load without execute: calling Skill() but not doing what it documents → TaskCreate tracks EXECUTION, not loading
• Marking execution complete without evidence: "Run codeql scan" marked done without showing output → must show results

The rule: If it's not a TaskCreate item, it won't happen. Period.

Skill Failures

• Skill avoidance: no execution tasks for skills → create execution tasks like "Run codex review --uncommitted"
• Skill mention vs execute: "I'll use TDD" without executing TDD workflow → complete "Write failing tests" and "Make tests pass" tasks
• Load without execute: invoked Skill() but didn't complete the execution task → loading is step 1, execution (with evidence) is what counts
• TDD theater: marked "Write failing tests" complete without showing failing test output → evidence required
• Fake ask-questions: marked "Ask clarifying questions" complete without using AskUserQuestion → tool usage required (Remote: N/A is acceptable)
• Plain text questions: asked questions in markdown instead of AskUserQuestion tool → FORBIDDEN

Decision Question Patterns (MUST use AskUserQuestion)

These phrases in assistant messages = VIOLATION if not using the tool:

• Would you like me to...? → Use AskUserQuestion with options
• Should we...? / Should I...? → Use AskUserQuestion with yes/no or options
• Do you want...? → Use AskUserQuestion with options
• Which would you prefer...? → Use AskUserQuestion with the options listed
• Could you clarify...? → Use AskUserQuestion
• What should I...? → Use AskUserQuestion with options

ALLOWED without tool (rhetorical/explanatory):

• Questions analyzing the problem: "The question is whether X works with Y..."
• Questions in code comments or documentation
• Questions quoting the user back to them

Gate Task Failures

• Gate task amnesia: create Planning, Implementation, then forget the rest -> create ALL gate tasks at the start.
• Gate task rushing: marking gate completed without doing the work -> gates verify work, not skip it.
• Proofless completion: status: completed without proof in description -> add PASS: [key]=[evidence] | ... to description.
• Early gate only: stop at Implementation because "implementation is done" -> Cleanup through Integration still required.
• False completion: marking gate completed when requirements not met -> keep in_progress with BLOCKED: [reason] in description.
• Gate task skip: not creating gate tasks at all -> MUST create all gate tasks at the start.

Phase Skipping

• Phase 2 skip: "requirements are clear" → Local: complete "Ask clarifying questions" task. Remote: mark N/A if ambiguity ≤ 7.
• Phase 6 skip: "code is simple, doesn't need review" → ALL review execution tasks must complete with evidence.
• Codex skip: "Run codex review" task not completed with output shown → BLOCKED. Show the codex output.
• Deslop skip: "Run deslop" task skipped "because code is clean" → run it anyway, show output.
• Codeql skip: "Run codeql scan" task skipped → BLOCKED. The skill itself determines applicability, not the agent pre-emptively.
• Reviewers skip: "Run reviewers skill prompts" skipped because "only shell/markdown changes" → invoke the skill; it determines relevance, not the agent.
• Workflow-improver skip: "Run workflow-improver" task not completed at session end → session incomplete. This must be the absolute last task completed.

Verification Failures

• Unverified completion: "Run verification commands" task not completed with exit code 0 shown → execute and show output.
• Partial verification: "syntax check passed" as full verification → run project CI, show full output.
• Stale evidence: "tests passed earlier" → run fresh verification, show current output.
• Execution task incomplete: "Run verification commands" marked complete without showing command output → evidence required.
• CI skip: CI task not completed with bun run ci exit code 0 shown → CI must pass.

Implementation Failures

• Sequential when parallel possible: executing 2+ independent tasks one-by-one with Bash -> use parallel Task agents.
• Bash familiarity bias: defaulting to sequential bash "because it's simpler" -> check skill routing table for dispatching-parallel-agents.
• Agent avoidance: "file operations are quick" to skip parallel agents -> if tasks are independent, parallelize.
• Unnamed agents: spawning agents without name parameter -> use names for tracking (e.g., name: "test-runner").
• Overly permissive mode: using mode: "bypassPermissions" for risky/security tasks -> use mode: "plan" for changes requiring review.
• Mode omission: not specifying mode when context requires it -> explicitly set mode based on task risk level.

Failure Deflection (CRITICAL)

THIS IS THE MOST SEVERE ANTI-PATTERN. ZERO TOLERANCE.

Applies to: CI failures, test failures, lint errors, type errors, build failures, ANY verification failure.

• "Pre-existing issues": claiming failures are "not related to my changes" or "pre-existing in the codebase" -> ABSOLUTELY FORBIDDEN. Main branch ALWAYS passes (otherwise PRs cannot merge). If anything fails, YOUR changes broke it.
• "My tests pass": claiming success because "the specific tests I created pass" while ignoring other failures -> UNACCEPTABLE

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->