PaperclipOrg
Claude Agent Skill · by Wshobson

Context Driven Development

Creates a `conductor/` directory with structured project documentation including product.md, tech-stack.md, workflow.md, and tracks.md files. Useful when starti

Install
Terminal · npx
$npx skills add https://github.com/wshobson/agents --skill context-driven-development
Works with Paperclip

How Context Driven Development fits into a Paperclip company.

Context Driven Development drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md393 lines
Expand
---name: context-driven-developmentdescription: >-  Creates and maintains project context artifacts (product.md, tech-stack.md, workflow.md, tracks.md)  in a `conductor/` directory. Scaffolds new projects from scratch, extracts context from existing  codebases, validates artifact consistency before implementation, and synchronizes documents as the  project evolves. Use when setting up a project, creating or updating product docs, managing a tech  stack file, defining development workflows, tracking work units, onboarding to an existing codebase,  or running project scaffolding.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 implementation2. **Living documentation**: Context artifacts evolve with the project3. **Single source of truth**: One canonical location for each type of information4. **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 current2. **Specification Phase**: Define requirements and acceptance criteria for work units3. **Planning Phase**: Break specifications into phased, actionable tasks4. **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](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 need2. Document the rationale for new dependencies3. Add version constraints4. Note any configuration requirements ### Update product.md When Features Complete After completing a feature track: 1. Move feature from "planned" to "implemented" in product.md2. Update any affected success metrics3. Document any scope changes from original plan ### Verify Context Before Implementation Before starting any track: 1. Read all context artifacts2. Flag any outdated information3. Propose updates before proceeding4. Confirm context accuracy with stakeholders ## Greenfield vs Brownfield Handling ### Greenfield Projects (New) For new projects: 1. Run `/conductor:setup` to create all artifacts interactively2. Answer questions about product vision, tech preferences, and workflow3. Generate initial style guides for chosen languages4. 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 detection2. System analyzes existing code, configs, and documentation3. Pre-populate artifacts based on discovered patterns4. 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 track3. **Evolution**: Update as project grows4. **Synchronization**: Keep artifacts aligned5. **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 yourself2. Check tracks.md for active work3. Review relevant track's plan.md for current task4. Verify context artifacts are current ### Ending a Session 1. Update plan.md with current progress2. Note any blockers or decisions made3. Commit in-progress work with clear status4. Update tracks.md if status changed ### Handling Interruptions If interrupted mid-task: 1. Mark task as `[~]` with note about stopping point2. Commit work-in-progress to feature branch3. Document any uncommitted decisions in plan.md ## Best Practices 1. **Read context first**: Always read relevant artifacts before starting work2. **Small updates**: Make incremental context changes, not massive rewrites3. **Link decisions**: Reference context when making implementation choices4. **Version context**: Commit context changes alongside code changes5. **Review context**: Include context artifact reviews in code reviews6. **Validate regularly**: Run context validation checklist before major work7. **Communicate changes**: Notify team when context artifacts change significantly8. **Preserve history**: Use git to track context evolution over time9. **Question staleness**: If context feels wrong, investigate and update10. **Keep it actionable**: Every context item should inform a decision or behavior