code-assist

# 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 interaction guidance

#### 4.2 Develop Implementation Code

Write implementation code to pass the tests, focusing on simplicity and correctness first.

**Constraints:**
- You MUST follow the TDD cycle: RED → GREEN → REFACTOR
- You MUST implement only what is needed to make current tests pass (YAGNI, KISS, SOLID)
- You MUST execute tests after each implementation step