claude-agent 1.2.0

package/commands/ca/context.md

@@ -0,0 +1,47 @@
+# /ca:context — Show Persistent Context
+
+## Prerequisites
+
+No prerequisites.
+
+## Behavior
+
+### 1. Show persistent context
+
+Read and display the contents of `.claude/rules/ca-context.md` (project context) and `~/.claude/rules/ca-context.md` (global context).
+
+If the files are empty or don't exist, tell the user there's no saved context yet and suggest using `/ca:remember <info>` to add some.
+
+### 2. Show loaded files in current context
+
+Check your own context window to determine which files are currently loaded. Do NOT use Glob or Read tools to check the disk — instead, inspect what you can actually "see" in your current conversation context.
+
+For each of the following categories, report whether the file's content is present in your context and show a brief summary if loaded:
+
+**Auto-loaded via rules/ system** (loaded into context automatically by Claude Code if the file exists on disk):
+- `~/.claude/rules/ca-rules.md` — shared rules
+- `~/.claude/rules/ca-settings.md` — global language settings
+- `~/.claude/rules/ca-context.md` — global persistent context
+- `~/.claude/rules/ca-errors.md` — global error lessons
+- `.claude/rules/ca-settings.md` — project language settings
+- `.claude/rules/ca-context.md` — project persistent context
+- `.claude/rules/ca-errors.md` — project error lessons
+
+**Runtime config** (loaded only when a workflow command explicitly reads them):
+- `~/.claude/ca/config.md` — global config
+- `.ca/config.md` — workspace config
+
+**Workflow files** (loaded only when read during workflow command execution):
+- `.ca/current/STATUS.md`
+- `.ca/current/BRIEF.md`
+- `.ca/current/REQUIREMENT.md`
+- `.ca/current/RESEARCH.md`
+- `.ca/current/PLAN.md`
+- `.ca/current/SUMMARY.md`
+
+**Other persistent data:**
+- `.ca/todos.md`
+- `.ca/map.md`
+
+Only display files that are loaded in your context. Skip files that are not loaded — do not show them at all.
+For each loaded file, show: ✅ **Loaded** — followed by a 1-line summary.

package/commands/ca/discuss.md

@@ -0,0 +1,74 @@
+# /ca:discuss — Discuss Requirements
+
+## Prerequisites
+
+1. Check `.ca/current/STATUS.md` exists. If not, tell the user to run `/ca:new` first and stop.
+2. Read `.ca/current/STATUS.md` and check `workflow_type`. If `workflow_type: quick`, tell the user: "This is a quick workflow. The discuss step is skipped. Please proceed with `/ca:plan`." **Stop immediately.**
+
+## Behavior
+
+You are conducting a focused requirements discussion. Your goal is to understand **exactly** what the user wants before any code is written.
+
+### 1. Start the discussion
+
+Read `.ca/current/BRIEF.md` if it exists. Use the brief as the starting point for the discussion — acknowledge what the user wants to do based on the brief.
+
+Also read `.ca/map.md` (if exists) to understand the project structure and inform the discussion.
+
+If the user also provided a task description with this command, incorporate it as well.
+
+If neither the brief nor a task description exists, ask what they want to accomplish.
+
+### 2. Ask clarifying questions ONE AT A TIME
+
+Do NOT dump a list of questions. Ask the most important question first, wait for the answer, then ask the next based on their response. Focus on:
+
+- **Scope**: What exactly should change? What should NOT change?
+- **Behavior**: What should happen? What's the expected input/output?
+- **Constraints**: Any specific approaches to use or avoid?
+- **Success criteria**: How will we know it's done correctly?
+
+Keep asking until the requirements are clear. Typically 2-5 questions suffice.
+
+**IMPORTANT**: If the user indicates they don't understand your question, you MUST stop and explain or rephrase the current question. Do NOT move on to the next question until the current one is resolved. Follow the Discussion Completeness Rule in `_rules.md`.
+
+**When a question has clear, enumerable options** (e.g., choosing between approaches, selecting a strategy, yes/no decisions), use `AskUserQuestion` with appropriate options instead of plain text. Reserve plain text for open-ended questions that cannot be expressed as choices.
+
+### 3. Present requirement summary
+
+When you have enough information, present a structured summary:
+
+```
+## Requirement Summary
+
+### Goal
+<one-line description>
+
+### Details
+<specific requirements>
+
+### Scope
+- Files/areas affected: ...
+- Out of scope: ...
+```
+
+### 4. MANDATORY CONFIRMATION
+
+Use `AskUserQuestion` with:
+- header: "Requirements"
+- question: "Does this accurately capture your requirements?"
+- options:
+  - "Accurate" — "Requirements are correct, proceed"
+  - "Needs changes" — "I want to revise something"
+
+- If **Accurate**: Write the summary to `.ca/current/REQUIREMENT.md` and also write the success criteria to `.ca/current/CRITERIA.md`:
+```
+# Success Criteria
+
+1. ...
+2. ...
+```
+Update STATUS.md (`discuss_completed: true`, `current_step: discuss`). Tell the user they can proceed with `/ca:research` or `/ca:plan` (or `/ca:next`). Suggest using `/clear` before proceeding to the next step to free up context.
+- If **Needs changes**: Ask what needs to change, revise the summary, and ask for confirmation again.
+
+**Do NOT proceed to any next step automatically. Wait for the user to invoke the next command.**

package/commands/ca/execute.md

@@ -0,0 +1,86 @@
+# /ca:execute — Execute Confirmed Plan
+
+Read `~/.claude/ca/config.md` for global config, then read `.ca/config.md` for workspace config. Workspace values override global values. These are needed for runtime settings (model_profile, auto_proceed_*, per-agent model overrides).
+
+## Prerequisites
+
+1. Check `.ca/current/STATUS.md` exists. If not, tell the user to run `/ca:new` first and stop.
+2. Read `.ca/current/STATUS.md` and verify `plan_confirmed: true`. If not, tell the user to run `/ca:plan` first and get all three confirmations. **Stop immediately.**
+
+## Behavior
+
+You are the execution orchestrator. You delegate the actual work to the `ca-executor` agent running in the foreground.
+
+### 1. Read context
+
+Read these files and collect their full content:
+- `.ca/current/PLAN.md`
+- `.ca/current/REQUIREMENT.md` (or `.ca/current/BRIEF.md` if `workflow_type: quick`)
+
+### 1b. Ensure codebase map exists
+
+Check if `.ca/map.md` exists:
+- If it does NOT exist, check if the project has existing source files (i.e., the project is not empty).
+  - If the project is **not empty**: Run `/ca:map` to create the codebase map before proceeding to execution.
+  - If the project is **empty** (new project): Skip for now — the map will be created after execution (see step 7).
+
+### 2. Resolve model for ca-executor
+
+Read the model configuration from config (global then workspace override):
+1. Check for per-agent override: `ca-executor_model` in config. If set, use that model.
+2. Otherwise, read `model_profile` from config (default: `balanced`). Read `references/model-profiles.md` and look up the model for `ca-executor` in the corresponding profile column.
+3. The resolved model will be passed to the Task tool.
+
+### 3. Launch ca-executor agent
+
+Use the Task tool with `subagent_type: "ca-executor"` and the resolved `model` parameter to launch the ca-executor agent. Pass it:
+- The full content of PLAN.md
+- The full content of REQUIREMENT.md (or BRIEF.md if `workflow_type: quick`)
+- The project root path
+- Instructions to follow the `ca-executor` agent prompt
+
+The agent runs in the foreground and executes the implementation steps, returning an execution summary.
+
+### 4. Write SUMMARY.md
+
+Take the agent's returned summary and write it to `.ca/current/SUMMARY.md`.
+
+### 5. Present execution summary
+
+Display to the user:
+
+```
+## Execution Summary
+
+### Changes Made
+- file1.py — what changed
+- file2.py — what changed
+
+### Steps Completed
+1. ...
+2. ...
+
+### Notes/Deviations (if any)
+- ...
+```
+
+### 6. Update STATUS.md
+
+Set `execute_completed: true`, `current_step: execute`.
+
+### 7. Update codebase map
+
+If `.ca/map.md` exists:
+- Read the current map and the execution summary
+- Update `.ca/map.md` to reflect any new or modified files and their purposes
+- Update the "Last updated" date
+
+If `.ca/map.md` does not exist (e.g., new project that was empty before execution), create it now by running the equivalent of `/ca:map` — scan the project structure and write `.ca/map.md`.
+
+### 8. Auto-proceed to verification
+
+Check config for `auto_proceed_to_verify`.
+- If `true`: Tell the user execution is complete, then automatically execute `Skill(ca:verify)`.
+- If `false` or not set: Tell the user execution is complete. Suggest using `/clear` before verification to free up context, then tell the user to run `/ca:verify` (or `/ca:next`). Also mention: "Tip: You can set `auto_proceed_to_verify: true` in `/ca:settings` to auto-proceed."
+
+**Do NOT proceed to verification automatically, unless `auto_proceed_to_verify` is set to `true` in config.**

package/commands/ca/fix.md

@@ -0,0 +1,69 @@
+# /ca:fix — Roll Back to a Previous Step
+
+## Prerequisites
+
+Check `.ca/current/STATUS.md` exists. If not, tell the user to run `/ca:new` first and stop.
+
+## Behavior
+
+### 1. Show current state
+
+Read `.ca/current/STATUS.md` and display where the workflow currently is.
+
+### 2. Determine target step
+
+The user's message after `/ca:fix` may specify a step name. Valid steps:
+- `discuss` — go back to requirements discussion
+- `research` — go back to research
+- `plan` — go back to planning
+
+If no step is specified, show the options and ask the user where they want to go back to.
+
+### 3. Update STATUS.md
+
+Based on the target step, reset the status flags:
+
+- **Back to discuss**: Set `discuss_completed: false`, `research_completed: false`, `plan_completed: false`, `plan_confirmed: false`, `execute_completed: false`, `verify_completed: false`, `current_step: init`
+- **Back to research**: Set `research_completed: false`, `plan_completed: false`, `plan_confirmed: false`, `execute_completed: false`, `verify_completed: false`, `current_step: discuss`
+- **Back to plan**: Set `plan_completed: false`, `plan_confirmed: false`, `execute_completed: false`, `verify_completed: false`, `current_step: research` (or `discuss` if research wasn't done)
+
+### 4. Preserve files
+
+Do NOT delete any existing files in `.ca/current/`. They serve as reference for the user when revising.
+
+### 5. Update PLAN.md for fix mode (if rolling back to plan)
+
+If the target step is `plan` and `.ca/current/PLAN.md` exists:
+- Read the current PLAN.md and `.ca/current/SUMMARY.md` (if exists)
+- Based on the execution summary, mark completed implementation steps with `[x]` prefix
+- Mark steps that failed, need modification, or were not reached with `[ ]` prefix
+- Add a section at the end of PLAN.md:
+
+```
+## Fix Notes
+
+Rolled back to plan on YYYY-MM-DD.
+Steps marked [x] were completed before rollback.
+Steps marked [ ] need to be re-planned or modified.
+The planner should append/update fix steps below, NOT rewrite the entire plan.
+```
+
+### 6. Update CRITERIA.md for fix mode (if rolling back to plan)
+
+If `.ca/current/CRITERIA.md` exists:
+- Read the current CRITERIA.md
+- Keep all existing criteria entries intact
+- Add a note at the end:
+
+```
+## Fix Notes
+
+Rolled back on YYYY-MM-DD. All criteria above must still be verified after fix.
+New criteria for fix changes should be appended below this line.
+```
+
+### 7. Confirm
+
+Tell the user which step they've rolled back to and what command to run next.
+
+If rolled back to plan, also tell the user: "PLAN.md has been updated with completion markers. When `/ca:plan` runs, it will append/update steps rather than rewriting."

package/commands/ca/forget.md

@@ -0,0 +1,34 @@
+# /ca:forget — Remove from Persistent Context
+
+## Prerequisites
+
+No prerequisites — context files are checked on demand.
+
+## Behavior
+
+### 1. Ask target level
+
+Use `AskUserQuestion` with:
+- header: "Level"
+- question: "Remove from global or project context?"
+- options:
+  - "Project" — "Remove from .claude/rules/ca-context.md"
+  - "Global" — "Remove from ~/.claude/rules/ca-context.md"
+
+### 2. Read current context
+
+Based on the user's choice:
+- **Project**: Read `.claude/rules/ca-context.md` and display its contents.
+- **Global**: Read `~/.claude/rules/ca-context.md` and display its contents. If the file doesn't exist, tell the user there is no global context and stop.
+
+### 3. Identify what to remove
+
+The user's message after `/ca:forget` describes what to remove. Match it against existing entries.
+
+If the match is ambiguous, show the matching entries and ask the user to confirm which one(s) to remove.
+
+### 4. Remove and confirm
+
+Remove the matching entry/entries from the chosen context file and write the updated file.
+
+Tell the user what was removed and show the remaining context.

package/commands/ca/help.md

@@ -0,0 +1,62 @@
+# /ca:help — Command Reference
+
+Display all available CA commands in the user's preferred language:
+
+## Setup
+
+| Command | Description |
+|---------|-------------|
+| `/ca:settings` | Configure language settings (global or workspace) |
+
+## Workflow Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ca:new [description]` | Start a new requirement — creates `.ca/` directory, collects initial brief |
+| `/ca:quick [description]` | Quick workflow — skip discuss & research, go straight to plan |
+| `/ca:discuss` | Discuss requirements — ask clarifying questions, produce confirmed requirement summary |
+| `/ca:research` | Analyze codebase + external resources (optional step) |
+| `/ca:plan` | Propose implementation plan with **triple confirmation** |
+| `/ca:execute` | Execute the confirmed plan (uses ca-executor agent) |
+| `/ca:verify` | Self-check + user acceptance + git commit confirmation (uses ca-verifier agent) |
+| `/ca:next` | Auto-detect current step and execute the next one |
+
+## Context Management
+
+| Command | Description |
+|---------|-------------|
+| `/ca:remember <info>` | Save information to persistent context |
+| `/ca:context` | Display current persistent context |
+| `/ca:forget <info>` | Remove information from context |
+
+## Todo Management
+
+| Command | Description |
+|---------|-------------|
+| `/ca:todo <item>` | Add a todo item |
+| `/ca:todos` | List all todo items |
+
+## Navigation
+
+| Command | Description |
+|---------|-------------|
+| `/ca:status` | Show current workflow status |
+| `/ca:fix [step]` | Roll back to a previous step |
+| `/ca:map` | Scan project structure and generate/update `.ca/map.md` |
+| `/ca:help` | Show this reference |
+
+## Typical Workflow
+
+**Standard:**
+```
+/ca:new → /ca:discuss → /ca:research (optional) → /ca:plan → /ca:execute → /ca:verify
+```
+**Or use `/ca:next` repeatedly to auto-advance through each step.**
+
+**Quick:**
+```
+/ca:quick → /ca:plan → /ca:execute → /ca:verify
+```
+**Or use `/ca:next` repeatedly to auto-advance through each step.**
+
+Every step has a **mandatory confirmation point** — nothing proceeds without your explicit approval.

package/commands/ca/map.md

@@ -0,0 +1,46 @@
+# /ca:map — Scan Project Structure
+
+## Behavior
+
+### 1. Check existing map
+
+If `.ca/map.md` already exists, use `AskUserQuestion` with:
+- header: "Map"
+- question: "A codebase map already exists. What would you like to do?"
+- options:
+  - "Update" — "Refresh the existing map"
+  - "Regenerate" — "Regenerate from scratch"
+  - "Cancel" — "Keep the current map"
+
+If **Cancel**: Stop.
+
+### 2. Scan project structure
+
+Scan the project root directory:
+- List all top-level directories and files
+- For each significant directory, list its contents (1-2 levels deep)
+- Identify key files (entry points, configs, READMEs, etc.)
+- Skip `.git/`, `node_modules/`, `.ca/`, and other common ignored directories
+
+### 3. Analyze and generate map
+
+For each significant file/directory, write a brief description of its purpose. Generate `.ca/map.md` with:
+
+```
+# Codebase Map
+
+> Auto-generated by /ca:map. Last updated: YYYY-MM-DD
+
+## Project Overview
+<brief description of what this project does>
+
+## Directory Structure
+<tree-like structure with descriptions>
+
+## Key Files
+<list of important files with their purposes>
+```
+
+### 4. Confirm
+
+Tell the user the map has been generated/updated. Show a summary of what was mapped.

package/commands/ca/new.md

@@ -0,0 +1,109 @@
+# /ca:new — Start a New Requirement
+
+Read `~/.claude/ca/config.md` for global config, then read `.ca/config.md` for workspace config. Workspace values override global values. These are needed for runtime settings and to check if global config exists.
+
+## Behavior
+
+### 1. Check for global config
+
+If `~/.claude/ca/config.md` does not exist, **automatically run the settings flow inline**:
+- Ask the user for the three language settings (interaction_language, comment_language, code_language) using `AskUserQuestion`, one at a time.
+- Save to `~/.claude/ca/config.md` as global config.
+- Also generate `~/.claude/rules/ca-settings.md` with corresponding language rules.
+- Then continue with the steps below.
+
+### 2. Check for unfinished workflow
+
+If `.ca/current/STATUS.md` exists, check if `verify_completed` is `false`.
+
+If there is an unfinished workflow:
+- **Warn the user**: Tell them there is an unfinished workflow in `.ca/current/`.
+- Show what step it was on.
+- Use `AskUserQuestion` with:
+  - header: "Archive"
+  - question: "Do you want to archive the unfinished workflow and start fresh?"
+  - options:
+    - "Archive and start fresh" — "Move old files to history and start new"
+    - "Keep current" — "Continue the existing workflow"
+- If **Archive and start fresh**: Move all files from `.ca/current/` to `.ca/history/<next-number>-unfinished/`, then continue.
+- If **Keep current**: Stop. Tell the user to finish the current workflow first or use `/ca:fix` to go back.
+
+### 3. Create directory structure
+
+Create the following directories and files if they don't exist:
+
+```
+.ca/
+  todos.md
+  current/
+  history/
+```
+
+### 4. Collect initial requirement description and link to todo
+
+**If the user provided a description** with this command:
+1. Read `.ca/todos.md` and find all uncompleted todo items (under `# Todo List`, not in `# Archive`).
+2. Analyze the user's description and see if it matches any existing todo item.
+3. If a match is found, use `AskUserQuestion` with:
+   - header: "Link Todo"
+   - question: "I found a matching todo: <todo text>. Link this requirement to it?"
+   - options:
+     - "Yes, link" — "Link to this todo"
+     - "No, skip" — "Don't link"
+   - If **Yes, link**: Save the todo text for linking in step 5.
+   - If **No, skip**: Continue without linking.
+4. If no match is found, use `AskUserQuestion` with:
+   - header: "Add Todo"
+   - question: "This requirement doesn't match any existing todo. Add it as a new todo item?"
+   - options:
+     - "Yes, add" — "Add to todo list"
+     - "No, skip" — "Don't add"
+   - If **Yes, add**: Append to `.ca/todos.md` with format `- [ ] <user's description>` and `> Added: YYYY-MM-DD` (use today's date). Save the todo text for linking in step 5.
+   - If **No, skip**: Continue without linking.
+
+**If the user did NOT provide a description**:
+1. Read `.ca/todos.md` and find all uncompleted todo items.
+2. Analyze and present them to the user: **"Here are your current todos. Which one would you like to work on? (Or describe a new requirement)"**
+   - Show each uncompleted todo with a number.
+3. If the user selects a todo, use that as the requirement description and save it for linking in step 5.
+4. If the user provides a new description instead, use it and proceed to match/add logic as above.
+
+### 5. Write BRIEF.md
+
+Write `.ca/current/BRIEF.md` with:
+
+```markdown
+# Brief
+
+<user's description>
+
+linked_todo: <todo text if linked, otherwise omit this line>
+```
+
+**IMPORTANT**: The `linked_todo` value must be the **exact original text** from `todos.md`. Do NOT modify, abbreviate, rephrase, or summarize the todo text. Copy it verbatim.
+
+Include `linked_todo` only if a todo was linked in step 4.
+
+### 6. Initialize STATUS.md
+
+Write `.ca/current/STATUS.md` with:
+
+```markdown
+# Workflow Status
+
+workflow_type: standard
+current_step: new
+init_completed: true
+discuss_completed: false
+research_completed: false
+plan_completed: false
+plan_confirmed: false
+execute_completed: false
+verify_completed: false
+```
+
+### 7. Confirm completion
+
+Tell the user the new requirement has been created. Show the brief. Suggest proceeding with `/ca:discuss` (or `/ca:next`) to discuss and refine the requirements.
+
+**Do NOT proceed to discuss automatically. Wait for the user to invoke the next command.**

package/commands/ca/next.md

@@ -0,0 +1,36 @@
+# /ca:next — Execute Next Workflow Step
+
+Read `~/.claude/ca/config.md` for global config, then read `.ca/config.md` for workspace config. Workspace values override global values. These are needed for runtime settings (model_profile, auto_proceed_*, per-agent model overrides).
+
+## Prerequisites
+
+Check `.ca/current/STATUS.md` exists. If not, tell the user to run `/ca:new` first and stop.
+
+## Behavior
+
+### 1. Read current status
+
+Read `.ca/current/STATUS.md` and determine the current workflow state.
+
+### 2. Determine and execute next step
+
+Based on the status flags and `workflow_type`, determine the next step and execute it using the `Skill` tool:
+
+**For `workflow_type: standard`:**
+- If `init_completed: true` and `discuss_completed: false` → Execute `Skill(ca:discuss)`
+- If `discuss_completed: true` and `research_completed: false` → Execute `Skill(ca:research)`
+- If `research_completed: true` and `plan_completed: false` → Execute `Skill(ca:plan)`
+- If `plan_confirmed: true` and `execute_completed: false` → Execute `Skill(ca:execute)`
+- If `execute_completed: true` and `verify_completed: false` → Execute `Skill(ca:verify)`
+- If `verify_completed: true` → Tell the user the workflow is complete.
+
+**For `workflow_type: quick`:**
+- If `init_completed: true` and `plan_completed: false` → Execute `Skill(ca:plan)`
+- If `plan_confirmed: true` and `execute_completed: false` → Execute `Skill(ca:execute)`
+- If `execute_completed: true` and `verify_completed: false` → Execute `Skill(ca:verify)`
+- If `verify_completed: true` → Tell the user the workflow is complete.
+
+### 3. Edge cases
+
+- If no STATUS.md exists, tell the user to run `/ca:new` first.
+- If the workflow is in an inconsistent state (e.g., plan_completed but not plan_confirmed), tell the user and suggest running the appropriate command.