Context Engineering

A filesystem-based context system with autonomous workflows and native Teams traceability.

Philosophy: 80% planning, 20% execution. Each unit of work makes the next easier. Every feature gets a persistent trace of what was built, why, and how.

Quick Start

Full Workflow (Recommended)

/lets-ship "add stripe payments"

Runs: understand > plan > work > review > compound. Human approves at gates. Teams + tasks persist as queryable trace.

Autonomous Mode

/lets-ship --auto "fix login timeout"

Skips all gates. Auto-fixes review issues (max 2 iterations). Auto-creates PR.

Individual Commands

/spec feat payments      # Create spec with auto-research
/work                    # Execute current spec
/review                  # Multi-agent code review
/compound                # Capture learnings + rate spec
/status                  # See where you are
/status --teams          # View team history

Commands

Command	Purpose	Team Members
lets-ship	Full workflow with teams + traceability	research, review
spec	Create spec with research	repo, learnings
work	Execute spec task-by-task	—
review	Multi-perspective code review	simplicity, spec, bug-hunter
compound	Capture learnings + rate spec	—
status	Progress, specs, team history	—
deepen	Research to improve spec	options
audit	Audit codebase docs, generate specs	hierarchical swarm

Directory Structure

context/
├── foundation/    # Human-authored truth (read-only for agents)
│   ├── architecture.md
│   ├── conventions.md
│   └── gotchas.md
├── specs/         # Feature/fix/improve definitions
│   └── 2026-01-26-feat-payments.md
└── tasks/         # (Optional) Atomic task breakdowns
    └── feat001-task001-setup.md

docs/
└── solutions/     # Captured learnings from /compound
    └── 2026-01-26-stripe-webhooks.md

~/.claude/
├── teams/ship-<slug>-<date>/    # Team config (persists as trace)
└── tasks/ship-<slug>-<date>/    # Task history (persists as trace)

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│  /lets-ship "feature description" [--auto]                  │
├─────────────────────────────────────────────────────────────┤
│  0. BOOTSTRAP — cold start if no context/ (create dirs,    │
│     interactive Q&A, generate foundation)                    │
│     + TeamCreate("ship-<slug>-<date>")                      │
├─────────────────────────────────────────────────────────────┤
│  1. UNDERSTAND — load foundation, spawn research agents     │
│     Team: repo-researcher, learnings-researcher             │
│     Gate: confirm understanding                             │
├─────────────────────────────────────────────────────────────┤
│  2. PLAN — create spec with acceptance criteria             │
│     Gate: approve / deepen / refine / simplify              │
├─────────────────────────────────────────────────────────────┤
│  3. WORK — execute via TaskCreate, incremental commits      │
│     Gate: ready for review?                                 │
├─────────────────────────────────────────────────────────────┤
│  4. REVIEW — spawn reviewer team members                    │
│     Team: simplicity-reviewer, spec-reviewer, bug-hunter    │
│     Gate: fix / ship / discuss                              │
├─────────────────────────────────────────────────────────────┤
│  5. COMPOUND — capture learnings, rate spec                 │
│     Gate: create PR / continue / done                       │
│     Shutdown team (trace persists)                          │
└─────────────────────────────────────────────────────────────┘

Agents

Spawned as team members (traced) during workflows:

Agent	When Used	Purpose
repo-researcher	/lets-ship, /spec	Find relevant codebase patterns
learnings-researcher	/lets-ship, /spec	Surface past learnings
options-researcher	/deepen	Research approaches, present options
simplicity-reviewer	/review, /lets-ship	Challenge complexity
spec-reviewer	/review, /lets-ship	Check spec compliance
bug-hunter	/review, /lets-ship	Hunt for bugs and security issues
context-worker	/work	Context-aware implementation

See rules/agents.md for subagent vs team member decision matrix.

Rules

Rule	Key Point
planning	80% planning, 20% execution
foundation	Foundation is read-only for agents
learnings	Always run /compound after features
agents	Subagents (disposable) vs team members (traced)

See rules/ for complete guidelines.

Integrations

Integration	Description
Linear	Bidirectional sync with Linear issues

Templates

Philosophy

Compound Engineering: Each unit of work should make subsequent units easier.

Plan thoroughly before writing code
Review to catch issues and capture learnings
Codify knowledge so it's reusable
Keep quality high so future changes are easy
Trace everything so you know what happened and why

Inspired by compound-engineering, adapted for filesystem-based context management with native Teams traceability.

context-engineering