directions

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

Read-on-demand model: the universal docs in this repo are the single source of truth. They are never copied into your projects — copies drift and stop receiving updates. Claude reads them on demand from your local clone of this repo, routed by the Directions Index in your global ~/.claude/CLAUDE.md.

Install once (per machine)

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

Then open ~/.claude/CLAUDE.md and replace every [LOCAL_DIRECTIONS_PATH] placeholder with the path to your local clone (the install script prints it).

For New Projects

1. Open a Claude session in your project and run /setup — it scaffolds only the project-specific files: docs/PROJECT_STATE.md (the "is Directions set up?" sentinel), docs/sessions/, docs/decisions.md, docs/glossary.md. Nothing else is copied.
2. Run /spec deep to create your first spec
3. Run /make-plan to break into tasks, /execute to build

For Existing Projects (older copied-docs layout)

If a project still contains copied universal docs (docs/00_base.md, docs/20_*.md, …), run /directions update — it removes the stale copies and switches the project to read-on-demand. Your project-specific files (state, sessions, decisions) are untouched.

Core Workflow

/spec  →  /make-plan  →  /execute  →  /check  →  /log
   │           │            │           │          │
 Spec        Tasks        Build      Review      Learn

---

File Structure

your-project/
├── CLAUDE.md                     ← Project-specific AI context
├── IMPLEMENTATION_PLAN.md        ← Active task list (waves, delete when done)
├── AGENTS.md                     ← Subagent patterns & context
├── specs/                        ← Feature specifications
│   └── [feature].md
└── docs/                         ← Scaffolded by /setup — project files ONLY
    ├── PROJECT_STATE.md          ← Current funnel position (the sentinel)
    ├── sessions/                 ← Session logs
    ├── decisions.md              ← Why we chose X over Y
    └── glossary.md               ← Project-specific terms

LLM-Directions/ (this repo — read on demand, never copied)
├── 00_base.md                    ← System overview + document router
├── 01_quick-reference.md         ← Daily cheatsheet
├── 04_architecture-decisions.md  ← Interview → tech mapping
├── PATTERNS-COOKBOOK.md          ← Pattern index (patterns live in cookbook/)
├── 10-19: Setup docs
├── 20-29: Technical gotchas
├── 30-39: Quality & debugging
├── 40-49: Terminology reference
└── 50-62: Advanced patterns

---

Key Commands

Command	Phase	Purpose
/spec (deep, examples)	Define	Multi-phase discovery, example mapping, creates spec
/make-plan	Plan	Creates IMPLEMENTATION_PLAN.md with waves
/execute (next)	Build	Wave-based execution with subagents; pick next task
/check (code, ship, security)	Review	Code quality, production checklist, security audit
/log	Learn	Update session log; also covers end-of-session close, handoff, blockers, phase changes
/status (full, arrive)	Any	Current state summary; full dump; sit-down handover check

Other Commands