Context Driven Development

Context-Driven Development

Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation.

When to Use This Skill

• Setting up new projects with Conductor
• Understanding the relationship between context artifacts
• Maintaining consistency across AI-assisted development sessions
• Onboarding team members to an existing Conductor project
• Deciding when to update context documents
• Managing greenfield vs brownfield project contexts

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 -> Evaluate-Loop 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. Evaluate-Loop Phase: Execute via the loop agents coordinated by conductor-orchestrator:
   • Step 1: loop-planner -- creates execution plan from spec
   • Step 2: loop-plan-evaluator -- verifies plan before coding
   • Step 3: loop-executor -- implements tasks, updates plan.md
   • Step 4: loop-execution-evaluator -- verifies implementation
   • Step 5: loop-fixer -- fixes evaluation failures, loops back

See conductor/workflow.md for the full Evaluate-Loop process.

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

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_file 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 /orchestrator-supaconductor: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 /orchestrator-supaconductor: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