Context-Driven Development

What Is Context-Driven Development?

Context-Driven Development is a methodology and supporting skill that formalizes the creation and maintenance of project context as structured, version-controlled artifacts. Within the Happycapy Skills platform, the "Context-Driven Development" skill enables teams to scaffold, extract, validate, and synchronize essential project context files-such as product.md, tech-stack.md, workflow.md, and tracks.md-within a dedicated conductor/ directory. This approach treats context as a first-class entity, ensuring that documentation evolves alongside code and that both human and AI contributors have a reliable, up-to-date reference for all project activities.

Rather than depending on scattered notes or informal prompts, context-driven development centralizes and structures the knowledge that defines a project. This includes the product vision, technical architecture, development processes, and tracked tasks or work units. By embedding these artifacts directly into the project repository, the skill empowers teams to maintain alignment, reduce onboarding friction, and enable consistent, context-aware AI development assistance.

Why Use Context-Driven Development?

Traditional project documentation is often fragmented, stale, or detached from the rapid evolution of code. This disconnect creates friction for developers, AI agents, and new team members who need accurate context to contribute effectively. Context-Driven Development addresses these challenges by:

• Establishing a Single Source of Truth: All context artifacts reside in the conductor/ directory, versioned alongside code, ensuring alignment between documentation and implementation.
• Improving AI Interactions: Well-maintained context artifacts allow AI tools and agents to provide more accurate suggestions, code generation, and task management based on the current state of the project.
• Reducing Onboarding Time: New contributors can quickly ramp up by reviewing structured, up-to-date documentation, including product goals, tech stack choices, workflows, and active tracks.
• Enhancing Consistency and Quality: By validating and synchronizing context artifacts before implementation, the skill helps teams avoid miscommunication and ensures that all contributors work from the same understanding.
• Supporting Both Greenfield and Brownfield Projects: Whether starting from scratch or extracting structure from an existing codebase, this skill adapts to the project's lifecycle.

How to Use Context-Driven Development

The Context-Driven Development skill provides a workflow for managing context artifacts throughout a project's life. These artifacts include:

• product.md: Captures the product vision, goals, and high-level requirements.
• tech-stack.md: Documents the chosen technologies, frameworks, and architecture rationale.
• workflow.md: Defines development processes, branching strategies, CI/CD pipelines, and review procedures.
• tracks.md: Tracks work units, features, bugs, or milestones relevant to the project's progress.

All files are located in the conductor/ directory at the project root.

Typical usage scenarios include:

1. Scaffolding a New

Project

When initializing a new project, run the Conductor skill to generate the required context artifacts:

conductor scaffold

This command creates the conductor/ directory with templated product.md, tech-stack.md, workflow.md, and tracks.md files. You can then populate each file with project-specific information.

Example: conductor/product.md

## Product Vision

Our goal is to build an intuitive task management platform for distributed teams, emphasizing real-time collaboration and robust integrations.

## Key Features
- Real-time task updates
- Third-party calendar sync
- Customizable workflows

2. Extracting Context from an Existing

Codebase

For brownfield projects, use the skill to automatically extract relevant information and scaffold context artifacts:

conductor extract

This analyzes the codebase and creates initial context files based on detected technologies, patterns, and project structure. Manual review and refinement are recommended to ensure accuracy.

3. Validating Context

Consistency

Before implementing new features or running AI-powered development sessions, validate the consistency of context artifacts:

conductor validate

This checks for discrepancies, such as missing tech stack entries, outdated workflows, or incomplete product descriptions, prompting updates as needed.

4. Synchronizing Context as the Project

Evolves

Whenever significant code or process changes occur, update the relevant context files and re-run validation. This ensures ongoing alignment between documentation and reality.

When to Use This Skill

• At Project Kickoff: Scaffold and define context artifacts before starting implementation.
• During Onboarding: Direct new team members to review the conductor/ directory for a comprehensive project overview.
• Before Major Changes: Validate and update context before introducing new technologies, workflows, or features.
• During AI-Assisted Sessions: Ensure context files are current so AI agents can operate with the latest project information.
• When Extracting Structure from Legacy Projects: Use the skill to bootstrap documentation for brownfield codebases.

Important Notes

• Context precedes code: Always define or update context artifacts before making significant changes to the codebase.
• Artifact consistency is critical: Regularly validate and synchronize context files to prevent drift between documentation and implementation.
• Treat context as source code: Store all context artifacts under version control in the conductor/ directory.
• AI interaction relies on context: Well-maintained context artifacts are essential for effective AI-driven development workflows.
• Customization is encouraged: Tailor the templates and structure of context files to match your team's needs, but maintain consistency and completeness.

By treating context as a managed artifact, the Context-Driven Development skill helps ensure that every contributor-human or AI-has the information needed to deliver consistent, high-quality results.