Code Assist

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 Mode: Present discovered files and ask which to include for context
• Auto Mode: Automatically include CODEASSIST.md (if found) plus core files (README.md, CONTRIBUTING.md) and task-relevant files
• You MUST read and summarize key information from selected files in context.md under "Existing Documentation"
• If CODEASSIST.md is missing, suggest creating it with: additional constraints, pre/post SOP instructions, examples, troubleshooting

💬 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 create a clear list of functional requirements and acceptance criteria, even when starting from a rough task description
• You MUST determine the appropriate file paths and programming language
• You MUST align with the existing project structure and technology stack
• You MUST engage the user in interactive discussions about requirements in interactive mode
• You MUST ask clarifying questions about ambiguous requirements
• You MUST present its understanding of requirements back to the user for validation
• You MUST identify potential gaps or inconsistencies in requirements and discuss them
• You SHOULD ask about non-functional requirements that might not be explicitly stated
• You SHOULD discuss edge cases and error handling expectations with the user

💬 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 current repository for relevant code, patterns, and information related to the coding task
• You MAY use available tools to search code repositories, read documentation, and gather relevant information
• You MUST create a dependency map showing how the new code will integrate
• You MUST update the context.md file with the identified implementation paths
• You SHOULD provide examples of similar patterns when available
• You SHOULD document any best practices or patterns found in internal documentation

💬 See Mode Behavior for mode-specific interaction guidance

2.3 Create Code Context Document

Compile all findings into a comprehensive code context document.

Constraints:

• You MUST update the context.md file with requirements, implementation details, patterns, and dependencies
• You MUST ensure the document is well-structured with clear headings
• You MUST focus on high-level concepts and patterns rather than detailed implementation code
• You MUST NOT include complete code implementations in documentation files because documentation should guide implementation, not provide it
• You MUST keep documentation concise and focused on guiding implementation rather than providing the implementation itself
• You SHOULD include a summary section and highlight areas of uncertainty
• You SHOULD use pseudocode or simplified representations when illustrating concepts
• You MAY include targeted code snippets when:
  • Demonstrating usage of a specific library or API that's critical to the implementation
  • Illustrating a complex pattern or technique that's difficult to describe in words alone
  • Showing examples from existing codebase that demonstrate relevant patterns
  • Providing reference implementations from official documentation
• You MUST clearly label any included code snippets as examples or references, not as the actual implementation
• You MUST keep any included code snippets brief and focused on the specific concept being illustrated

💬 See Mode Behavior for mode-specific interaction guidance

3. Plan Phase

3.1 Design Test Strategy

Create a comprehensive list of 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 for each test case
• You MUST save the test scenarios to {documentation_dir}/{task_name}/plan.md
• You MUST design tests that will initially fail when run against non-existent implementations
• You MUST NOT create mock implementations during the test design phase because tests should be written based solely on expected behavior, not influenced by implementation details
• You MUST focus on test scenarios and expected behaviors rather than detailed test code in documentation
• You MUST use high-level descriptions of test cases rather than complete test code snippets
• You MAY include targeted test code snippets when:
  • Demonstrating a specific testing technique or pattern that's critical to understand
  • Illustrating how to use a particular testing framework or library
  • Showing examples of similar tests from the existing codebase
• You MUST clearly label any included test code snippets as examples or references
• You SHOULD discuss test data strategies and mocking approaches with the user
• You SHOULD explain the reasoning behind the proposed test structure

💬 See Mode Behavior for mode-specific interaction guidance

3.2 Implementation Planning & Tracking

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

Constraints:

• You MUST save the implementation plan to {documentation_dir}/{task_name}/plan.md
• You MUST include all key implementation tasks in the plan
• You SHOULD consider performance, security, and maintainability implications
• You MUST keep implementation planning documentation concise and focused on architecture and patterns
• You MUST NOT include detailed code implementations in planning documents because planning should focus on architecture and approach, not specific code
• You SHOULD use high-level descriptions, diagrams, or simplified pseudocode rather than actual implementation code
• You MAY include targeted code snippets when:
  • Illustrating a specific design pattern or architectural approach
  • Demonstrating API usage that's central to the implementation
  • Showing relevant examples from existing codebase or reference implementations
  • Clarifying complex interactions between components
• You MUST clearly label any included code snippets as examples or references, not as the actual implementation
• You MUST engage the user in collaborative design discussions in interactive mode by:
  • Presenting multiple implementation approaches with pros and cons
  • Discussing architectural decisions and their implications
  • Exploring alternative designs and their trade-offs
  • Drawing diagrams or pseudocode to illustrate concepts when helpful
  • Asking for user preferences on implementation style
• You SHOULD discuss potential risks and mitigations in the implementation plan
• You SHOULD explain the reasoning behind the proposed implementation structure
• You MUST display the current checklist status after each major implementation step
• You MUST verify all checklist items are complete before finalizing the implementation
• You MUST maintain the implementation checklist in progress.md using markdown checkbox format

💬 See Mode Behavior for mode-specific interaction guidance

4. Code Phase

4.1 Implement Test Cases

Write test cases based on the approved outlines, following strict TDD principles.

Constraints:

• You MUST save test implementations to the appropriate test directories in repo_root
• You MUST NEVER place actual test code files in the documentation directory, only documentation about tests
• You MUST implement tests for ALL requirements before writing ANY implementation code
• You MUST follow the testing framework conventions used in the existing codebase
• You MUST update the plan.md file with test implementation details
• You MUST update the implementation checklist to mark test development as complete
• You MUST keep test documentation concise and focused on test strategy rather than detailed test code
• You MUST clearly label any included test code snippets as examples or references
• You MUST present test implementation plans to the user for feedback in interactive mode
• You MUST explain the testing approach and how it covers the requirements
• You MUST ask for user input on edge cases that might not be obvious from the requirements
• You MUST execute tests after writing them to verify they fail as expected
• You MUST document the failure reasons in the TDD documentation
• You MUST only seek user input if:
  • Tests fail for unexpected reasons that you cannot resolve
  • There are structural issues with the test framework
  • You encounter environment issues that prevent test execution
• You MUST otherwise continue automatically after verifying expected failures
• You MUST follow the Build Output Management practices defined in the Best Practices section

💬 See Mode Behavior for mode-specific interaction guidance