/code-assist

name: code-assist
description: Implement coding tasks with an explore-plan-code workflow and explicit verification gates.
kind: sop

Code Assist

Overview

This sop guides the implementation of code tasks using test-driven development principles, following a structured Explore, Plan, Code, Commit workflow. It balances automation with user collaboration while adhering to existing package patterns and prioritizing readability and extensibility. The agent acts as a Technical Implementation Partner and TDD Coach - providing guidance, generating test cases and implementation code that follows existing patterns, avoids over-engineering, and produces idiomatic, modern code in the target language.

Parameters

• **task_description** (required): A description of the task to be implemented. This can be a detailed specification with requirements and acceptance criteria, or even a rough idea that will be refined during the explore and plan phases
• **additional_context** (optional): Any supplementary information that would help with understanding the implementation context
• **documentation_dir** (optional, default: ".agents/scratchpad/{project_name}"): The directory where planning documents will be stored
• **repo_root** (optional, default: current working directory): The root directory of the repository for code implementation
• **project_name** (optional): Project name for organizing working files. If processing a code task file, will be inferred from the task path. Otherwise, will be generated from the task description with a YYYY-MM-DD date prefix.
• **task_name** (optional): A short, descriptive name for the implementation task
• **mode** (optional, default: "auto"): The interaction mode:
• "interactive": Collaboration with user confirmation at each step
• "auto": No user interaction after initial setup

**Constraints for parameter acquisition:**

• You MUST ask for all parameters upfront in a single prompt, not just required ones because this ensures efficient workflow and prevents repeated interruptions during execution
• You MUST support multiple input methods for task_description and additional_context (direct input, file path, URL)
• You MUST normalize mode input to "interactive" or "auto"
• You MUST validate directory paths and generate task_name if not provided
• You MUST confirm successful acquisition of all parameters before proceeding
• If mode is "auto", you MUST warn the user that no further interaction will be required

Mode Behavior

Apply these patterns throughout all steps based on the selected mode:

**Interactive Mode:**

• Present proposed actions and ask for confirmation before proceeding
• When multiple approaches exist, explain pros/cons and ask for user preference
• Review artifacts and solicit specific feedback before moving forward
• Ask clarifying questions about ambiguous requirements
• Pause at key decision points to explain reasoning
• Adapt to user feedback and preferences
• Provide educational context when introducing new patterns or techniques

**Auto Mode:**

• Execute all actions autonomously without user confirmation
• Document all decisions, assumptions, and reasoning in progress.md
• When multiple approaches exist, select the most appropriate and document why
• Provide comprehensive summaries at completion

Important Notes

**Separation of Concerns:** This script maintains strict separation between documentation and code. All documentation about the implementation process is stored in the documentation directory, while all actual code (both tests and implementation) must be placed in the appropriate directories within the repository root. No code files should ever be placed in the documentation directory.

**CODEASSIST.md Integration:** If CODEASSIST.md exists in repo_root, it contains additional constraints, pre/post SOP instructions, examples, and troubleshooting specific to this project. Apply any specified practices throughout the implementation process.

Steps

1. Setup

Initialize the project environment and create necessary directory structures.

**Constraints:**

• You MUST validate and create the documentation directory structure properly:
• Use `mkdir -p {documentation_dir}` to explicitly create the documentation directory as a directory
• Create the full path: `{documentation_dir}/{task_name}/` with logs subdirectory using `mkdir -p`
• Verify the directory structure was created successfully before proceeding
• You MUST discover existing instruction files using: `find . -maxdepth 3 -type f \( -path "*/node_modules/*" -o -path "*/build/*" -o -path "*/.venv/*" -o -path "*/venv/*" -o -path "*/__pycache__/*" -o -path "*/.git/*" -o -path "*/dist/*" -o -path "*/target/*" \) -prune -o -name "*.md" -print | grep -E "(CODEASSIST|DEVELOPMENT|SETUP|BUILD|CONTRIBUTING|ARCHITECTURE|TESTING|DEPLOYMENT|TROUBLESHOOTING|README)" | head -20`
• You MUST read CODEASSIST.md if found and apply its constraints throughout (see Important Notes)
• You MUST notify the user when the structure has been created
• You MUST handle directory creation errors gracefully and report specific issues to the user
• You MUST NOT proceed with the script if directory creation fails because this would cause subsequent steps to fail
• You MUST ONLY place documentation files in the documentation directory, NEVER code implementations because mixing documentation and code creates confusion and violates the separation of concerns principle
• You MUST ensure all actual code implementations are placed in the appropriate directories within repo_root, NOT in the documentation directory
• You MUST create a context.md file documenting project structure, requirements, patterns, dependencies, and implementation paths
• You MUST create a progress.md file to track script execution using markdown checklists, setup notes, and implementation progress

**Instruction File Discovery:**

• You MUST run the find command to discover available instruction files
• **Interactive Mod