claude-agent

CA — Claude Agent

A user-controlled development workflow for Claude Code. Every step requires your explicit confirmation before proceeding.

Install

npx claude-agent

Or install from source:

git clone https://github.com/Seraphli/claude-agent.git
cd claude-agent
npm run install-ca

This syncs slash commands to ~/.claude/commands/ca/, agents to ~/.claude/agents/, scripts to ~/.claude/ca/scripts/, references to ~/.claude/ca/references/, and registers the statusline hook. Stale files removed from source are automatically cleaned up during install.

Uninstall

npx claude-agent --uninstall

Or from source:

npm run uninstall-ca

Removes commands, agents, and hooks from ~/.claude/. Project .ca/ directories and ~/.claude/ca/ config are preserved.

Workflow

Three workflow modes are available:

Full workflow — for requirements that need discussion:

/ca:new → /ca:discuss → /ca:plan → /ca:execute → /ca:verify → /ca:finish

Quick workflow — for clear, simple changes:

/ca:quick → /ca:plan → /ca:execute → /ca:verify → /ca:finish

Write workflow — for creative writing and document tasks:

/ca:write → /ca:discuss → /ca:plan → /ca:execute → /ca:verify → /ca:finish

Each workflow optionally creates a dedicated git branch (ca/<workflow-id>) for isolated development.

Use /ca:next at any point to automatically detect and run the next step.

Multi-workflow — plan multiple requirements, then batch execute:

/ca:new → /ca:discuss → /ca:plan   (repeat for each requirement)
/ca:switch                          (switch between workflows)
/ca:batch                           (batch execute all confirmed plans)

Branch Management

When use_branches is enabled (default), each workflow operates on a dedicated branch:

• Branch creation — /ca:new or /ca:quick creates a ca/<workflow-id> branch from the current base branch
• Auto-commit — after execution, changes are automatically committed to the workflow branch
• Finish — /ca:finish squash-merges (or regular merge, based on merge_strategy) the workflow branch back to the base branch
• Cleanup — the workflow branch is automatically deleted after merge when auto_delete_branch is true (default)

This keeps your main branch clean and gives each requirement its own isolated history.

1. New Requirement — /ca:new [description]

Creates a workflow in .ca/workflows/<id>/. If an unfinished workflow exists, offers to keep it alongside the new one, archive it, or continue it. Collects an initial requirement brief. On first run, auto-configures language settings if no global config exists.

2. Discuss — /ca:discuss

Starts with adaptive research using parallel researcher agents, then performs a systematic dimension scan (10 dimensions for standard, 6 for write workflows) to identify gaps, and clarifies requirements through focused Q&A (one question at a time). Produces a requirement summary that you must confirm before moving on.

3. Plan — /ca:plan

For quick workflows, assesses requirement complexity — simple requirements can skip research, complex ones get automated research. Clarifies any uncertain items before drafting. Proposes an implementation plan with triple confirmation and backtracking:

• Requirement understanding — "I understand you want X, correct?"
• Approach and method — "I'll modify these files using this approach, agreed?"
• Expected results — "The end result will be X, is that what you want?"

If changes at a later step affect earlier confirmations, the system backtracks and re-confirms affected steps. Success criteria are tagged [auto] or [manual] for verification.

4. Execute — /ca:execute

Runs the confirmed plan using isolated executor agents. Implementation steps use ordered/unordered list structure to express execution order — ordered items run sequentially, unordered items run in parallel. Only proceeds if the plan has been triple-confirmed. Returns an execution summary. When branch management is enabled, changes are auto-committed to the workflow branch after execution.

5. Verify — /ca:verify

Auto criteria are verified by independent verifier agents (optionally in parallel). If auto verification fails and auto_fix is enabled, the system assesses whether failures are implementation bugs or approach issues. Implementation bugs trigger an automatic plan→execute→verify loop (up to max_fix_rounds times) without user interaction. Approach/plan issues require manual intervention. In batch mode, verification runs fully automated — skips manual criteria, user acceptance, and gitignore check; auto-commits on success; fails immediately without retry on failure. Manual criteria are confirmed with you one at a time. After all criteria pass, proceed to /ca:finish.

6. Finish — /ca:finish

Merges the workflow branch back to the base branch and cleans up. When use_branches is enabled, squash-merges (or regular merge based on merge_strategy) the ca/<workflow-id> branch into the base branch, then deletes the workflow branch if auto_delete_branch is true.

Quick Mode — /ca:quick [description]

Skips the discuss phase. Creates a brief and goes straight to planning. Research directions are based on 6 quick dimensions; simple requirements can skip research. Best for small, well-understood changes.

Other Commands

Command	Description
/ca:quick [desc]	Start a quick workflow (skip discuss)
/ca:write [desc]	Start a writing workflow (writing-specific dimensions)
/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:switch	Switch active workflow
/ca:list	List all workflows with status summary
/ca:batch	Batch execute all plan-confirmed workflows
/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:errors	Show and manage error lessons
/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 in discuss, go straight to plan
auto_proceed_to_verify	Skip manual verify trigger after execution
max_concurrency	Max parallel agents in execute/verify (default: 4)
track_ca_files	Version control for CA files: none (default), all, .ca/, or .claude/rules/ca*
use_branches	Git branch per workflow: true (default) or false
merge_strategy	How to merge workflow branch at finish: squash (default) or merge
auto_delete_branch	Auto-delete workflow branch after merge: true (default) or false
auto_fix	Auto-fix loop on verify failure: true or false (default)
max_fix_rounds	Maximum auto-fix retry rounds (default: 3)

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, concurrency, auto-proceed)
    version                      # Installed version number
    scripts/                     # Node.js scripts for deterministic operations
    references/                  # Reference files (model-profiles.md, etc.)
  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                       # Active todo items (uncompleted)
  todos-archive.md               # Archived todo items (completed/cancelled)
  map.md                         # Codebase structure map (/ca:map)
  active.md                      # Currently active workflow ID
  workflows/
    <workflow-id>/
      STATUS.md                  # Workflow state
      BRIEF.md                   # Initial requirement brief
      REQUIREMENT.md             # Finalized requirement from /ca:discuss
      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 (parallel for independent steps)	Code edits cause context bloat
ca-verifier	Independent verification (supports auto/manual, parallel mode)	Fresh context avoids confirmation bias

Statusline

CA installs a status bar hook that displays:

• Current model name
• "ca" + version number
• Context window usage bar

Testing

Prerequisites

• tmux — used to run Claude in a detached terminal session
• claude CLI — must support --model and --dangerously-skip-permissions flags
• jq — used for JSON parsing in helper scripts
• node — used for CA install and status scripts

Run all tests

npm test

Run a single phase

npm run test:phase -- 1

Replace 1 with 2 or 3 to run a specific phase.

Test architecture

Tests are organized into three phases under tests/phases/:

Phase	Script	Description
1	phase1_quick.sh	Quick workflow: /ca:quick → /ca:plan → /ca:execute → /ca:verify → /ca:finish
2	phase2_standard.sh	Standard workflow: /ca:new → /ca:discuss → /ca:plan → /ca:execute → /ca:verify → /ca:finish
3	phase3_helpers.sh	Helper commands: /ca:todo, /ca:todos, /ca:map, /ca:status, /ca:list

Shared infrastructure lives in tests/e2e_common.sh (setup, tmux helpers, assertions, result recording). Each phase runs in a fully isolated temp directory with its own HOME override so tests never affect your real Claude config.

License

MIT