README

# Claude Code Commands

**Complete workflow system for AI-assisted development with Linear integration, session logging, and quality gates.**

**📚 Workflow Documentation**: See `docs/workflows/` for detailed guides:
- `PARALLEL-EPIC-IMPLEMENTATION.md` - Complete parallel epic workflow guide (validated: BE-128, 80-90x speedup)
- `PARALLEL-EPIC-QUICK-REFERENCE.md` - Quick reference for parallel implementation
- `WHY-BE-128-WAS-SO-SMOOTH.md` - Process analysis: what's replicable vs. luck

---

## 🚀 Quick Start (Most Common Workflows)

### 1. Plan & Decompose
```bash
/plan "Add Redis caching to user service"

What it does:

• Analyzes requirements with interactive Q&A
• Decomposes into atomic issues with labels
• Generates structured YAML definition
• Stops here - doesn't create issues yet

Output: issue-plan-redis-caching.yaml (review before creating issues!)

Why it stops: Each phase runs in NEW context window for full session logging

---

2. Create Linear Issues

/create-issues issue-plan-redis-caching.yaml

What it does:

• Creates epic + all sub-issues in Linear
• Links children to epic
• Applies labels from YAML
• Sets status to Refinement
• Returns: {epic: "BE-100", children: ["BE-101", ...]}

Output: Linear issues in Refinement status (ready for spec generation)

---

3. Generate Detailed Spec

/feature BE-101

What it does:

• Deep codebase research (10-15 minutes)
• Identifies patterns and similar implementations
• Generates comprehensive implementation plan
• Updates Linear issue to Ready status
• Creates specs/issue-BE-101-{description}.md

When to use: After /create-issues creates issues in Linear

---

4. Implement with TDD

/implement BE-101

What it does:

• Ensures on feature branch (creates if needed)
• Reads spec from specs/ directory
• Follows TDD workflow (tests first)
• Runs quality gates (format, lint, typecheck)
• Commits incrementally with proper messages

Branch safety: Automatically checks out/creates feature branch before committing

---

5. Run Quality Gates

/test

What it does:

• Runs format, lint, typecheck, architecture validation
• Runs full test suite
• Auto-fixes issues when possible
• Loops until all gates pass

---

6. Create Pull Request

/pr BE-101

What it does:

• Creates GitHub PR with comprehensive summary
• Links to Linear issue
• Includes test plan and changes
• Adds traceability (session logs, commit history)

---

📁 Folder Structure

.claude/commands/
├── plan.md                    # 🎯 Primary: Decompose requirements
├── implement.md               # 🎯 Primary: TDD implementation
├── test.md                    # 🎯 Primary: Quality gates
│
├── spec-generation/           # 📦 Subsystem: Spec generation
│   ├── feature.md             #    /feature - Feature specs (use this!)
│   ├── generate-spec.md       #    Engine (called by wrappers)
│   └── [future: bug.md, chore.md, patch.md]
│
├── utilities/                 # 🔧 Reusable utilities
│   └── ensure-feature-branch.md  # Branch safety (called by /implement)
│
├── shared/                    # 📚 Shared patterns
│   └── session-logging.md     # Session management framework
│
├── issues/                    # 📋 Issue management
│   └── create-issues.md       # Issue creation (called by /plan)
│
└── [other subsystems...]

---

🔄 Complete Workflow Example

IMPORTANT: Run each step in a NEW context window for full session logging!

# 1. Decompose requirements (NEW context)
/plan "Add batch update operations to tp CLI"
# → Interactive Q&A
# → Generates: issue-plan-batch-operations.yaml
# → STOPS here

# 2. Review YAML
cat issue-plan-batch-operations.yaml
# → Review epic + sub-issues structure
# → Edit if needed

# 3. Create Linear issues (NEW context)
/create-issues issue-plan-batch-operations.yaml
# → Creates TASK-23 (epic) + TASK-24..28 (children)
# → Returns: {epic: "TASK-23", children: ["TASK-24", ...]}

# 4. Generate spec for each issue (NEW context for each)
/feature TASK-24  # Sub-issue 1
/feature TASK-25  # Sub-issue 2
# → Each runs deep research
# → Each creates detailed spec
# → Each has own session log

# 5. Implement (NEW context)
/implement TASK-24
# → Ensures on feature/TASK-23-batch-operations branch
# → TDD workflow
# → Quality gates
# → Commits

# 6. Test (NEW context)
/test

# 7. Create PR (NEW context)
/pr TASK-24
# → Full traceability across all sessions

Why separate contexts?

• Complete session logging for each phase
• Full observability: agent-logs/ has session for each step
• Can pause/resume workflow at any point
• Clear separation of concerns

---

🎨 Workflow Philosophy

Read-Only Workflows (No Commits)

These stay on your current branch (typically main):

• /plan - Generates YAML definition only (no Linear calls)
• /create-issues - Creates Linear issues from YAML (no local files)
• /feature - Writes spec files (not committed yet)
• /generate-spec - Advanced spec generation (use /feature instead)

Why? You can review each output before the next step

Commit-Making Workflows (Branch Required)

These ensure you're on a feature branch:

• /implement - Writes code + commits → calls /ensure-feature-branch
• /pr - Creates PR (assumes feature branch exists)

Safety: Branch protection + /ensure-feature-branch prevents accidental main commits

---

📦 Subsystems Explained

Spec Generation (spec-generation/)

Use /feature for features (most common):

/feature BE-101
# → Calls /generate-spec with type=feature
# → Deep research, comprehensive phases, extensive testing

Future wrappers:

• /bug BE-102 → Focused on reproduction + fix
• /chore BE-103 → Lightweight, minimal testing
• /patch BE-104 → Quick targeted fixes

Advanced: Call /generate-spec directly for custom behavior:

/generate-spec BE-101 --type=feature --s