Feature Breakdown

Feature Breakdown

Break down features into concrete, implementable tasks within the @dotcontext/cli architecture.

When to Use

• Starting the Planning (P) phase of a PREVC workflow
• Scoping a new CLI command, MCP tool, or service
• Creating a plan document in .context/plans/
• Estimating complexity to choose the right workflow scale (QUICK/SMALL/MEDIUM/LARGE)

Instructions

1. Classify the Feature Scope

Determine which layers of the codebase are involved:

2. Determine the Workflow Scale

Use these criteria to set the scale when calling workflow-init:

3. Identify the Task Breakdown Pattern

Most features in this project follow one of these patterns:

Pattern A: New MCP Gateway Action

1. Define the action in the Zod schema (mcpServer.ts)
2. Add handler logic in the gateway file (src/services/mcp/gateway/<tool>.ts)
3. Create or extend the backing service (src/services/<domain>/)
4. Update type exports in gatewayTools.ts and gateway/index.ts
5. Add tests for the handler
6. Update MCP tool description string

Pattern B: New CLI Command

1. Define the command with Commander in src/index.ts
2. Create the service in src/services/<name>/
3. Add i18n keys to src/utils/i18n.ts (both en and pt-BR)
4. Wire CLI options to service calls
5. Add CLI output via CLIInterface from src/utils/cliUI.ts
6. Write tests

Pattern C: New Generator/Scaffold Type

1. Create generator class in src/generators/<type>/
2. Define templates in src/generators/<type>/templates/
3. Add frontmatter type to src/types/scaffoldFrontmatter.ts
4. Integrate with InitService for scaffold creation
5. Integrate with FillService for AI content generation
6. Add to MCP context gateway if applicable
7. Write generator tests

Pattern D: New Workflow Feature

1. Update types in src/workflow/types.ts
2. Modify phase/gate logic in src/workflow/
3. Update WorkflowService in src/services/workflow/
4. Update MCP workflow tools if user-facing
5. Write tests for phase transitions

4. Create the Plan Document

Use the MCP tool or create manually:

# Via MCP
context({ action: 'scaffoldPlan', planName: 'my-feature', title: 'My Feature', summary: 'What it does' })

# Manual creation in .context/plans/my-feature.md

Structure each phase with concrete steps:

## Phases

### P - Planning
- [ ] Define requirements and acceptance criteria
- [ ] Identify affected services and files
- [ ] Choose workflow scale

### R - Review (for MEDIUM/LARGE)
- [ ] Review architecture impact
- [ ] Document design decisions as ADRs
- [ ] Get plan approval

### E - Execution
- [ ] Implement service logic in src/services/<domain>/
- [ ] Add MCP gateway handler (if applicable)
- [ ] Update CLI integration (if applicable)
- [ ] Add i18n keys for new user-facing strings
- [ ] Update type exports

### V - Validation
- [ ] Write unit tests with jest.mock() for externals
- [ ] Run full test suite: npm test
- [ ] Manual CLI verification: npx tsx src/index.ts <command>
- [ ] TypeScript compilation check: npm run build

### C - Confirmation (for LARGE)
- [ ] Update CHANGELOG.md
- [ ] Update relevant .context/ documentation
- [ ] Update README if public API changed

5. Identify Dependencies and Risks

Common dependencies to flag:

• AI provider changes: Require testing with actual API keys (not just mocks)
• tree-sitter changes: Optional dependency -- test with and without it installed
• MCP protocol changes: Must maintain backward compatibility with existing clients
• Frontmatter format changes: Must handle both v1 and v2 formats
• i18n additions: Both locales must be updated simultaneously

6. Link the Plan to the Workflow

After creating the plan, link it to the active workflow:

plan({ action: 'link', planSlug: 'my-feature' })

This enables phase tracking and the commitPhase action for git integration.

Example: Breaking Down "Add Caching to Semantic Analysis"

Scale: MEDIUM (multiple files, design decision on cache strategy)

Tasks:

1. P: Define cache invalidation strategy (file mtime vs. content hash)
2. P: Decide cache storage location (.context/.cache/ vs. temp dir)
3. R: Review impact on CodebaseAnalyzer and SemanticContextBuilder
4. E: Add cache layer to src/services/semantic/codebaseAnalyzer.ts
5. E: Add cache config to AnalyzerOptions type
6. E: Wire cache option through MCP context({ action: 'buildSemantic' }) params
7. V: Test cache hit/miss with codebaseAnalyzer.test.ts
8. V: Test that cacheEnabled: false bypasses cache
9. V: Manual test with large repo to verify performance improvement

Files affected: src/services/semantic/codebaseAnalyzer.ts, src/services/semantic/types.ts, src/services/mcp/gateway/context.ts, src/services/mcp/mcpServer.ts