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 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 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 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 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 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 for mode-specific interaction guidance