Directions

A systematic approach to AI-assisted software development.

For people who direct AI to build software but don't code themselves.

---

What This Is

Directions is a documentation and workflow system that helps you:

1. Define clearly - Multi-phase discovery creates specs with acceptance criteria
2. Plan atomically - Break work into <30 min tasks with validation
3. Build with fresh context - Wave-based execution prevents context degradation
4. Validate rigorously - Backpressure and multi-perspective review
5. Compound learnings - Extract patterns so you never solve the same problem twice

---

The Funnel

Every feature flows through three phases:

DEFINE ──gate──> PLAN ──gate──> BUILD
   │                │              │
   ▼                ▼              ▼
  Spec        Task List      Working Code

Principle: 80% on Define + Plan, 20% on Build.

---

Quick Start

For New Projects

1. Copy this folder to your project as /docs
2. Add to your CLAUDE.md:

   ## Context
   Read docs/00_base.md at the start of every session.
   Check docs/PROJECT_STATE.md for current focus.

3. Start a Claude session - run /interview to create your first spec
4. Run /plan to break into tasks, /execute to build

Core Workflow

/interview  →  /plan  →  /execute  →  /reflect  →  /compound
    │            │           │            │            │
  Spec       Tasks       Build        Review      Learn

---

File Structure

project/
├── CLAUDE.md                     ← Project-specific AI context
├── PROJECT_STATE.md              ← Current funnel position
├── IMPLEMENTATION_PLAN.md        ← Active task list (waves)
├── AGENTS.md                     ← Subagent patterns & context
│
├── specs/                        ← Feature specifications
│   └── [feature].md
├── sessions/                     ← Session logs
├── decisions.md                  ← Why we chose X over Y
└── ideas.md                      ← Backlog with phase tracking

docs/ (Directions reference)
├── 00_base.md                    ← Start here every session
├── 01_quick-reference.md         ← Daily cheatsheet
├── 03_workflow-phases.md         ← The funnel process
├── 04_architecture-decisions.md  ← Interview → tech mapping
├── PATTERNS-COOKBOOK.md          ← Reusable code patterns
├── 10-19: Setup docs
├── 20-29: Technical gotchas
├── 30-39: Quality & debugging
├── 40-49: Terminology reference
└── 50-59: Advanced patterns

---

Key Commands

Command	Phase	Purpose
/interview	Define	Multi-phase discovery, creates spec
/plan	Plan	Creates IMPLEMENTATION_PLAN.md with waves
/execute	Build	Wave-based execution with subagents
/next	Build	Pick next task with full context
/reflect	Review	Multi-perspective code review
/compound	Learn	Extract reusable patterns
/status	Any	Current state summary
/log	Any	Update session log

Other Commands

Command	Purpose
/setup	Detect project state, offer setup/migration
/decide	Record an architectural decision
/learned	Add term to personal glossary
/cookbook	Manage reusable code patterns
/phase	Change project phase
/review	Production checklist
/new-feature	Scaffold docs for new feature
/directions	Show all available commands

---

Key Concepts

Backpressure

Every task has validation that must pass before commit:

swift build   # Compiles?
swiftlint     # Clean?
swift test    # Tests pass?

No commit until green.

Waves

Tasks grouped by dependencies:

• Wave 1: Parallel (no dependencies)
• Wave 2: Depends on Wave 1
• Final: Verification

Compounding

After each session, extract learnings:

• Patterns → AGENTS.md
• Terms → 44_my-glossary.md
• Decisions → decisions.md

Patterns Cookbook

Reusable code patterns extracted from production apps. Copy-first beats building new.

/cookbook         # Update cookbook (rescan for patterns)
/cookbook add     # Quick-add a pattern you just built
/cookbook search  # Search existing patterns

Included patterns:

• Window layouts (NavigationSplitView, HSplitView, multi-window)
• Export dialogs (NSSavePanel, NSOpenPanel, progress indicators)
• App lifecycle (initialization order, scene phase handling)
• MCP memory integration (Vestige patterns)

See PATTERNS-COOKBOOK.md for full code snippets.

---

Installation

Option 1: Plugin Install (Recommended)

git clone https://github.com/Xpycode/LLM-Directions.git
cd LLM-Directions
./install-directions.sh

Or manually:

mkdir -p ~/.claude/plugins/local
ln -sf /path/to/LLM-Directions ~/.claude/plugins/local/directions
cp commands/* ~/.claude/commands/
cp CLAUDE-GLOBAL-TEMPLATE.md ~/.claude/CLAUDE.md

Option 2: Commands Only

cp -r commands/* ~/.claude/commands/

---

Hooks (Plugin Only)

Hook	Trigger	Behavior
SessionStart	New session	Auto-loads project state
Stop	Ending session	Reminds to run /log
UserPromptSubmit	Every prompt	Suggests relevant docs
PostToolUse	After commits	Suggests /decide for architecture

---

Patterns Adopted From

• Ralph Playbook - Funnel methodology, backpressure
• Compound Engineering - Learning extraction
• Context Engineering Kit - Reflexion patterns
• miniPM - Task phase progression
• Deep Research Skill - Multi-phase discovery
• Simone - Project management framework

---

Origin

Synthesized from 229 documentation files across 15+ shipped macOS/iOS projects, enhanced with community patterns from the Claude Code ecosystem.

---

License

MIT - Use freely, modify as needed.