Context Driven Development

1---
2name: context-driven-development
3description: Use this skill when working with Conductor's context-driven
4  development methodology, managing project context artifacts, or understanding
5  the relationship between product.md, tech-stack.md, and workflow.md files.
6metadata:
7  version: 1.0.0
8---
9 
10# Context-Driven Development
11 
12Guide for implementing and maintaining context as a managed artifact alongside code, enabling consistent AI interactions and team alignment through structured project documentation.
13 
14## Do not use this skill when
15 
16- The task is unrelated to context-driven development
17- You need a different domain or tool outside this scope
18 
19## Instructions
20 
21- Clarify goals, constraints, and required inputs.
22- Apply relevant best practices and validate outcomes.
23- Provide actionable steps and verification.
24- If detailed examples are required, open `resources/implementation-playbook.md`.
25 
26## Use this skill when
27 
28- Setting up new projects with Conductor
29- Understanding the relationship between context artifacts
30- Maintaining consistency across AI-assisted development sessions
31- Onboarding team members to an existing Conductor project
32- Deciding when to update context documents
33- Managing greenfield vs brownfield project contexts
34 
35## Core Philosophy
36 
37Context-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.
38 
39Key principles:
40 
411. **Context precedes code**: Define what you're building and how before implementation
422. **Living documentation**: Context artifacts evolve with the project
433. **Single source of truth**: One canonical location for each type of information
444. **AI alignment**: Consistent context produces consistent AI behavior
45 
46## The Workflow
47 
48Follow the **Context → Spec & Plan → Implement** workflow:
49 
501. **Context Phase**: Establish or verify project context artifacts exist and are current
512. **Specification Phase**: Define requirements and acceptance criteria for work units
523. **Planning Phase**: Break specifications into phased, actionable tasks
534. **Implementation Phase**: Execute tasks following established workflow patterns
54 
55## Artifact Relationships
56 
57### product.md - Defines WHAT and WHY
58 
59Purpose: Captures product vision, goals, target users, and business context.
60 
61Contents:
62 
63- Product name and one-line description
64- Problem statement and solution approach
65- Target user personas
66- Core features and capabilities
67- Success metrics and KPIs
68- Product roadmap (high-level)
69 
70Update when:
71 
72- Product vision or goals change
73- New major features are planned
74- Target audience shifts
75- Business priorities evolve
76 
77### product-guidelines.md - Defines HOW to Communicate
78 
79Purpose: Establishes brand voice, messaging standards, and communication patterns.
80 
81Contents:
82 
83- Brand voice and tone guidelines
84- Terminology and glossary
85- Error message conventions
86- User-facing copy standards
87- Documentation style
88 
89Update when:
90 
91- Brand guidelines change
92- New terminology is introduced
93- Communication patterns need refinement
94 
95### tech-stack.md - Defines WITH WHAT
96 
97Purpose: Documents technology choices, dependencies, and architectural decisions.
98 
99Contents:
100 
101- Primary languages and frameworks
102- Key dependencies with versions
103- Infrastructure and deployment targets
104- Development tools and environment
105- Testing frameworks
106- Code quality tools
107 
108Update when:
109 
110- Adding new dependencies
111- Upgrading major versions
112- Changing infrastructure
113- Adopting new tools or patterns
114 
115### workflow.md - Defines HOW to Work
116 
117Purpose: Establishes development practices, quality gates, and team workflows.
118 
119Contents:
120 
121- Development methodology (TDD, etc.)
122- Git workflow and commit conventions
123- Code review requirements
124- Testing requirements and coverage targets
125- Quality assurance gates
126- Deployment procedures
127 
128Update when:
129 
130- Team practices evolve
131- Quality standards change
132- New workflow patterns are adopted
133 
134### tracks.md - Tracks WHAT'S HAPPENING
135 
136Purpose: Registry of all work units with status and metadata.
137 
138Contents:
139 
140- Active tracks with current status
141- Completed tracks with completion dates
142- Track metadata (type, priority, assignee)
143- Links to individual track directories
144 
145Update when:
146 
147- New tracks are created
148- Track status changes
149- Tracks are completed or archived
150 
151## Context Maintenance Principles
152 
153### Keep Artifacts Synchronized
154 
155Ensure changes in one artifact reflect in related documents:
156 
157- New feature in product.md → Update tech-stack.md if new dependencies needed
158- Completed track → Update product.md to reflect new capabilities
159- Workflow change → Update all affected track plans
160 
161### Update tech-stack.md When Adding Dependencies
162 
163Before adding any new dependency:
164 
1651. Check if existing dependencies solve the need
1662. Document the rationale for new dependencies
1673. Add version constraints
1684. Note any configuration requirements
169 
170### Update product.md When Features Complete
171 
172After completing a feature track:
173 
1741. Move feature from "planned" to "implemented" in product.md
1752. Update any affected success metrics
1763. Document any scope changes from original plan
177 
178### Verify Context Before Implementation
179 
180Before starting any track:
181 
1821. Read all context artifacts
1832. Flag any outdated information
1843. Propose updates before proceeding
1854. Confirm context accuracy with stakeholders
186 
187## Greenfield vs Brownfield Handling
188 
189### Greenfield Projects (New)
190 
191For new projects:
192 
1931. Run `/conductor:setup` to create all artifacts interactively
1942. Answer questions about product vision, tech preferences, and workflow
1953. Generate initial style guides for chosen languages
1964. Create empty tracks registry
197 
198Characteristics:
199 
200- Full control over context structure
201- Define standards before code exists
202- Establish patterns early
203 
204### Brownfield Projects (Existing)
205 
206For existing codebases:
207 
2081. Run `/conductor:setup` with existing codebase detection
2092. System analyzes existing code, configs, and documentation
2103. Pre-populate artifacts based on discovered patterns
2114. Review and refine generated context
212 
213Characteristics:
214 
215- Extract implicit context from existing code
216- Reconcile existing patterns with desired patterns
217- Document technical debt and modernization plans
218- Preserve working patterns while establishing standards
219 
220## Benefits
221 
222### Team Alignment
223 
224- New team members onboard faster with explicit context
225- Consistent terminology and conventions across the team
226- Shared understanding of product goals and technical decisions
227 
228### AI Consistency
229 
230- AI assistants produce aligned outputs across sessions
231- Reduced need to re-explain context in each interaction
232- Predictable behavior based on documented standards
233 
234### Institutional Memory
235 
236- Decisions and rationale are preserved
237- Context survives team changes
238- Historical context informs future decisions
239 
240### Quality Assurance
241 
242- Standards are explicit and verifiable
243- Deviations from context are detectable
244- Quality gates are documented and enforceable
245 
246## Directory Structure
247 
248```
249conductor/
250├── index.md              # Navigation hub linking all artifacts
251├── product.md            # Product vision and goals
252├── product-guidelines.md # Communication standards
253├── tech-stack.md         # Technology preferences
254├── workflow.md           # Development practices
255├── tracks.md             # Work unit registry
256├── setup_state.json      # Resumable setup state
257├── code_styleguides/     # Language-specific conventions
258│   ├── python.md
259│   ├── typescript.md
260│   └── ...
261└── tracks/
262    └── <track-id>/
263        ├── spec.md
264        ├── plan.md
265        ├── metadata.json
266        └── index.md
267```
268 
269## Context Lifecycle
270 
2711. **Creation**: Initial setup via `/conductor:setup`
2722. **Validation**: Verify before each track
2733. **Evolution**: Update as project grows
2744. **Synchronization**: Keep artifacts aligned
2755. **Archival**: Document historical decisions
276 
277## Context Validation Checklist
278 
279Before starting implementation on any track, validate context:
280 
281### Product Context
282 
283- [ ] product.md reflects current product vision
284- [ ] Target users are accurately described
285- [ ] Feature list is up to date
286- [ ] Success metrics are defined
287 
288### Technical Context
289 
290- [ ] tech-stack.md lists all current dependencies
291- [ ] Version numbers are accurate
292- [ ] Infrastructure targets are correct
293- [ ] Development tools are documented
294 
295### Workflow Context
296 
297- [ ] workflow.md describes current practices
298- [ ] Quality gates are defined
299- [ ] Coverage targets are specified
300- [ ] Commit conventions are documented
301 
302### Track Context
303 
304- [ ] tracks.md shows all active work
305- [ ] No stale or abandoned tracks
306- [ ] Dependencies between tracks are noted
307 
308## Common Anti-Patterns
309 
310Avoid these context management mistakes:
311 
312### Stale Context
313 
314Problem: Context documents become outdated and misleading.
315Solution: Update context as part of each track's completion process.
316 
317### Context Sprawl
318 
319Problem: Information scattered across multiple locations.
320Solution: Use the defined artifact structure; resist creating new document types.
321 
322### Implicit Context
323 
324Problem: Relying on knowledge not captured in artifacts.
325Solution: If you reference something repeatedly, add it to the appropriate artifact.
326 
327### Context Hoarding
328 
329Problem: One person maintains context without team input.
330Solution: Review context artifacts in pull requests; make updates collaborative.
331 
332### Over-Specification
333 
334Problem: Context becomes so detailed it's impossible to maintain.
335Solution: Keep artifacts focused on decisions that affect AI behavior and team alignment.
336 
337## Integration with Development Tools
338 
339### IDE Integration
340 
341Configure your IDE to display context files prominently:
342 
343- Pin conductor/product.md for quick reference
344- Add tech-stack.md to project notes
345- Create snippets for common patterns from style guides
346 
347### Git Hooks
348 
349Consider pre-commit hooks that:
350 
351- Warn when dependencies change without tech-stack.md update
352- Remind to update product.md when feature branches merge
353- Validate context artifact syntax
354 
355### CI/CD Integration
356 
357Include context validation in pipelines:
358 
359- Check tech-stack.md matches actual dependencies
360- Verify links in context documents resolve
361- Ensure tracks.md status matches git branch state
362 
363## Session Continuity
364 
365Conductor supports multi-session development through context persistence:
366 
367### Starting a New Session
368 
3691. Read index.md to orient yourself
3702. Check tracks.md for active work
3713. Review relevant track's plan.md for current task
3724. Verify context artifacts are current
373 
374### Ending a Session
375 
3761. Update plan.md with current progress
3772. Note any blockers or decisions made
3783. Commit in-progress work with clear status
3794. Update tracks.md if status changed
380 
381### Handling Interruptions
382 
383If interrupted mid-task:
384 
3851. Mark task as `[~]` with note about stopping point
3862. Commit work-in-progress to feature branch
3873. Document any uncommitted decisions in plan.md
388 
389## Best Practices
390 
3911. **Read context first**: Always read relevant artifacts before starting work
3922. **Small updates**: Make incremental context changes, not massive rewrites
3933. **Link decisions**: Reference context when making implementation choices
3944. **Version context**: Commit context changes alongside code changes
3955. **Review context**: Include context artifact reviews in code reviews
3966. **Validate regularly**: Run context validation checklist before major work
3977. **Communicate changes**: Notify team when context artifacts change significantly
3988. **Preserve history**: Use git to track context evolution over time
3999. **Question staleness**: If context feels wrong, investigate and update
40010. **Keep it actionable**: Every context item should inform a decision or behavior
401