/context-driven-development

name: context-driven-development
description: Use this skill when working with Conductor's context-driven development methodology, managing project context artifacts, or understanding the relationship between product.md, tech-stack.md, and workflow.md files.
version: 1.0.0

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, a