vamfi/vamfi-plugins/implementation-plan

Implementation Plan

Produce a detailed technical implementation plan that specifies the branching strategy, coding patterns, guardrails, and step-by-step checklist before any code is written. Prevent rework by planning before implementing.

Overview

An implementation plan bridges the gap between a shaped story and working code. It ensures the developer (human or agent) understands the what, why, and how before starting, reducing back-and-forth and rework.

Implementation Planning Process

Step 1: Scope and Impact Analysis

Read the relevant codebase (Grep and Glob) to:

• Identify which files and modules will be touched
• Find existing patterns to follow (or deliberately break with)
• Identify integration points and their current contracts
• Flag any existing technical debt that this change might interact with

Produce an impact map:

Step 2: Branching Strategy

Select and document the branching approach:

Trunk-based development (preferred for high-frequency delivery):

• Short-lived feature branches (< 2 days), merged to main via PR
• Feature flags for work-in-progress that needs to be merged but not released

Gitflow (for release-cadence-based teams):

• Feature branches from develop
• Release branches from develop to main
• Hotfix branches from main

Feature flags (when applicable):

• Flag name convention: [team]-[feature]-[date]
• Flag lifecycle: define the removal date at creation
• Default: off in production, on in staging

Step 3: Coding Patterns and Guardrails

Define the patterns to follow for this implementation:

• Architectural pattern: which layer handles what (controller → service → repository)
• Error handling: how errors propagate and are logged
• Data validation: where validation happens (boundary, not deep in business logic)
• Testing approach: test first (TDD) or test alongside
• Naming conventions: follow existing conventions discovered in Step 1

Anti-patterns to avoid:

• [ ] Do not add business logic to controllers/routes
• [ ] Do not bypass the data access layer for direct DB queries
• [ ] Do not introduce new dependencies without documenting the ADR
• [ ] Do not merge without tests for the new behaviour

Step 4: Step-by-Step Implementation Checklist

Produce a numbered checklist that an engineer (or agent) can follow:

## Implementation Checklist: [Feature Name]
 
### Setup
-[ ] 1. Create branch `feature/[story-id]-[short-description]` from `main`
-[ ] 2. Confirm local environment matches staging config
 
### Implementation
-[ ] 3. [First implementation step — specific file and change]
-[ ] 4. [Second implementation step]
-[ ] 5. Write unit tests for [specific component]
-[ ] 6. Write integration test for [specific flow]
 
### Validation
-[ ] 7. Run test suite: all tests pass
-[ ] 8. Run linter: no new errors
-[ ] 9. Manual smoke test: [specific user flow to test]
-[ ] 10. Check performance: [specific metric to validate]
 
### Merge
-[ ] 11. Create PR with reference to STORY-[N]
-[ ] 12. Request review from [role]
-[ ] 13. Address review comments
-[ ] 14. Squash and merge on approval

Additional Resources

• `references/branching-strategies.md` — Detailed branching pattern guidance
• `references/coding-guardrails.md` — Language and framework-specific guardrails