Agentic workflow - CLAUDE

CLAUDE.md

Devenv / nix

The project uses devenv and has access to nix. If a tool is not available, check if its provided via the devenv packages or reference it using a nix shell.

When running commands, you usually will want to do so through devenv shell to ensure bundler and gems are setup properly.

If a tool is used frequently, suggest adding it to the devenv packages.

Performing work

Each conversation will mainly be focused into a specific 'mode' of work:

• 'planning'. In planning mode, plans are forumulated for work, but edits to project files are not made. Plans may be discussed directly in conversation; once a plan is finalized, write it to .agent/PLAN.md for user evaluation and edits.

• 'execution'. In execution mode, plans written to .agent/PLAN.md are put into action. Project files may be edited, but no further edits to the .agent/PLAN.md file are to be made. Instead, progress is communicated via more markdown files in .agent. For example, if a plan calls for two steps of "setup test suite" and "add relevant tests", we might create .agent/setup-test-suite.md and .agent/add-tests.md. Futher context may be put into those specific files as needed to keep track of state and research findings. As tasks are worked, files should be renamed to indicate state. eg. .agent/setup-test-suite.INPROGRESS.md or .agent/setup-test-suite.DONE.md

  IMPORTANT: Execute plan steps in sequential order. Complete each step fully before moving to the next step. Do not skip ahead or jump to later steps even if you think you've identified the solution early. Each step in the plan exists for a reason (gathering data, confirming hypotheses, etc.). Skipping steps can lead to fixing the wrong problem or missing important context.

  EXECUTION MODE START PROTOCOL: When entering execution mode, the agent must:

  1. Read .agent/PLAN.md to understand all planned tasks
  2. Check .agent/ directory for existing progress files to determine what's been completed
  3. Present a bulleted list of all tasks from the plan with their current status (pending/in-progress/done)
  4. Ask the user: "What task would you like me to work on next? (specify task number/name, or 'all' to execute all remaining tasks)"
  5. If given a specific task: Work that entire task fully to completion, then STOP and restart with the bulleted list
  6. If given 'all': Work through all remaining tasks in sequential order without stopping

• other. If not in either 'planning' or 'execution' mode, then the .agent folder workflow may be ignored and normal execution resumes

Working Directories

.agent/ - Execution tracking and progress documentation

• Use for markdown files tracking plan execution steps
• Name files descriptively (e.g., setup-test-suite.md, fix-parameter-bug.md)
• Use suffixes to indicate state: .INPROGRESS.md, .DONE.md
• Files here communicate progress to the user

.agent-workdir/ - Scratch directory for temporary artifacts

• Use for scripts, test output logs, intermediate data, compressed context
• Put ALL temporary files here (scripts, logs, test results, etc.)
• NEVER put temporary artifacts in /tmp - always use .agent-workdir/
• This directory is ignored by git and can be freely used in any mode
• Examples: test runner scripts, verification logs, data processing intermediates

Long-Running Commands

• The bash tool has a maximum timeout of 120000ms (2 minutes). For commands that may exceed this limit, use the tool's built-in background execution feature by setting run_in_background: true.
• When using background execution:
  • The tool returns a shell_id that can be used to check progress with mcp__acp__BashOutput or terminate with mcp__acp__KillShell
  • Track background processes in .agent-workdir/BACKGROUND_PROCESSES.md with the shell_id
  • Check progress periodically using mcp__acp__BashOutput with the shell_id
• For commands that won't exceed 2 minutes but might take longer than a few seconds (builds, installs, quick tests), supply an explicit timeout parameter so hung processes terminate predictably.
• For this project, commands involving devenv shell typically take longer due to environment setup overhead. Use generous timeouts (e.g., 120000ms = 2 minutes for test runs).

End-of-Conversation Checklist

Before conversation ends or reaches a natural stopping point, create/update .agent-workdir/BACKGROUND_PROCESSES.md with:

• List of all background processes still running
• The shell_id returned by the bash tool (for processes started with run_in_background: true)
• The exact command line used to start each process
• What each process is doing
• Expected completion time
• How to check progress or kill the process

Example format:

# Background Processes

## Active Processes

### Process: Verification test suite (100 iterations)
- **Shell ID:** 6cea5544-3a8c-4771-8c2c-915baf1be727
- **Command:** `bundle exec rspec spec/verification --iterations=100`
- **Started:** 2025-10-03 15:45:00
- **Expected completion:** ~10 minutes from start
- **Check progress:** Use `mcp__acp__BashOutput` with shell_id
- **Kill if needed:** Use `mcp__acp__KillShell` with shell_id

## Completed Processes
- Shell ID abc123: Baseline tests (completed successfully at 15:30:00)