claude-agent 1.2.0

package/README.md

@@ -0,0 +1,171 @@
+# CA — Claude Agent
+
+A user-controlled development workflow for Claude Code. Every step requires your explicit confirmation before proceeding.
+
+## Install
+
+```bash
+cd claude-agent
+npm run install-ca
+```
+
+This copies slash commands to `~/.claude/commands/ca/`, agents to `~/.claude/agents/`, and registers the statusline hook.
+
+## Uninstall
+
+```bash
+npm run uninstall-ca
+```
+
+Removes commands, agents, and hooks from `~/.claude/`. Project `.ca/` directories and `~/.claude/ca/` config are preserved.
+
+## Workflow
+
+Two workflow modes are available:
+
+**Full workflow** — for requirements that need discussion and research:
+
+```
+/ca:new → /ca:discuss → /ca:research → /ca:plan → /ca:execute → /ca:verify
+```
+
+**Quick workflow** — for clear, simple changes:
+
+```
+/ca:quick → /ca:plan → /ca:execute → /ca:verify
+```
+
+Use `/ca:next` at any point to automatically detect and run the next step.
+
+### 1. New Requirement — `/ca:new [description]`
+
+Creates a `.ca/` directory in your project for workflow state. Collects an initial requirement brief. On first run, auto-configures language settings if no global config exists. Warns if there is an unfinished workflow.
+
+### 2. Discuss — `/ca:discuss`
+
+Clarifies your requirements through focused Q&A (one question at a time), starting from the brief collected in `/ca:new`. Produces a requirement summary that you must confirm before moving on.
+
+### 3. Research — `/ca:research` (optional)
+
+Analyzes the codebase and optionally searches external resources. Uses an isolated agent to keep the main conversation clean. Findings require your confirmation.
+
+### 4. Plan — `/ca:plan`
+
+Proposes an implementation plan with **triple confirmation**:
+
+1. **Requirement understanding** — "I understand you want X, correct?"
+2. **Approach and method** — "I'll modify these files using this approach, agreed?"
+3. **Expected results** — "The end result will be X, is that what you want?"
+
+All three must pass before the plan is finalized.
+
+### 5. Execute — `/ca:execute`
+
+Runs the confirmed plan using an isolated executor agent. Only proceeds if the plan has been triple-confirmed. Returns an execution summary.
+
+### 6. Verify — `/ca:verify`
+
+An independent verifier agent checks every success criterion in a fresh context. After your acceptance, optionally creates a git commit (message confirmed by you). Archives the workflow cycle to `.ca/history/`.
+
+### Quick Mode — `/ca:quick [description]`
+
+Skips the discuss and research phases entirely. Creates a brief and goes straight to planning. Best for small, well-understood changes.
+
+## Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `/ca:quick [desc]` | Start a quick workflow (skip discuss/research) |
+| `/ca:next` | Auto-detect and run the next workflow step |
+| `/ca:map` | Scan and record project structure |
+| `/ca:settings` | Configure language, model, and auto-proceed settings |
+| `/ca:status` | Show current workflow state |
+| `/ca:fix [step]` | Roll back to a previous step |
+| `/ca:remember <info>` | Save to persistent context (project or global) |
+| `/ca:context` | Show loaded context in current session |
+| `/ca:forget <info>` | Remove from persistent context |
+| `/ca:todo <item>` | Add a todo item |
+| `/ca:todos` | List all todos |
+| `/ca:help` | Show command reference |
+
+## Configuration
+
+CA uses a dual-layer configuration system:
+
+- **Global** (`~/.claude/ca/config.md`) — applies to all projects
+- **Workspace** (`.ca/config.md`) — applies to current project, overrides global
+
+Three language settings:
+
+| Setting | Purpose |
+|---------|---------|
+| `interaction_language` | Language for conversations |
+| `comment_language` | Language for code comments |
+| `code_language` | Language for code strings (logs, errors, etc.) |
+
+Additional settings:
+
+| Setting | Purpose |
+|---------|---------|
+| `model_profile` | Agent model tier: `quality`, `balanced` (default), or `budget` |
+| `auto_proceed_to_plan` | Skip research confirmation, go straight to plan |
+| `auto_proceed_to_verify` | Skip manual verify trigger after execution |
+
+Per-agent model overrides (e.g., `ca-verifier_model: opus`) are also supported.
+
+Use `/ca:settings` to configure.
+
+## Project Structure
+
+```
+~/.claude/
+  ca/
+    config.md                    # Global config (language, model, auto-proceed)
+    version                      # Installed version number
+  commands/ca/                   # Slash commands (installed by install-ca)
+  agents/                        # Agent definitions (installed by install-ca)
+  rules/
+    ca-rules.md                  # Shared rules (auto-loaded)
+    ca-settings.md               # Global language settings (auto-loaded)
+    ca-context.md                # Global persistent context (auto-loaded)
+    ca-errors.md                 # Global error lessons (auto-loaded)
+
+.ca/                             # Created per-project by /ca:new or /ca:quick
+  config.md                      # Workspace config (overrides global)
+  todos.md                       # Todo list with archive
+  map.md                         # Codebase structure map (/ca:map)
+  current/
+    STATUS.md                    # Workflow state
+    BRIEF.md                     # Initial requirement brief
+    REQUIREMENT.md               # Finalized requirement from /ca:discuss
+    RESEARCH.md                  # Findings from /ca:research
+    PLAN.md                      # Confirmed plan from /ca:plan
+    SUMMARY.md                   # Execution summary from /ca:execute
+    CRITERIA.md                  # Success criteria from /ca:plan
+  history/
+    0001-feature-slug/           # Archived workflow cycles
+
+.claude/rules/                   # Project-level rules (auto-loaded)
+  ca-settings.md                 # Project language settings
+  ca-context.md                  # Project persistent context
+  ca-errors.md                   # Project error lessons
+```
+
+## Agents
+
+| Agent | Role | Why isolated |
+|-------|------|-------------|
+| `ca-researcher` | Deep codebase analysis | Research consumes large context |
+| `ca-executor` | Implements the plan | Code edits cause context bloat |
+| `ca-verifier` | Independent verification | Fresh context avoids confirmation bias |
+
+## Statusline
+
+CA installs a status bar hook that displays:
+- Current model name
+- "ca" + version number
+- Context window usage bar
+
+## License
+
+MIT

package/agents/ca-executor.md

@@ -0,0 +1,75 @@
+---
+name: ca-executor
+description: Execution agent that implements changes according to the confirmed plan
+tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+model: inherit
+---
+
+# CA Executor Agent
+
+You are an execution agent for the CA development workflow. Your job is to **implement exactly what the plan says**, step by step. You do NOT deviate from the plan or make independent design decisions.
+
+## Input
+
+You will receive:
+- The content of PLAN.md (the confirmed implementation plan)
+- The content of REQUIREMENT.md (the original requirement)
+- The content of context.md (persistent project context, if any)
+- The project root path
+
+## Your Task
+
+### 1. Execute each step in PLAN.md
+
+Go through the implementation steps in order. For each step:
+- Read any files you need to understand before modifying
+- Make the changes as specified
+- Verify the change was applied correctly
+
+### 2. Track what you did
+
+Keep a running log of:
+- Each file modified and what changed
+- Each file created and why
+- Any deviations from the plan (with explanation)
+
+### 3. Output Format
+
+When done, return your summary in this exact structure:
+
+```
+## Execution Summary
+
+### Changes Made
+- <file_path> — <what changed>
+
+### Files Created
+- <file_path> — <purpose>
+
+### Steps Completed
+1. <step> — Done
+2. <step> — Done
+
+### Deviations from Plan
+- <deviation and reason> (or "None")
+
+### Notes
+- <anything the user should know>
+```
+
+## Rules
+
+- Follow PLAN.md **exactly**. Do not add features, refactor unrelated code, or make "improvements" beyond the plan.
+- If a step is unclear or seems wrong, record it as a deviation note rather than guessing.
+- Do not run tests unless the plan explicitly says to.
+- Do not commit anything. The verify step handles that.
+- All imports must be at the top of files.
+- Write code comments in the language specified by `comment_language` in the config (default: English).
+- Write code strings (logs, error messages, etc.) in the language specified by `code_language` in the config (default: English).
+- Keep code compact and concise — no unnecessary abstractions.

package/agents/ca-researcher.md

@@ -0,0 +1,69 @@
+---
+name: ca-researcher
+description: Research agent that gathers facts about the codebase and external resources
+tools:
+  - Read
+  - Glob
+  - Grep
+  - WebFetch
+  - WebSearch
+model: inherit
+---
+
+# CA Researcher Agent
+
+You are a research agent for the CA development workflow. Your job is to **gather facts** about the codebase and external resources relevant to a requirement. You do NOT propose solutions or make implementation decisions.
+
+## Input
+
+You will receive:
+- The content of REQUIREMENT.md (what the user wants)
+- The project root path
+- Optional research scope instructions from the user
+
+## Your Task
+
+### 1. Codebase Analysis
+
+Use Glob and Grep to find files relevant to the requirement:
+- Identify files that will likely need modification
+- Find existing patterns, conventions, and architecture
+- Locate related tests, configs, and dependencies
+- Note any constraints (version requirements, API contracts, etc.)
+
+### 2. External Resources (if requested)
+
+If the user asked for external research:
+- Search for relevant documentation
+- Find API references, library docs, or best practices
+- Summarize findings concisely
+
+### 3. Output Format
+
+Return your findings in this exact structure:
+
+```
+## Research Findings
+
+### Relevant Files
+- <file_path> — <why it's relevant>
+
+### Code Patterns
+- <pattern description>
+
+### Constraints and Dependencies
+- <constraint>
+
+### External Resources
+- <resource> — <key finding>
+
+### Key Observations
+- <anything notable that could affect implementation>
+```
+
+## Rules
+
+- Only report facts. Do NOT suggest approaches or implementations.
+- Be thorough but concise. List the most important findings first.
+- If you find potential issues or conflicts, report them as observations.
+- Read file contents when needed to understand structure, don't just list filenames.

package/agents/ca-verifier.md

@@ -0,0 +1,80 @@
+---
+name: ca-verifier
+description: Verification agent that independently checks implementation against requirements
+tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+model: inherit
+---
+
+# CA Verifier Agent
+
+You are a verification agent for the CA development workflow. Your job is to **independently check** whether the implementation meets the requirements and plan. You operate in a fresh context to avoid confirmation bias.
+
+## Input
+
+You will receive:
+- The content of REQUIREMENT.md (what was requested)
+- The content of PLAN.md (what was planned)
+- The content of SUMMARY.md (what was executed)
+- The project root path
+
+## Your Task
+
+### 1. Check each success criterion
+
+Read the success criteria from REQUIREMENT.md. For each one:
+- Verify it's actually met by reading the relevant code/files
+- Record the evidence (what you found)
+- Mark as PASS or FAIL
+
+### 2. Check plan compliance
+
+Compare SUMMARY.md against PLAN.md:
+- Were all planned steps executed?
+- Were there unexpected deviations?
+- Are the expected results achieved?
+
+### 3. Basic quality checks
+
+- Do modified files have syntax errors? (Run linters/interpreters if available)
+- Are there obvious bugs or issues?
+- Do imports look correct?
+
+### 4. Output Format
+
+Return your report in this exact structure:
+
+```
+## Verification Report
+
+### Success Criteria
+| # | Criterion | Status | Evidence |
+|---|-----------|--------|----------|
+| 1 | <criterion> | PASS/FAIL | <what you found> |
+
+### Plan Compliance
+| # | Planned Step | Status | Notes |
+|---|-------------|--------|-------|
+| 1 | <step> | DONE/MISSING/DEVIATED | <notes> |
+
+### Quality Checks
+- Syntax: PASS/FAIL
+- Imports: PASS/FAIL
+- Obvious issues: <list or "None">
+
+### Overall: PASS/FAIL
+
+### Recommendations (if any)
+- <recommendation>
+```
+
+## Rules
+
+- Be objective and thorough. Your purpose is to catch issues before the user accepts the work.
+- Do NOT modify any files. You are read-only.
+- Do NOT fix issues. Report them so the user can decide what to do.
+- Check actual file contents, don't just trust SUMMARY.md claims.
+- If you can run tests (e.g., `npm test`, `pytest`), do so and report results.

package/bin/install.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const homeDir = require("os").homedir();
+const srcDir = path.resolve(__dirname, "..");
+const targetCommandsDir = path.join(homeDir, ".claude", "commands", "ca");
+const targetAgentsDir = path.join(homeDir, ".claude", "agents");
+const targetHooksDir = path.join(homeDir, ".claude", "hooks");
+const caConfigDir = path.join(homeDir, ".claude", "ca");
+const settingsPath = path.join(homeDir, ".claude", "settings.json");
+
+const pkg = JSON.parse(fs.readFileSync(path.join(srcDir, "package.json"), "utf8"));
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+const banner = '\n' +
+  cyan + '   ██████╗ █████╗\n' +
+  '  ██╔════╝██╔══██╗\n' +
+  '  ██║     ███████║\n' +
+  '  ██║     ██╔══██║\n' +
+  '  ╚██████╗██║  ██║\n' +
+  '   ╚═════╝╚═╝  ╚═╝' + reset + '\n\n' +
+  '  Claude Agent ' + dim + 'v' + pkg.version + reset + '\n';
+
+console.log(banner);
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    const srcPath = path.join(src, entry);
+    const destPath = path.join(dest, entry);
+    if (fs.statSync(srcPath).isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function copyAgents(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    if (entry.startsWith("ca-") && entry.endsWith(".md")) {
+      fs.copyFileSync(path.join(src, entry), path.join(dest, entry));
+    }
+  }
+}
+
+function generateSettingsRules(configContent) {
+  const lines = configContent.split("\n");
+  const rules = ["# CA Settings Rules\n"];
+  for (const line of lines) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (key === "interaction_language") {
+      rules.push(`- Always communicate in ${value}`);
+    } else if (key === "comment_language") {
+      rules.push(`- Write all code comments in ${value}`);
+    } else if (key === "code_language") {
+      rules.push(`- Use ${value} for code strings (logs, error messages, etc.)`);
+    }
+  }
+  return rules.join("\n") + "\n";
+}
+
+// Copy commands
+const srcCommandsDir = path.join(srcDir, "commands", "ca");
+copyDir(srcCommandsDir, targetCommandsDir);
+const commandCount = fs.readdirSync(targetCommandsDir).filter((f) => f.endsWith(".md")).length;
+console.log(`  ${green}✓${reset} Installed ${commandCount} commands`);
+
+// Copy agents
+const srcAgentsDir = path.join(srcDir, "agents");
+copyAgents(srcAgentsDir, targetAgentsDir);
+const agentFiles = fs.readdirSync(srcAgentsDir).filter((f) => f.startsWith("ca-") && f.endsWith(".md"));
+console.log(`  ${green}✓${reset} Installed ${agentFiles.length} agents`);
+
+// Copy hooks
+const srcHooksDir = path.join(srcDir, "hooks");
+fs.mkdirSync(targetHooksDir, { recursive: true });
+const hookFile = "ca-statusline.js";
+fs.copyFileSync(path.join(srcHooksDir, hookFile), path.join(targetHooksDir, hookFile));
+console.log(`  ${green}✓${reset} Installed statusline hook`);
+
+// Create global config directory
+fs.mkdirSync(caConfigDir, { recursive: true });
+console.log(`  ${green}✓${reset} Created config directory`);
+
+// Create rules directory and install rules files
+const rulesDir = path.join(homeDir, ".claude", "rules");
+fs.mkdirSync(rulesDir, { recursive: true });
+
+// Copy _rules.md as ca-rules.md
+const rulesSource = path.join(srcCommandsDir, "_rules.md");
+const rulesTarget = path.join(rulesDir, "ca-rules.md");
+fs.copyFileSync(rulesSource, rulesTarget);
+console.log(`  ${green}✓${reset} Installed rules`);
+
+// Generate ca-settings.md from existing config
+const globalConfigPath = path.join(caConfigDir, "config.md");
+if (fs.existsSync(globalConfigPath)) {
+  const configContent = fs.readFileSync(globalConfigPath, "utf8");
+  const settingsRules = generateSettingsRules(configContent);
+  fs.writeFileSync(path.join(rulesDir, "ca-settings.md"), settingsRules);
+  console.log(`  ${green}✓${reset} Generated settings from config`);
+}
+
+// Migrate old context.md to rules if exists
+const oldGlobalContext = path.join(caConfigDir, "context.md");
+const newGlobalContext = path.join(rulesDir, "ca-context.md");
+if (fs.existsSync(oldGlobalContext) && !fs.existsSync(newGlobalContext)) {
+  fs.copyFileSync(oldGlobalContext, newGlobalContext);
+  console.log(`  ${green}✓${reset} Migrated context to rules`);
+}
+
+// Migrate old errors.md to rules if exists
+const oldGlobalErrors = path.join(caConfigDir, "errors.md");
+const newGlobalErrors = path.join(rulesDir, "ca-errors.md");
+if (fs.existsSync(oldGlobalErrors) && !fs.existsSync(newGlobalErrors)) {
+  fs.copyFileSync(oldGlobalErrors, newGlobalErrors);
+  console.log(`  ${green}✓${reset} Migrated errors to rules`);
+}
+
+// Write version file
+fs.writeFileSync(path.join(caConfigDir, "version"), pkg.version);
+console.log(`  ${green}✓${reset} Wrote version (${pkg.version})`);
+
+// Register statusline in settings.json
+let settings = {};
+if (fs.existsSync(settingsPath)) {
+  settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+}
+const hookPath = path.join(targetHooksDir, hookFile);
+settings.statusLine = { type: "command", command: `node "${hookPath}"` };
+
+// Add Read permissions for CA config files
+if (!settings.permissions) settings.permissions = {};
+if (!Array.isArray(settings.permissions.allow)) settings.permissions.allow = [];
+const readPermissions = [
+  "Read(.ca/*)",
+  "Read(.ca/**/*)",
+  "Read(~/.claude/ca/*)"
+];
+for (const perm of readPermissions) {
+  if (!settings.permissions.allow.includes(perm)) {
+    settings.permissions.allow.push(perm);
+  }
+}
+
+fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+console.log(`  ${green}✓${reset} Configured statusline`);
+console.log(`  ${green}✓${reset} Added Read permissions`);
+
+console.log(`\n  ${green}Done!${reset} Launch Claude Code and run ${cyan}/ca:help${reset}.\n`);

package/bin/uninstall.js

@@ -0,0 +1,67 @@
+const fs = require("fs");
+const path = require("path");
+
+const homeDir = require("os").homedir();
+const targetCommandsDir = path.join(homeDir, ".claude", "commands", "ca");
+const targetAgentsDir = path.join(homeDir, ".claude", "agents");
+const targetHooksDir = path.join(homeDir, ".claude", "hooks");
+const settingsPath = path.join(homeDir, ".claude", "settings.json");
+
+// Remove commands directory
+if (fs.existsSync(targetCommandsDir)) {
+  fs.rmSync(targetCommandsDir, { recursive: true });
+  console.log(`Removed ${targetCommandsDir}`);
+} else {
+  console.log("Commands directory not found, skipping.");
+}
+
+// Remove agent files
+if (fs.existsSync(targetAgentsDir)) {
+  let removed = 0;
+  for (const entry of fs.readdirSync(targetAgentsDir)) {
+    if (entry.startsWith("ca-") && entry.endsWith(".md")) {
+      fs.unlinkSync(path.join(targetAgentsDir, entry));
+      removed++;
+    }
+  }
+  console.log(`Removed ${removed} agent files from ${targetAgentsDir}`);
+} else {
+  console.log("Agents directory not found, skipping.");
+}
+
+// Remove hook file
+const hookFile = path.join(targetHooksDir, "ca-statusline.js");
+if (fs.existsSync(hookFile)) {
+  fs.unlinkSync(hookFile);
+  console.log(`Removed ${hookFile}`);
+} else {
+  console.log("Hook file not found, skipping.");
+}
+
+// Deregister statusline from settings.json
+if (fs.existsSync(settingsPath)) {
+  const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  if (settings.statusLine?.command?.includes("ca-statusline")) {
+    delete settings.statusLine;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("Removed statusline from settings.json");
+  }
+}
+
+// Remove all CA rules files
+const rulesDir = path.join(homeDir, ".claude", "rules");
+if (fs.existsSync(rulesDir)) {
+  let removedRules = 0;
+  for (const entry of fs.readdirSync(rulesDir)) {
+    if (entry.startsWith("ca-") && entry.endsWith(".md")) {
+      fs.unlinkSync(path.join(rulesDir, entry));
+      removedRules++;
+    }
+  }
+  if (removedRules > 0) {
+    console.log(`Removed ${removedRules} CA rules files from ${rulesDir}`);
+  }
+}
+
+console.log("\nCA uninstalled successfully!");
+console.log("Note: .ca/ directories and ~/.claude/ca/ config are preserved. CA rules files have been removed.");

package/commands/ca/_rules.md

@@ -0,0 +1,40 @@
+# CA Command Rules
+
+## UI Rule
+
+Before calling `AskUserQuestion`, always output structured content first (summary, list, checkpoint, etc.) so the user has sufficient context visible above the option picker.
+
+In the message immediately before an `AskUserQuestion` call, always end with a horizontal rule (`---`) as the last line. This prevents the option picker from obscuring the last visible line of content.
+
+## Discussion Completeness Rule
+
+When asking clarifying questions one at a time during the discuss phase:
+- If the user indicates they don't understand the question, you MUST explain or rephrase the current question first before moving on.
+- Do NOT skip to the next question when the user's response shows confusion, disagreement, or a request for clarification about the current question.
+- Only proceed to the next question after the current one is clearly resolved.
+
+## Error Recording Rule
+
+When an agent makes a mistake during execution (wrong file, logic error, repeated mistake, etc.), it must record the error:
+- **Project-level**: Append to `.claude/rules/ca-errors.md` for project-specific lessons.
+- **Global-level**: Append to `~/.claude/rules/ca-errors.md` for cross-project lessons.
+
+Format each entry as:
+```
+- [YYYY-MM-DD] <brief description of the error and what was learned>
+```
+
+## Todo Independence Rule
+
+Users may invoke `/ca:todo` at any point during a workflow (discuss, research, plan, execute, verify). When this happens:
+- Treat it as an independent command — process the todo addition, then resume the current workflow where you left off.
+- Do NOT incorporate the todo content into the current requirement, plan, or discussion.
+- Do NOT let the todo interrupt or alter the ongoing workflow state.
+
+## Map-First File Lookup Rule
+
+When searching for project-related files, agents must follow this priority:
+1. **First**, check `.ca/map.md` (if it exists) for the file location or relevant section.
+2. **Only if** the map does not contain the needed information, fall back to Glob/Grep search.
+
+This reduces unnecessary searches and ensures agents leverage the existing codebase map.