# implement > Implement code changes based on approved atomic specs. Executes one atomic spec at a time, gathers evidence, and escalates if implementation reveals spec gaps. Use after spec group approval. - Author: Matthew Lin - Repository: matthew-plusprogramming/monorepo - Version: 20260121205838 - Stars: 0 - Forks: 0 - Last Updated: 2026-02-07 - Source: https://github.com/matthew-plusprogramming/monorepo - Web: https://mule.run/skillshub/@@matthew-plusprogramming/monorepo~implement:20260121205838 --- --- name: implement description: Implement code changes based on approved atomic specs. Executes one atomic spec at a time, gathers evidence, and escalates if implementation reveals spec gaps. Use after spec group approval. allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Task user-invocable: true --- # Implementation Skill ## Purpose Execute implementation from approved atomic specs with full traceability to requirements. **Key Input**: Atomic specs from `.claude/specs/groups//atomic/` ## Usage ``` /implement # Implement all atomic specs in order /implement # Implement specific atomic spec /implement --parallel # Dispatch parallel implementers per atomic spec ``` ## Prerequisites Before using this skill, verify: 1. **Spec group exists** at `.claude/specs/groups//` 2. **review_state** is `APPROVED` in manifest.json 3. **Atomic specs exist** in `atomic/` directory 4. **Enforcement passed** (`atomic_specs.enforcement_status: "passing"`) 5. **Open questions** are resolved or explicitly deferred If prerequisites not met → STOP and resolve before implementing. ## Implementation Process ### Step 0: Load Session Context Check for existing session state to enable resuming mid-implementation: ```bash # Check session checkpoint cat .claude/context/session.json | jq '.phase_checkpoint' ``` If `atomic_specs_pending` has values, use those as the implementation queue instead of starting fresh. This enables cross-session recovery if implementation was interrupted. ```json { "phase_checkpoint": { "phase": "implementing", "atomic_specs_pending": ["as-003", "as-004"], "atomic_specs_complete": ["as-001", "as-002"], "last_completed": "as-002" } } ``` If no checkpoint exists or `phase` is not `implementing`, proceed with full atomic spec list from Step 2. ### Step 1: Load and Verify Spec Group ``` Read: .claude/specs/groups//manifest.json Read: .claude/specs/groups//requirements.md Read: .claude/specs/groups//spec.md List: .claude/specs/groups//atomic/*.md ``` Verify in manifest.json: - `review_state` is `APPROVED` - `atomic_specs.enforcement_status` is `passing` - No blocking open questions ### Step 2: List Atomic Specs ``` .claude/specs/groups//atomic/ ├── as-001-logout-button-ui.md ├── as-002-token-clearing.md ├── as-003-post-logout-redirect.md └── as-004-error-handling.md ``` Each atomic spec is independently implementable. Execute in order (as-001, as-002, etc.). ### Step 3: Understand the Codebase Before making changes, study existing patterns: - File structure and naming conventions - Error handling patterns - Testing approaches ### Step 4: Execute Atomic Specs in Order For each atomic spec: #### 4a. Mark Atomic Spec as In Progress Update atomic spec frontmatter: ```yaml status: implementing ``` Update manifest.json: ```json { "work_state": "IMPLEMENTING" } ``` Update session checkpoint to track implementation phase: ```bash # Update session checkpoint node .claude/scripts/session-checkpoint.mjs transition-phase implementing ``` #### 4b. Read Atomic Spec From the atomic spec file, extract: - Description (single behavior to implement) - Acceptance criteria - Test strategy - Deployment notes #### 4c. Implement the Atomic Spec Follow spec requirements exactly: - Use existing patterns from codebase - Maintain naming conventions - Include error handling as specified - Add comments linking to AC numbers #### 4d. Run Relevant Tests ```bash npm test -- ``` #### 4e. Fill Implementation Evidence Update the atomic spec's Implementation Evidence section: ```markdown ## Implementation Evidence | File | Line | Description | | ---------------------------- | ---- | ---------------------------- | | src/services/auth-service.ts | 67 | logout() method clears token | | src/components/UserMenu.tsx | 42 | Logout button component | ``` #### 4f. Mark Atomic Spec Complete Update atomic spec frontmatter: ```yaml status: implemented ``` Add to atomic spec Decision Log: ```markdown ## Decision Log - `2026-01-14T10:30:00Z`: Created from spec.md decomposition - `2026-01-14T14:30:00Z`: Implementation complete - auth-service.ts:67 ``` #### 4g. Update Session Checkpoint After each atomic spec completion, update session state for cross-session recovery: ```bash # Mark atomic spec complete in session node .claude/scripts/session-checkpoint.mjs complete-atomic-spec ``` This ensures that if the session ends unexpectedly, the next session can resume from the correct atomic spec. ### Step 5: Handle Spec Deviations If you discover during implementation: #### Scenario A: Missing Requirement Spec doesn't cover a necessary case. **Action**: 1. STOP implementation 2. Document in spec's Open Questions: ```markdown ## Open Questions - Q3: How should logout behave if user has unsaved changes? (Status: blocking) - Discovered during implementation - Need user decision before proceeding ``` 3. Ask user for guidance 4. Update spec with decision 5. Resume implementation #### Scenario B: Invalid Assumption Spec assumes something that's not true in the codebase. **Action**: 1. STOP implementation 2. Document in spec's Decision & Work Log: ```markdown - 2026-01-02: **Issue** - Spec assumes AuthService.logout() exists, but it doesn't - **Proposed amendment**: Add AuthService.logout() method to task list - **Status**: Awaiting approval ``` 3. Propose spec amendment 4. Get user approval 5. Update spec 6. Resume implementation #### Scenario C: Better Approach Discovered Found a more efficient or clearer way to achieve the requirement. **Action**: 1. Evaluate: Does this change the **behavior** or just the **implementation**? 2. If behavior unchanged → Proceed (implementation detail) 3. If behavior changes → Propose spec amendment with rationale 4. Get approval before deviating **Never silently deviate from the spec.** ### Step 6: Validate Implementation After all atomic specs complete: ```bash # Run full test suite npm test # Check for lint errors npm run lint # Build if applicable npm run build ``` Ensure: - All tests passing - No lint errors - Build succeeds - No console errors introduced ### Step 7: Update Manifest Update manifest.json with implementation complete: ```json { "work_state": "VERIFYING", "convergence": { "all_acs_implemented": true }, "decision_log": [ // ... existing entries ... { "timestamp": "", "actor": "agent", "action": "implementation_complete", "details": "All 4 atomic specs implemented, tests passing" } ], "session_ref": { "session_id": "", "last_checkpoint": "", "last_atomic_spec": "", "checkpoint_phase": "implementing", "checkpoint_state": "clean" } } ``` Transition to verifying phase for cross-session tracking: ```bash # Transition to verifying phase node .claude/scripts/session-checkpoint.mjs transition-phase verifying ``` ### Step 8: Report Completion ```markdown ## Implementation Complete ✅ **Spec Group**: **Atomic Specs**: 4/4 complete **Evidence**: - as-001: src/components/UserMenu.tsx:42 - as-002: src/services/auth-service.ts:67 - as-003: src/router/auth-router.ts:23 - as-004: src/services/auth-service.ts:78 **Tests**: All passing **Build**: Successful **Next Steps**: 1. Run `/test ` to ensure test coverage (if not done in parallel) 2. Run `/unify ` to validate convergence ``` ## Parallel Execution with Test Writer For larger tasks, implementation and test writing can run in parallel. ### When to Parallelize - Multiple independent tasks in task list - Clear acceptance criteria for each task - Low coupling between tasks ### How to Parallelize Use Task tool to dispatch subagents: ```javascript // Dispatch implementer subagent Task({ description: "Implement logout functionality", prompt: `Implement tasks 1-3 from TaskSpec at .claude/specs/active/logout-button.md Focus on: - Adding logout button component - Implementing AuthService.logout() method - Adding error handling Do NOT implement tests - test-writer will handle that. Follow spec requirements exactly. Escalate if spec gaps discovered.`, subagent_type: "implementer", }); // Dispatch test-writer subagent in parallel Task({ description: "Write tests for logout functionality", prompt: `Write tests for acceptance criteria AC1.1-AC2.3 from TaskSpec at .claude/specs/active/logout-button.md Map each AC to specific test cases. Follow AAA pattern. Tests will initially fail until implementation complete.`, subagent_type: "test-writer", }); ``` Main agent retains integration responsibility: - Collect outputs from both subagents - Ensure tests pass with implementation - Run unifier to validate alignment ## Spec Conformance Rules ### DO: - Follow spec requirements exactly - Use existing codebase patterns - Ask user when spec is unclear - Update spec when discovering gaps - Log evidence of completion - Run tests after each task ### DON'T: - Add features not in spec - Deviate from specified behavior - Assume unstated requirements - Skip error handling specified in spec - Make breaking changes not mentioned in spec - Silently fix spec errors - propose amendments instead ## Integration with Other Skills After implementation: - Use `/unify` to validate spec-impl-test alignment **After unify passes, the review chain is**: 1. `/code-review` - Code quality review (always) 2. `/security` - Security review (always) 3. `/browser-test` - UI validation (if UI changes) 4. `/docs` - Documentation generation (if public API) 5. Commit ## Error Handling ### Build Failures ```bash npm run build # Error: ... ``` **Action**: 1. Read error message carefully 2. Check if spec anticipated this (Security section, Edge Cases) 3. If spec covers it → Implement as specified 4. If spec doesn't cover it → Add to Open Questions, get guidance ### Test Failures ```bash npm test # FAIL: expected X, got Y ``` **Action**: 1. Determine if test or implementation is wrong 2. If test is wrong → Fix test to match spec 3. If implementation is wrong → Fix implementation to match spec 4. If spec is wrong → Propose spec amendment ### Merge Conflicts If working in parallel with other workstreams: ```bash git pull origin main # CONFLICT: ... ``` **Action**: 1. Check MasterSpec contract registry 2. Verify your implementation matches contract interface 3. Resolve conflict favoring contract definition 4. If contract is ambiguous → Escalate to orchestrator ## Examples ### Example 1: Simple Task Execution **Spec**: TaskSpec for logout button (AC1.1: Clear token) **Implementation**: ```typescript // src/services/auth.service.ts async logout(): Promise { try { // Call API to invalidate session await this.api.post('/auth/logout'); // Clear local token (AC1.1) localStorage.removeItem('auth_token'); // Update auth state this.authState.next({ isAuthenticated: false }); } catch (error) { // AC2.1: Display error on failure throw new Error('Logout failed. Please try again.'); } } ``` **Evidence**: - Task marked complete in spec - Tests passing: `auth-service.test.ts` (2 tests) - AC1.1 verified: Token cleared from localStorage ### Example 2: Discovering Spec Gap **During implementation**, discovered: - Spec says "redirect to login page" - But doesn't specify: Should we preserve the return URL for after re-login? **Action**: ```markdown ## Open Questions - Q4: Should we preserve return URL for post-login redirect? (Status: blocking) - Discovered during implementation of redirect logic - Options: - A: Redirect to /login (simple, spec as written) - B: Redirect to /login?returnUrl= (better UX) - **Recommendation**: Option B for better UX - Awaiting user decision ``` **Result**: User chooses Option B → Update spec → Implement with return URL preservation ### Example 3: Parallel Implementation **Scenario**: MasterSpec with 3 workstreams **Main agent**: ```javascript // Dispatch implementers for each workstream const ws1 = Task({ description: "Implement WebSocket Server (ws-1)", prompt: "Implement workstream ws-1 from master spec...", subagent_type: "implementer", }); const ws2 = Task({ description: "Implement Frontend Client (ws-2)", prompt: "Implement workstream ws-2 from master spec...", subagent_type: "implementer", }); const ws3 = Task({ description: "Implement Notification Service (ws-3)", prompt: "Implement workstream ws-3 from master spec...", subagent_type: "implementer", }); // Wait for all to complete // Then run unifier for cross-workstream validation ``` **Result**: Parallel execution with main agent handling integration and contract validation