Context Driven Development

context-driven-development — detailed patterns and worked examples

Core Philosophy

Context-Driven Development treats 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.

Key principles:

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

Follow the Context → Spec & Plan → Implement workflow:

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

Artifact Relationships

product.md - Defines 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

• Business priorities evolve

product-guidelines.md - Defines HOW to Communicate

Purpose: Establishes brand voice, messaging standards, and communication patterns.

Contents:

• Brand voice and tone guidelines

• Terminology and glossary

• Error message conventions

• User-facing copy standards

• Documentation style

Update when:

• Brand guidelines change

• New terminology is introduced

• Communication patterns need refinement

tech-stack.md - Defines 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 - Defines HOW to Work

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

Contents:

• Development methodology (TDD, 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 - Tracks 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 directories

Update when:

• New tracks are created

• Track status changes

• Tracks are completed or archived

See references/artifact-templates.md for copy-paste starter templates.

Context Maintenance Principles

Keep Artifacts Synchronized

Ensure changes in one artifact 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

Update product.md When Features Complete

After completing a feature track:

1. Move feature from "planned" to "implemented" in product.md

2. Update any affected success metrics

3. Document any scope changes from original plan

Verify Context Before Implementation

Before starting any track:

1. Read all context artifacts

2. Flag any outdated information

3. Propose updates before proceeding

4. Confirm context accuracy with stakeholders

Greenfield vs Brownfield Handling

Greenfield Projects (New)

For new projects:

1. Run /conductor:setup to create all artifacts interactively

2. Answer questions about product vision, tech preferences, and workflow

3. Generate initial style guides for chosen languages

4. Create empty tracks registry

Characteristics:

• Full control over context structure

• Define standards before code exists

• Establish patterns early

Brownfield Projects (Existing)

For existing codebases:

1. Run /conductor:setup with existing codebase detection

2. System analyzes existing code, configs, and documentation

3. Pre-populate artifacts based on discovered patterns

4. Review and refine generated context

Characteristics:

• Extract implicit context from existing code

• Reconcile existing patterns with desired patterns

• Document technical debt and modernization plans

• Preserve working patterns while establishing standards

Benefits

Team Alignment

• New team members onboard faster with explicit context

• Consistent terminology and conventions across the team

• Shared understanding of product goals and technical decisions

AI Consistency

• AI assistants produce aligned outputs across sessions

• Reduced need to re-explain context in each interaction

• Predictable behavior based on documented standards

Institutional Memory

• Decisions and rationale are preserved

• Context survives team changes

• Historical context informs future decisions

Quality Assurance

• Standards are explicit and verifiable

• Deviations from context are detectable

• Quality gates are documented and enforceable

Directory Structure

conductor/
├── index.md              # Navigation hub linking all artifacts
├── product.md            # Product vision and goals
├── product-guidelines.md # Communication standards
├── tech-stack.md         # Technology preferences
├── workflow.md           # Development practices
├── tracks.md             # Work unit registry
├── setup_state.json      # Resumable setup state
├── code_styleguides/     # Language-specific conventions
│   ├── python.md
│   ├── typescript.md
│   └── ...
└── tracks/
    └── <track-id>/
        ├── spec.md
        ├── plan.md
        ├── metadata.json
        └── index.md

Context Lifecycle

1. Creation: Initial setup via /conductor:setup

2. Validation: Verify before each track

3. Evolution: Update as project grows

4. Synchronization: Keep artifacts aligned

5. Archival: Document historical decisions

Context Validation Checklist

Before starting implementation on any track, validate context:

Product Context

• [ ] product.md reflects current product vision

• [ ] Target users are accurately described

• [ ] Feature list is up to date

• [ ] Success metrics are defined

Technical Context

• [ ] tech-stack.md lists all current dependencies

• [ ] Version numbers are accurate

• [ ] Infrastructure targets are correct

• [ ] Development tools are documented

Workflow Context

• [ ] workflow.md describes current practices

• [ ] Quality gates are defined

• [ ] Coverage targets are specified

• [ ] Commit conventions are documented

Track Context

• [ ] tracks.md shows all active work

• [ ] No stale or abandoned tracks

• [ ] Dependencies between tracks are noted

Common Anti-Patterns

Avoid these context management mistakes:

Stale Context

Problem: Context documents become outdated and misleading. Solution: Update context as part of each track's completion process.

Context Sprawl

Problem: Information scattered across multiple locations. Solution: Use the defined artifact structure; resist creating new document types.

Implicit Context

Problem: Relying on knowledge not captured in artifacts. Solution: If you reference something repeatedly, add it to the appropriate artifact.

Context Hoarding

Problem: One person maintains context without team input. Solution: Review context artifacts in pull requests; make updates collaborative.

Over-Specification

Problem: Context becomes so detailed it's impossible to maintain. Solution: Keep artifacts focused on decisions that affect AI behavior and team alignment.

Integration with Development Tools

IDE Integration

Configure your IDE to display context files prominently:

• Pin conductor/product.md for quick reference

• Add tech-stack.md to project notes

• Create snippets for common patterns from style guides

Git Hooks

Consider pre-commit hooks that:

• Warn when dependencies change without tech-stack.md update

• Remind to update product.md when feature branches merge

• Validate context artifact syntax

CI/CD Integration

Include context validation in pipelines:

• Check tech-stack.md matches actual dependencies

• Verify links in context documents resolve

• Ensure tracks.md status matches git branch state

Session Continuity

Conductor supports multi-session development through context persistence:

Starting a New Session

1. Read index.md to orient yourself

2. Check tracks.md for active work

3. Review relevant track's plan.md for current task

4. Verify context artifacts are current

Ending a Session

1. Update plan.md 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

Handling Interruptions

If interrupted mid-task:

1. Mark task as [~] with note about stopping point

2. Commit work-in-progress to feature branch

3. Document any uncommitted decisions in plan.md