--- name: clarc-way description: "The clarc Way — opinionated end-to-end software development methodology. 8-stage pipeline from idea to shipped code: /idea → /evaluate → /explore → /prd → /plan → /tdd → /code-review → commit. Activate when a user asks how to structure their workflow, which commands to use, or when to use clarc." --- # The clarc Way An opinionated, end-to-end methodology for professional software development with Claude Code. Not a tool collection — a structured process from raw idea to shipped code. ## When to Activate - User asks "where do I start?" or "what should I do first?" - User is unsure which commands or agents to use - User wants to understand the recommended workflow - Starting a new feature, fixing a bug, or refactoring - Onboarding a developer who is new to clarc and needs a guided tour of the full pipeline from idea to merged PR - Deciding which phases to skip for a well-defined ticket versus an exploratory feature with unclear scope - Explaining why quality gates (TDD, code review, security scan) are mandatory steps rather than optional add-ons - Comparing the clarc way to another AI-assisted development framework like SPARC or a custom workflow --- ## The Pipeline ``` ┌─────────────────────────────────────────────────────────────────┐ │ THE CLARC WAY │ │ │ │ Phase 0: Discovery (new features only) │ │ ───────────────────────────────────── │ │ /idea → /evaluate → /explore → /prd │ │ │ │ Phase 1: Planning │ │ ───────────────────────────────────── │ │ /plan → architecture + task breakdown │ │ │ │ Phase 2: Implementation │ │ ───────────────────────────────────── │ │ /tdd → RED (write failing test) │ │ → GREEN (minimal implementation) │ │ → IMPROVE (refactor) │ │ │ │ Phase 3: Quality │ │ ───────────────────────────────────── │ │ /code-review → fix CRITICAL + HIGH │ │ /security → (when auth/APIs involved) │ │ │ │ Phase 4: Ship │ │ ───────────────────────────────────── │ │ git commit (conventional format) │ │ + push + PR via commit-commands skills │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## Skip Matrix Not every phase is required for every task. Use this table to decide: | Task Type | Phase 0 | Phase 1 | Phase 2 | Phase 3 | Phase 4 | |-----------|---------|---------|---------|---------|---------| | New feature (unknown value) | ✅ | ✅ | ✅ | ✅ | ✅ | | New feature (clear spec) | ⏭ | ✅ | ✅ | ✅ | ✅ | | Bug fix | ⏭ | ⏭ | ✅ | ✅ | ✅ | | Refactor | ⏭ | ✅ | ✅ | ✅ | ✅ | | Chore / dependency update | ⏭ | ⏭ | ⏭ | ⏭ | ✅ | | Documentation only | ⏭ | ⏭ | ⏭ | ⏭ | ✅ | --- ## Phase 0: Discovery > Run only for new features whose value or approach is not yet clear. ``` /idea ``` Structures the raw idea: problem statement, target user, success metric. Output: `docs/ideas/YYYY-MM-DD-.md` ``` /evaluate ``` Go / No-Go / Modify recommendation. Uses the `product-evaluator` agent. **Stop here if No-Go.** Do not proceed to implementation. Output: `docs/evals/YYYY-MM-DD--eval.md` ``` /explore ``` Generates 2–4 solution options with trade-off analysis and Architecture Decision Record. Output: `docs/decisions/-adr.md` ``` /prd ``` Full Product Requirements Document synthesizing idea + eval + ADR. Output: `docs/specs/-prd.md` --- ## Phase 1: Planning ``` /plan ``` Invokes the `planner` agent: 1. Restates requirements in unambiguous terms 2. Breaks work into phases with specific, actionable steps 3. Identifies dependencies and risks 4. **Waits for explicit confirmation before any code is written** --- ## Phase 2: Implementation (TDD) ``` /tdd ``` Enforces write-tests-first via the `tdd-guide` agent: 1. **RED** — write a failing test that captures the desired behavior 2. Run test → confirm it fails for the right reason 3. **GREEN** — write minimal code to make the test pass 4. Run test → confirm it passes 5. **IMPROVE** — refactor while keeping tests green 6. Verify coverage is 80%+ Never skip the failing test step. A test that never failed proves nothing. --- ## Phase 3: Quality Gates These are not optional. They run after implementation, before commit. ``` /code-review ``` Routes to the right language specialist automatically (TypeScript, Go, Python, etc.). Fix all CRITICAL and HIGH findings. Address MEDIUM where feasible. ``` /security ``` Run when the change touches: authentication, user input, API endpoints, secrets, database access. Scans for OWASP Top 10, secrets, injection vectors, SSRF. --- ## Phase 4: Ship Ask Claude to generate a conventional commit message from staged changes: ``` Format: : Types: feat, fix, refactor, docs, test, chore, perf, ci ``` Use the `commit-commands:commit` skill for a git commit, or `commit-commands:commit-push-pr` to commit + push + open a PR in one step. --- ## Principles **Convention over Configuration** clarc selects the right tools. You focus on the problem. **Quality Gates are Mandatory** TDD + Code Review + Security are not checkboxes — they are the output. **Continuous Improvement** Session learnings become instincts via `/learn-eval`. Instincts become permanent skills via `/evolve`. **Opinionated, not Dogmatic** Phases can be skipped when genuinely not needed. The skip matrix above is the guide. --- ## Bug Fix Walkthrough Bug fixes skip Phase 0 (no discovery needed) and Phase 1 (no upfront plan for a known defect). Start directly at Phase 2 with a failing test. **Scenario:** `getUserById` returns `null` instead of throwing when the user does not exist. ``` # 1. Write the failing test first (RED) /tdd → [tdd-guide] Write: test_getUserById_throws_when_user_not_found → Run: npm test -- --testNamePattern getUserById → Confirm: test FAILS (currently returns null, not throws) # 2. Fix the implementation (GREEN) → Edit src/api/users.ts: throw NotFoundError when db returns null → Run: npm test -- --testNamePattern getUserById → Confirm: test PASSES # 3. Quality gate before commit /code-review → [typescript-reviewer] MEDIUM: missing error type export — fix it → Run: npm test (full suite, all green) # 4. Commit → git commit -m "fix: throw NotFoundError when getUserById receives unknown id" ``` **What was skipped:** `/idea`, `/evaluate`, `/explore`, `/prd`, `/plan` — all unnecessary for a well-understood defect. **What was not skipped:** `/tdd` (failing test first), `/code-review` (quality gate before commit). --- ## Comparison: clarc Way vs. SPARC | Dimension | clarc Way | SPARC (ruflo) | |-----------|-----------|---------------| | Phases | 5 (Discovery → Ship) | 5 (Spec → Completion) | | Tool integration | Every phase has dedicated commands + agents | Framework-level, less tooling | | Quality gates | Mandatory (/code-review, /security) | Refinement phase | | Learning loop | Instincts → Skills (automated) | Manual | | Entry point | `/clarc-way` (interactive guide) | SPARC template | | TDD enforcement | `/tdd` with agent enforcement | Part of refinement | --- ## Quick Reference | Situation | Start here | |-----------|-----------| | "I have a new idea" | `/idea` | | "Should I build this?" | `/evaluate` | | "I know what to build, where do I start?" | `/plan` | | "Fix this bug" | `/tdd` (write the failing test first) | | "Review my code" | `/code-review` | | "I'm done, ship it" | `commit-commands:commit-push-pr` | | "What has clarc learned?" | `/instinct-status` | | "Show me all commands" | `/find-skill` |