/code-assist

name: code-assist
description: Guides implementation of code tasks using test-driven development in an Explore, Plan, Code, Commit workflow. Acts as a Technical Implementation Partner and TDD Coach — following existing patterns, avoiding over-engineering, and producing idiomatic, modern code.
type: anthropic-skill
version: "1.1"
metadata:
  internal: true

Code Assist

Overview

Guides implementation of code tasks using test-driven development in an Explore, Plan, Code, Commit workflow. Balances automation with user collaboration while adhering to existing package patterns and prioritizing readability and extensibility.

Parameters

• **task_description** (required): Task specification, rough idea, file path to `.code-task.md`, or URL
• **additional_context** (optional): Supplementary information for implementation context
• **documentation_dir** (optional, default: ".sop/planning"): Directory for planning documents
• **repo_root** (optional, default: current working directory): Repository root for code implementation
• **task_name** (optional): Short descriptive name (auto-generated if not provided)
• **mode** (optional, default: "auto"): "interactive" (confirmation at each step) or "auto" (autonomous execution)

**Constraints:**

• You MUST ask for all parameters upfront in a single prompt to avoid repeated interruptions
• You MUST validate inputs: normalize mode to "interactive"/"auto", verify paths, generate task_name if needed

Mode Behavior

Apply these patterns throughout all steps:

**Interactive Mode:** Present actions for confirmation. Explain pros/cons when multiple approaches exist. Ask clarifying questions. Pause at key decision points. Provide educational context.

**Auto Mode:** Execute autonomously. Document all decisions and reasoning in progress.md. Select the most appropriate approach and document why. Provide comprehensive summaries at completion.

Important Notes

**Separation of Concerns:** Documentation goes in `{documentation_dir}`. Code (tests and implementation) goes in `repo_root`. Never mix them. Documentation should guide implementation with high-level concepts — not provide it. When including code snippets in documentation, keep them brief and clearly label them as examples or references.

**CODEASSIST.md Integration:** If CODEASSIST.md exists in repo_root, read it and apply its constraints throughout.

Steps

1. Setup

Initialize the project environment and create necessary directory structures.

**Constraints:**

• You MUST create `{documentation_dir}/implementation/{task_name}/` (with logs subdirectory) and verify it exists before proceeding
• You MUST discover instruction files (CODEASSIST.md, README.md, CONTRIBUTING.md, ARCHITECTURE.md, etc.) and summarize relevant information in context.md
• You MUST create context.md (project structure, requirements, patterns, dependencies) and progress.md (execution tracking with markdown checklists)
• If task_description points to a `.code-task.md` with YAML frontmatter, update `status: in_progress` and `started: <date>` (if not already set)

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific interaction guidance

2. Explore Phase

2.1 Analyze Requirements and Context

Analyze the task description and existing documentation to identify core functionality, edge cases, and constraints.

**Constraints:**

• You MUST produce a clear list of functional requirements and acceptance criteria, even from rough descriptions
• You MUST determine appropriate file paths, language, and alignment with existing project structure
• In interactive mode, discuss requirements with the user, clarify ambiguities, and validate your understanding

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific interaction guidance

2.2 Research Existing Patterns

Search for similar implementations and identify interfaces, libraries, and components the implementation will interact with.

**Constraints:**

• You MUST search the repository for relevant code, patterns, and conventions
• You MUST create a dependency map and update context.md with implementation paths

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific interaction guidance

3. Plan Phase

3.1 Design Test Strategy

Create test scenarios covering normal operation, edge cases, and error conditions.

**Constraints:**

• You MUST cover all acceptance criteria with at least one test scenario
• You MUST define explicit input/output pairs and save scenarios to plan.md
• You MUST design tests that will initially fail (no mock implementations during design)

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific interaction guidance

3.2 Implementation Planning & Tracking

Outline the high-level structure and create an implementation plan.

**Constraints:**

• You MUST save the plan to plan.md with key implementation tasks
• You MUST maintain an implementation checklist in progress.md using markdown checkbox format
• In interactive mode, present multiple approaches with pros/cons and discuss trade-offs

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific interaction guidance

4. Code Phase

**Phase-wide constraints:**

• You MUST place all code (tests and implementation) in repo_root, never in documentation_dir
• You MUST verify tests/builds pass before advancing to the next sub-step
• You MUST follow the existing codebase's conventions (naming, patterns, error handling, testing style)
• Pipe build output to `{documentation_dir}/implementation/{task_name}/logs/` and search for success/failure indicators

4.1 Implement Test Cases

Write test cases following strict TDD principles.

**Constraints:**

• You MUST implement tests for ALL requirements before writing ANY implementation code
• You MUST execute tests to verify they fail as expected, documenting failure reasons
• You MUST follow the testing framework conventions used in the existing codebase

> 💬 See [Mode Behavior](#mode-behavior) for mode-specific inte