ranbot-ai/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.

Do not use this skill when

• The task is unrelated to context-driven development
• You need a different domain or tool outside this scope

Instructions

• Clarify goals, constraints, and required inputs.
• Apply relevant best practices and validate outcomes.
• Provide actionable steps and verification.
• If detailed examples are required, open resources/implementation-playbook.md.

Use this skill when

• 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 & 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

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