implementation-skill

name

implementation-skill

description

Single-agent spec implementation workflow for harness-visualizer. Use when asked to implement a spec, execute tasks from specs/, continue spec work, complete a phase/wave, or turn an implementation-ready requirements/design/tasks bundle into working TypeScript code (Vue 3 frontend, Express + Socket.IO backend). Adapted from the Claude Build plugin's implementation-team knowledge without multi-agent orchestration.

Implementation Skill

This skill is the single-agent version of Claude Build's implementation workflow. In Claude Build, an Opus orchestrator decomposes work, assigns file-owned waves to implementers, runs architect review, test writing, and quality gates. In this harness, you perform those roles yourself, sequentially and deliberately:

1. Orchestrator: load context, parse specs, inventory files, plan dependency-ordered work.
2. Implementer: write focused production code after reading existing patterns.
3. Test Writer: add/update Vitest tests covering happy paths, error paths, and edge cases.
4. Architect Reviewer: review your own changes against the spec, codebase patterns, and quality gates.

Do not use multi-agent orchestration. Do not spawn teammates. Preserve Claude Build's discipline: explicit decomposition, scoped file ownership per task, no coding before understanding the spec, and no completion claim until quality checks are addressed or clearly reported.

---

When to Use

Use this skill when the user asks to:

• implement a spec from specs/
• continue a spec's implementation
• complete a task, phase, wave, or checklist from tasks.md / progress.md
• turn a generated spec bundle into code
• verify or finish a partially implemented spec

If the user only asks to generate or refine spec documents, use the spec-generation workflow (/spec:* commands) instead.

---

Required Startup

Before changing code:

1. Load project instructions

   • Read root CLAUDE.md.
   • Read AGENTS.md for the tool-agnostic mirror.
   • Read ROADMAP.md to see how the requested spec maps to the 8-phase plan.
   • Read any nested CLAUDE.md (e.g. backend/CLAUDE.md, frontend/CLAUDE.md) if they exist.

2. Load implementation config

   • Read .claude/implementation-team.config.json for paths, conventions, and quality gate commands.
   • If absent, fall back to CLAUDE.md and observed patterns, but flag the missing config.

3. Load the spec bundle

   • Read spec.config.json if present.
   • Read, in priority order:
     1. tasks.md — primary implementation checklist
     2. design.md — architecture, components, data model, file inventory
     3. requirements.md — FR/NFRs and Given-When-Then acceptance criteria
     4. research/synthesis.md and relevant research/*.md — codebase constraints and risks
     5. discovery.md — source intent, scope, open questions
     6. progress.md — current completion state
     7. README.md, QA notes, orchestration run docs if present

4. Inspect current repo state

   • Run git status --short.
   • Do not overwrite unrelated user changes.
   • If files you need are already modified, inspect them and distinguish existing changes from yours.

---

How Specs Are Generated and What That Means for Implementation

Specs in specs/ are produced by the spec-gen plugin pipeline:

init → discover → research → requirements → design → tasks → progress

Artifact roles

Artifact	Implementation meaning
spec.config.json	Spec name, output path, sources, pipeline state. Use it to confirm the spec directory and whether the pipeline reached tasks.
discovery.md	Source-grounded intent. Use for context and resolving ambiguity, not as the direct coding checklist.
research/*.md	Evidence about existing code patterns, constraints, integration points, risks.
research/synthesis.md	Consolidated recommendations and known risks. Read before implementation for non-obvious codebase constraints.
requirements.md	EARS-format requirements: SHALL/SHOULD/MAY, FR IDs, NFRs, Given-When-Then acceptance criteria, scope, deferred items. Use to verify task/design coverage.
design.md	Technical architecture, component specs, data/API/IPC models, File Change Inventory. The implementation blueprint.
tasks.md	Strict task breakdown with phases, dependencies, acceptance criteria, files, and testing. Primary execution plan.
progress.md	Tracker for task status and session logs. Update when a task/phase completes or the user asks.

Parsing generated specs

Modern generated tasks.md usually uses this strict format:

### Task 1.1: Title
- **Type**: Backend | Frontend | Shared | Testing | DevOps
- **Priority**: High | Medium | Low
- **Effort**: estimate
- **Dependencies**: task IDs or None
- **Acceptance Criteria**:
  - [ ] criterion
- **Files**:
  - Create: paths or None
  - Modify: paths or None
- **Testing**: Unit | Integration | E2E | specifics

Parse flexibly. Extract normalized task fields: ID, title, phase, dependencies, files, acceptance criteria, testing, status.

---

Implementation Workflow

Phase 1: Context Loading

Read all required startup files. If the spec is vague, lacks tasks/design, or has blocking open questions, ask for clarification before coding.

Phase 2: Analysis and Decomposition

Before edits, build a working plan:

1. Task selection

   • If the user names specific task IDs, implement only those unless dependencies are missing.
   • If the user says to continue, choose the first unblocked incomplete task(s) from progress.md/tasks.md.
   • If the user asks for a full spec implementation, propose phase/wave execution rather than attempting a large spec in one uncontrolled pass.

2. File inventory

   • From design.md File Change Inventory and task Files sections, list every file to create/modify.
   • Read existing files and adjacent examples before editing.
   • For new files, verify the correct location from project conventions (backend/src/... vs frontend/src/...).

3. Dependency analysis

   • Map task dependencies from tasks.md.
   • Foundation usually comes first: shared types, zod schemas, Socket.IO event map, base stores.
   • Dependent work follows: services, components, wiring, tests.

4. Wave planning

   • Wave 0: shared contracts (TS types, zod schemas, Socket.IO event map).
   • Wave 1: backend or frontend tracks that don't depend on each other.
   • Wave 2: integration and wiring across the IPC boundary.
   • Wave 3: tests, review, docs/progress updates.
   • Keep the active change set small.

5. Approval checkpoint

   • For large or ambiguous changes, present the decomposition and wait for user approval.
   • For a small, explicit task, briefly state the plan and proceed.

Phase 3: Implementation

For each task:

1. Read existing patterns. Use grep/search for symbols, imports, and config; LSP if available for definitions/references.
2. Implement only the selected task scope.
3. Follow project conventions over personal preference:
   • Vue 3 SFCs with <script setup lang="ts">.
   • Pinia stores with composition API style.
   • TypeScript everywhere — no any without justification.
   • Express handlers stay thin; logic lives in backend/src/scanner|watcher|files|scoring.
   • All Socket.IO payloads validated with zod on both ends.
   • Filesystem access goes through the secure read/write helpers — never raw fs in handlers.
4. Do not add features or refactors beyond the spec.
5. If the task requires a file outside the task's file list, pause and justify it against the design before editing.

Phase 4: Testing

1. Read existing tests before creating new ones.
2. Choose the right layer:
   • Unit (Vitest) for pure functions: pattern matchers, scorers, path safety helpers.
   • Integration (Vitest with real fs) for scanner/watcher: use tmp dirs, write fixtures, assert emitted events.
   • Component (@vue/test-utils) for Vue components with non-trivial logic.
3. Cover happy path, invalid input, edge cases, and security boundaries (path traversal, symlink escape, oversized payloads).
4. Prefer behavior tests over implementation-detail tests.
5. Use precise assertions; avoid generic toBeTruthy() / not.toBeNull() when exact outcomes are knowable.
6. Run the narrowest useful tests first, then broader gates when the change set is ready.

Phase 5: Self Architect Review

Review your changes before claiming completion. Only flag substantive issues; do not bikeshed.

Checklist:

• Spec compliance: all selected task acceptance criteria met?
• Requirements traceability: related FR/NFR acceptance criteria satisfied?
• Architecture: follows existing Vue/Pinia/Express patterns?
• File scope: no unnecessary files changed?
• Type safety: no untyped escape hatches; zod schemas mirror TS types?
• Security: filesystem access goes through allowlisted helpers; no raw paths leak to handlers; bind address is 127.0.0.1?
• Performance: chokidar watch scope reasonable; no unbounded fast-glob; Socket.IO emits debounced where appropriate?
• Tests: meaningful coverage added/updated and passing where run?

Phase 6: Quality Gates

Run configured quality gates from .claude/implementation-team.config.json:

• Type check: npm run typecheck
• Lint: npm run lint
• Tests: npm run test (or narrower: npx vitest run path/to/file)

If a gate fails:

1. Determine whether the failure is caused by your changes.
2. Fix caused failures.
3. Re-run the failing gate or a narrower reproducer.
4. If unrelated or too broad/slow, report it clearly with evidence.

Never state that all checks passed unless you actually ran them.

Phase 7: Progress and Synthesis

When completing tasks:

1. Update progress.md if requested or part of the workflow.
   • Modern status: ⬜, 🔄, ✅, ⏸️, ❌.
   • Update summary counts and session log when present.
2. Final response should include:
   • tasks completed
   • files changed
   • tests/quality gates run and results
   • known limitations or follow-up items

---

File Ownership Discipline for a Single Agent

Claude Build enforces one owner per file to avoid merge conflicts. In this harness, apply the spirit:

• Treat each implementation pass as owning a small explicit file set.
• Avoid touching unrelated files.
• If two tasks require the same file, combine them in one pass or sequence them intentionally.
• If a file has user changes, preserve them and explain any interaction.

---

Research During Implementation

Search locally first:

• Use grep/search for strings, config values, routes, IPC events, and examples.
• Read adjacent files and similar implementations before choosing a pattern.

Use external docs only when local code and spec research do not answer a framework/library question. Prefer local conventions when they conflict with generic best practices unless the local pattern is unsafe or explicitly superseded by the spec.

---

Project-Specific Implementation Notes

From the project and implementation config:

• Languages: TypeScript everywhere.
• Stack: Vue 3 + Vite + Pinia (frontend); Express + Socket.IO + chokidar + fast-glob + gray-matter + zod (backend).
• Test framework: Vitest, with @vue/test-utils for components.
• Quality gates:
  • npm run typecheck
  • npm run lint
  • npm run test
• Security non-negotiables:
  • Backend binds to 127.0.0.1 only.
  • All filesystem paths resolved via fs.realpath and verified against the configured watch-root allowlist before any read or write.
  • Extension allowlist on editable files: .md, .markdown, .json, .yml, .yaml, .txt.
  • 1 MB read/write size cap.
  • Symlinks resolving outside watch roots are rejected.
• IPC discipline: Every Socket.IO event has a zod schema on both client and server. Reject unknown/invalid payloads.
• Dogfooding default: The app self-targets process.cwd() (or HARNESS_VISUALIZER_ROOT) on startup unless overridden by the user via the directory picker.

---

Stop Conditions

Stop and ask the user before coding when:

• The requested spec/task cannot be identified.
• Required source documents are missing or only stubs.
• Blocking open questions remain in discovery/research/requirements.
• The implementation requires scope outside the approved task/design.
• Existing uncommitted changes conflict with required edits.
• A quality gate reveals a broad failure needing product or architectural direction.