| 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 <description>
Structures the raw idea: problem statement, target user, success metric.
Output: docs/ideas/YYYY-MM-DD-<name>.md
/evaluate <name>
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-<name>-eval.md
/explore <name>
Generates 2–4 solution options with trade-off analysis and Architecture Decision Record.
Output: docs/decisions/<name>-adr.md
/prd <name>
Full Product Requirements Document synthesizing idea + eval + ADR.
Output: docs/specs/<name>-prd.md
Phase 1: Planning
/plan <what to build>
Invokes the planner agent:
- Restates requirements in unambiguous terms
- Breaks work into phases with specific, actionable steps
- Identifies dependencies and risks
- Waits for explicit confirmation before any code is written
Phase 2: Implementation (TDD)
/tdd
Enforces write-tests-first via the tdd-guide agent:
- RED — write a failing test that captures the desired behavior
- Run test → confirm it fails for the right reason
- GREEN — write minimal code to make the test pass
- Run test → confirm it passes
- IMPROVE — refactor while keeping tests green
- 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: <type>: <description>
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 |
