implement-delta

# Implementation Workflow Implement a delta following its plan. ## Input Delta ID: $ARGUMENTS (e.g., "DLT-001") ## Context **You must load the following skills and read the following files before proceeding.** ### Skills - `katachi:framework-core` - Workflow principles - `katachi:working-on-delta` - Per-feature workflow - `katachi:research-docs` - Documentation research for correct API usage ### Delta inventory - `docs/planning/DELTAS.md` - Delta definitions ### Delta documents - `docs/delta-specs/$ARGUMENTS.md` - What to build (requirements) - `docs/delta-designs/$ARGUMENTS.md` - Why/how (design rationale) - `docs/delta-plans/$ARGUMENTS.md` - Implementation plan with batches ### Project decisions - `docs/architecture/README.md` - Architecture decisions (ADRs) - `docs/design/README.md` - Design patterns (DES) ### Feature documentation (for acceptance criteria and architecture) - Read affected feature specs from delta-spec (use as acceptance criteria source) - Read affected feature designs from delta-design (use as architecture guidance) - Feature specs define what behavior to implement - Feature designs define architectural patterns to follow ## Pre-Check Verify all documentation exists: - If spec/design/plan missing, suggest running appropriate commands first - Plan is the primary guide for implementation Update status: ```bash python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "⧗ Implementation" ``` ## Working with Batches The implementation plan is organized into batches — scoped groups of steps with their own context and dependencies. Before implementing, understand how to work with them: ### Context & Research entries Each batch lists the documents, code files, and research pointers it needs. These are a **starting point, not a contract**: - **Read** the listed entries before starting the batch - **Adapt as you go**: remove entries that turn out to be irrelevant, add files you discover during implementation, update references if earlier batches produced different output than planned - **Follow research pointers**: when a context entry points to library docs or an existing pattern, look it up. For any library or framework referenced in the batch, follow the `katachi:research-docs` skill guidance to verify current API signatures before writing code — do not rely on training data for library APIs - **Write findings back**: when research reveals important information (API behavior, library patterns, design constraints), write those findings to the design doc (`docs/delta-designs/$ARGUMENTS.md`) for later reconciliation. This is critical — implementation knowledge must flow back to documentation ### Batch status tracking Update each batch's status marker in the plan file (`docs/delta-plans/$ARGUMENTS.md`) as you progress: - `⧗ Pending` — not yet started - `⧗ Implementing` — currently in progress - `✓ Done` — all steps completed and verified ### Living documents If a different approach is needed for valid reasons during implementation: - Update the relevant document (spec/design/plan) immediately - Then proceed with the new approach - This applies to batch context entries too — update them to reflect reality ## Execution Mode Read the implementation plan and analyze batch dependencies (`Depends on:` fields). - **If all batches are sequential** (each depends on the previous) → execute batches one at a time as the single agent - **If independent batches exist** (batches with no cross-dependencies) → spawn parallel agents, one per independent batch --- ## Sequential Execution Used when batches form a dependency chain. The lead agent implements everything directly. ### 1. Process Each Batch For each batch in dependency order: 1. **Mark batch** as `⧗ Implementing` in the plan file 2. **Load context**: Read the batch's Context & Research entries. For ADRs/DES, read the full documents, not just indexes 3. **Research**: Follow research pointers — for any libraries/frameworks involved, follow the `katachi:research-docs` skill guidance to verify current APIs. Investigate patterns. Write important findings to the design doc 4. **Implement steps**: Work through the batch's steps autonomously - Follow relevant decisions (ADRs/DES) - Add code comments referencing decisions when the choice would be unclear without context (`// See ADR-003 for why we use X instead of Y`) - Verify each step works before proceeding 5. **Mark batch** as `✓ Done` in the plan file 6. **Adapt next batches**: If this batch's output differs from what was planned, update context entries in subsequent batches before starting them Use scratchpad `/tmp/implement-$ARGUMENTS-state.md` to track: - Current batch and step - Issues encountered - Patterns detected - Deviations from plan - Research findings ### 2. Verify Acceptance Criteria After all batches are done: - Run all tests - Run linting and type checking (fix any issues) - Perform manual checks against spec - **Exercise the running system**: launch the delta's feature and drive its real runtime path — hit the HTTP endpoint (e.g. `curl`), invoke the CLI, or drive the UI, as fits the project — and confirm the observed behavior matches each acceptance criterion, not just that tests pass. Infer the run command from the project (package.json/Makefile/etc.) or ask if it's unclear. Stay within the local/dev environment: never touch production or other real shared services, and never run destructive or irreversible commands that could affect anything beyond the local setup — reading/writing local files and data and driving local/dev services is fine. Skip only when the change has no runtime surface to drive (a pure library or internal refactor), and say so. - Ensure all acceptance criteria are met ### 3. Present for User Review Show complete implementation to user: - Summarize what was implemented - Highlight any deviations from plan (with rationale) - Note any emergent patterns detected - Note any research findings written back to design doc Invite feedback: "What needs adjustment in this implementation?" ### 4. Iterate Based on User Feedback Apply user corrections or changes. Re-test after changes. **When user rejects code changes:** Update documents consistently. Repeat until user approves. ### 5. Finalize Update status: ```bash python ${CLAUDE_PLUGIN_ROOT}/scripts/deltas.py status set $ARGUMENTS "✓ Implementation" ``` Present summary: ``` "Delta implementation complete for $ARGUMENTS. [Brief explanation of what was implemented] Files changed: - [file]: [what changed] - ..." ``` Offer to commit: "Ready to commit this implementation?" --- ## Parallel Execution Used when the plan contains independent batches (batches without cross-dependencies). The lead agent orchestrates agents rather than implementing directly. ### 1. Analyze Batch Dependencies Read all batches and their `Depends on:` fields. Identify: - **Independent batches**: No dependencies on each other — can run in parallel - **Dependent batches**: Must wait for their dependencies to complete Group into execution waves: - Wave 1: All batches with no dependencies - Wave 2: Batches that depend only on Wave 1 batches - Continue until all batches are scheduled ### 2. Set Up Team and Tasks 1. Create team with `TeamCreate` (name: `dlt-<delta-id>-implementation`) 2. Create **one task per batch** using the batch scope as the task description 3. Set up task dependencies matching the batch `Depends on:` fields 4. Assign independent batches to separate agents ### 3. Spawn Agents for Independent Batches Spawn agents **in parallel** (single message, multiple Agent tool calls) with: - `subagent_type`: `"general-purpose"` - `model`: `"sonnet"` (unless user specifies otherwise) - `mode`: `"bypassPermissions"` - `team_name`: the team name from step 2 - `run_in_background`: `true` Each agent's prompt must include: - Their batch assignment (e.g., "You are implementing Batch 2: Search Endpoint for DLT-054") - Instructions to: - Read the plan (`docs/delta-plans/$ARGUMENTS.md`) — specifically their batch section - Read the spec and design documents - Load their batch's Context & Research entries (read full ADR/DES documents, not just indexes) - Follow research pointers and write findings to the design doc - Implement their batch's steps autonomously - Mark batch as `✓ Done` in the plan file when complete - Message `team-lead` for any decisions not covered by the documentation - Run verification for their area (test, typecheck, lint) - The project's coding style guidelines (copy relevant sections from CLAUDE.md) ### 4. Monitor, Coordinate, and Execute Dependent Batches After spawning agents: - Respond to agent questions about decisions not covered by documentation - Monitor task progress via `TaskList` - When independent batches complete, spawn agents for newly unblocked dependent batches - Does NOT implement code directly — delegate mode ### 5. Verify and Review Once all batches are complete: - Run full test suites for all affected areas - Run linting and type checking across the whole project - Fix any integration issues between agent outputs - **Exercise the running system**: launch the delta's feature and drive its real runtime path — hit the HTTP endpoint (e.g. `curl`), invoke the CLI, or drive the UI, as fits the project — and confirm the observed behavior matches each acceptance criterion, not just that tests pass. Infer the run command from the project (package.json/Makefile/etc.) or ask if it's unclear. Stay within the local/dev environment: never touch production or other real shared services, and never run destructive or irreversible commands that could affect anything beyond the local setup — reading/writing local files and data and driving local/dev services is fine. Skip only when the change has no runtime surface to drive (a pure library or internal refactor), and say so. Then follow steps 3-5 from Sequential Execution (present to user, iterate, finalize). --- ## Working with Decisions **Using ADRs and DES:** - Read all decisions referenced in the current batch's context - Follow constraints unless there's good reason to deviate - If deviation needed: discuss with user, consider updating decision **Referencing in Code:** - Add comments ONLY when choice would be unclear without context - Format: `// See [DECISION-ID]: [brief reason]` - Don't reference obvious patterns **Pattern Detection:** - Watch for repeated code structures - Notice cross-cutting concerns - Suggest documentation when patterns should be consistent ## Workflow **Batch-by-batch implementation:** - Read plan and analyze batch dependencies - For each batch: load context, research, implement steps, mark done - If independent batches exist: spawn parallel agents per batch - After all batches: verify acceptance criteria (tests, lint, types, manual checks, plus exercising the running system against local/dev only) - Present to user for final review - Iterate based on feedback - Commit when approved