context-driven-development

# Context-Driven Development

Treat project context as a first-class artifact managed alongside code. Instead of relying on ad-hoc prompts or scattered documentation, establish a persistent, structured foundation that informs all AI interactions.


## Installation

### OpenClaw / Moltbot / Clawbot

```bash
npx clawhub@latest install context-driven-development
```


## WHAT This Skill Does

Creates and maintains a set of context documents that:
- Define what you're building and why (product.md)
- Specify technology choices and constraints (tech-stack.md)
- Establish how the team works (workflow.md)
- Track what's happening (tracks.md)

## WHEN to Use

**Use for:**
- Setting up new projects with AI-assisted development
- Onboarding team members to existing codebases
- Ensuring consistent AI behavior across sessions
- Documenting decisions that affect code generation
- Managing projects with multiple contributors or AI assistants

**Skip for:**
- Solo experiments or throwaway prototypes
- Single-file scripts
- Projects without AI assistance

**Keywords:** context, project setup, documentation, AI alignment, team workflow, product vision, tech stack

## Core Philosophy

```
Context precedes code.
Living documentation.
Single source of truth.
AI alignment.
```

1. **Context precedes code** — Define what you're building and how before implementation
2. **Living documentation** — Context artifacts evolve with the project
3. **Single source of truth** — One canonical location for each type of information
4. **AI alignment** — Consistent context produces consistent AI behavior

## The Workflow

```
Context → Spec & Plan → Implement
```

1. **Context Phase:** Establish or verify project context artifacts exist and are current
2. **Specification Phase:** Define requirements and acceptance criteria for work units
3. **Planning Phase:** Break specifications into phased, actionable tasks
4. **Implementation Phase:** Execute tasks following established workflow patterns

## The Context Documents

### product.md — WHAT and WHY

Purpose: Captures product vision, goals, target users, and business context.

**Contents:**
- Product name and one-line description
- Problem statement and solution approach
- Target user personas
- Core features and capabilities
- Success metrics and KPIs
- Product roadmap (high-level)

**Update when:**
- Product vision or goals change
- New major features are planned
- Target audience shifts

### tech-stack.md — WITH WHAT

Purpose: Documents technology choices, dependencies, and architectural decisions.

**Contents:**
- Primary languages and frameworks
- Key dependencies with versions
- Infrastructure and deployment targets
- Development tools and environment
- Testing frameworks
- Code quality tools

**Update when:**
- Adding new dependencies
- Upgrading major versions
- Changing infrastructure
- Adopting new tools or patterns

### workflow.md — HOW to Work

Purpose: Establishes development practices, quality gates, and team workflows.

**Contents:**
- Development methodology (TDD, trunk-based, etc.)
- Git workflow and commit conventions
- Code review requirements
- Testing requirements and coverage targets
- Quality assurance gates
- Deployment procedures

**Update when:**
- Team practices evolve
- Quality standards change
- New workflow patterns are adopted

### tracks.md — WHAT'S HAPPENING

Purpose: Registry of all work units with status and metadata.

**Contents:**
- Active tracks with current status
- Completed tracks with completion dates
- Track metadata (type, priority, assignee)
- Links to individual track specs

**Update when:**
- New work starts
- Work status changes
- Work completes

## Directory Structure

```
context/
├── product.md            # Product vision and goals
├── tech-stack.md         # Technology choices
├── workflow.md           # Development practices
├── tracks.md             # Work unit registry
└── styleguides/          # Language-specific conventions
    ├── python.md
    ├── typescript.md
    └── ...
```

## Setup: New Project (Greenfield)

For new projects, create all artifacts from scratch:

1. **Create `context/product.md`:**
   - Define the problem you're solving
   - Describe target users
   - List core features for v1
   - Define success metrics

2. **Create `context/tech-stack.md`:**
   - Choose languages and frameworks
   - Document key dependencies with versions
   - Specify infrastructure targets
   - List development tools

3. **Create `context/workflow.md`:**
   - Define branching strategy
   - Set commit conventions
   - Establish testing requirements
   - Document deployment process

4. **Create `context/tracks.md`:**
   - Start with empty registry
   - Add work units as they're created

## Setup: Existing Project (Brownfield)

For existing codebases, extract context from what exists:

1. **Analyze the codebase:**
   - Read package.json, requirements.txt, go.mod, etc.
   - Look at existing README and docs
   - Check git history for patterns

2. **Create `context/tech-stack.md`:**
   - Document discovered dependencies
   - Note infrastructure from configs (Docker, CI, etc.)

3. **Create `context/product.md`:**
   - Infer product purpose from code
   - Document current feature set
   - Note any README content

4. **Create `context/workflow.md`:**
   - Document existing practices
   - Note any established patterns

## Maintenance Principles

### Keep Artifacts Synchronized

Changes in one artifact should reflect in related documents:
- New feature in product.md → Update tech-stack.md if new dependencies needed
- Completed track → Update product.md to reflect new capabilities
- Workflow change → Update all affected track plans

### Update tech-stack.md When Adding Dependencies

Before adding any new dependency:
1. Check if existing dependencies solve the need
2. Document the rationale for new dependencies
3. Add version constraints
4. Note any configuration requirements

### Verify Context Before Implementation

Before starting any work:
1. Read all context artifacts
2. Flag any outdated information
3. Propose updates before proceeding
4. Confirm context accuracy

## Validation Checklist

Before starting implementation, validate:

**Product Context:**
- [ ] product.md reflects current vision
- [ ] Target users are accurately described
- [ ] Feature list is up to date

**Technical Context:**
- [ ] tech-stack.md lists all current dependencies
- [ ] Version numbers are accurate
- [ ] Infrastructure targets are correct

**Workflow Context:**
- [ ] workflow.md describes current practices
- [ ] Quality gates are defined
- [ ] Commit conventions are documented

## Anti-Patterns

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Stale Context | Documents become outdated and misleading | Update context as part of each track's completion |
| Context Sprawl | Information scattered across multiple locations | Use defined artifact structure; resist new document types |
| Implicit Context | Relying on knowledge not captured in artifacts | If referenced repeatedly, add to appropriate artifact |
| Over-Specification | Context so detailed it's impossible to maintain | Keep focused on decisions affecting AI behavior and team alignment |

## Session Continuity

### Starting a New Session

1. Read context/product.md to orient yourself
2. Check context/tracks.md for active work
3. Read relevant track specs for current task
4. Verify context artifacts are current

### Ending a Session

1. Update track status with current progress
2. Note any blockers or decisions made
3. Commit in-progress work with clear status
4. Update tracks.md if status changed

## Benefits

**Team Alignment:**
- New team members onboard faster with explicit context
- Consistent terminology across the team
- Shared understanding of product goals

**AI Consistency:**
- AI assistants produce aligned outputs across sessions
- Reduced need to re-explain context
- Predictable behavior based on documented standards

**Institutional Memory:**
- Decisions and rationale are preserved
- Context survives team changes
- Historical context informs future decisions

## NEVER Do

1. **NEVER start implementation without reading context** — context precedes code
2. **NEVER add dependencies without updating tech-stack.md** — keep the source of truth current
3. **NEVER let context documents get stale** — update them as part of completing work
4. **NEVER scatter context across ad-hoc documents** — use the defined structure
5. **NEVER assume AI remembers previous sessions** — context must be in artifacts
6. **NEVER skip context for "quick" changes** — small changes compound into drift