clarc-way

# 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:
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: <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` |