From 59b0caa13141730642d463fa608e94c974e6aa46 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 23 Aug 2026 06:51:40 +0000 Subject: [PATCH] chore: re-run claude-code-optimizer (v1.24.0 -> v1.28.6) - CLAUDE.md: add Caveman Mode section (default full) and orchestrator-default Subagents section with role roster; update footer marker - offload full Autonomy wording to agent_docs/autonomy.md, consolidate restated MCP/trigger paragraphs onto agent_docs/mcp_catalog.md pointers - align agent_docs/modes.md and agent_docs/review_process.md with the new caveman/orca defaults; update orca skill to the default-mode contract - .claude/loop.md: complete the verification chain (install + build) --- .claude/loop.md | 5 +- .claude/skills/orca/SKILL.md | 70 +++++++++++++---------- CLAUDE.md | 106 +++++++++++++++++++---------------- agent_docs/autonomy.md | 9 +++ agent_docs/modes.md | 21 ++++--- agent_docs/review_process.md | 25 ++++----- 6 files changed, 134 insertions(+), 102 deletions(-) create mode 100644 agent_docs/autonomy.md diff --git a/.claude/loop.md b/.claude/loop.md index 7bd44e2c..d48a835a 100644 --- a/.claude/loop.md +++ b/.claude/loop.md @@ -7,8 +7,9 @@ nothing is pending, say so in one line and do not invent work. 2. **This branch's pull request** — new review comments, a failed CI run, or a merge conflict. Red build → `.claude/skills/ci/SKILL.md`. Comments and merge state → `.claude/skills/pr/SKILL.md`. Address them; do not just describe them. -3. **Verification** — `npm run format:check`, `npm run lint`, `npx tsc --noEmit`, `npm test`. Anything red is the work - for this iteration. +3. **Verification** — the project's chain in its stated order: `npm install`, `npm run format:check`, `npm run lint`, + `npx tsc --noEmit`, `npm test`, `npm run build` (install matters on a fresh clone, which is what a cloud or routine + session always is). Anything red is the work for this iteration. 4. **Backlog** — the top item in `BACKLOG.md` if it is small and self-contained. Anything larger stays where it is. Rules for every iteration: diff --git a/.claude/skills/orca/SKILL.md b/.claude/skills/orca/SKILL.md index 417d637f..b16f1232 100644 --- a/.claude/skills/orca/SKILL.md +++ b/.claude/skills/orca/SKILL.md @@ -1,6 +1,6 @@ --- name: orca -description: "Orchestrator mode, toggled with '/orca' — also 'orca mode', 'orchestrator mode', 'orca an/aus', 'delegate everything from now on'. While ON the main agent does no task work itself: every unit goes to subagents that inherit its model and effort, at most N in parallel (default 5). '/orca off' restores normal behavior. Load it when the user toggles the mode or asks for its state, and at session start when SCRATCHPAD.md still marks the mode ON." +description: "Orchestrator mode — the default working mode of this project, not a toggle to find. The main agent does no task work itself: every unit goes to a role-framed subagent that inherits its model and effort, at most 5 in parallel unless overridden. Load it for the contract (roles, width, write scopes, verification), when the user says '/orca', 'orca mode', 'orchestrator mode', 'orca an/aus', 'delegate everything', or asks what the width is set to. '/orca off' drops to plain behavior for this session only." argument-hint: "[on|off|N|status]" --- @@ -8,53 +8,61 @@ argument-hint: "[on|off|N|status]" ## When to Use -- `/orca` · `/orca on|off|status` · `/orca 10` — the user toggles the mode or asks what it is set to +- `/orca` (reports state and width) · `/orca on|off|status` · `/orca 10` — the user asks what the mode is set to, or changes it - "orca mode", "orchestrator mode", "orca an/aus", "ab jetzt alles delegieren", "delegate everything" - Session start, when `SCRATCHPAD.md` still carries an Orca line from an earlier session or from before a compaction -Not this skill: a one-off "use a subagent for this". That is the normal delegation table in -`agent_docs/review_process.md → Subagent Delegation`. +Not this skill: choosing a `subagent_type` for one assignment while already orchestrating. That is the type/role +table in `CLAUDE.md → Subagents`, with the longer form in `agent_docs/review_process.md → Subagent Delegation`. -## Toggle +## State -| Argument | Effect | -| ----------------------------------------- | -------------------------------------------------------------------- | -| _(none)_ | Flip the current state — off → on at the last width (5 if never set), on → off | -| `on` / `off` | Set explicitly | -| `N` — any number (`/orca 10`, `/orca 2`) | On, with at most N subagents running at once | -| `status` | Report state + width, change nothing | +**On by default, width 5.** Every session starts orchestrating; there is no activation step. The width is the only +number to think about, and only if the default is wrong for the task. -**Default is off.** Until someone types `/orca`, this file changes nothing about how the session works. Switching on -or off is confirmed in one line — state, width, and what it means for the next turn. +| Argument | Effect | +|----------|--------| +| *(none)* | Report state and width, change nothing — same as `status` | +| `N` — any number (`/orca 10`, `/orca 2`) | Set the parallel width for this session | +| `off` | Plain Claude Code behavior for the rest of **this** session | +| `on` | Back to orchestrating, at the last width set (5 if never set) | +| `status` | Report state and width, change nothing | -**State** lives in `SCRATCHPAD.md` → _Current Work_ as one line — `**Orca mode** — ON, max parallel ()` — -because a mode that only exists in context silently disappears at the next compaction. Switching off removes the -line. A line left over from an earlier session is _state, not authority_: say in one sentence that the mode is still -on, then work in it — the user has `/orca off`. +**Off is a command, never a default.** The next session orchestrates again, because nothing carries `off` forward — +not this file, not CLAUDE.md, not `SCRATCHPAD.md`. Only a non-default *width* is worth persisting: write it to +`SCRATCHPAD.md` → *Current Work* as `**Orca** — width ()` so a compaction cannot lose it. **A line there is +authority, not staleness** — obey it and say in one sentence that the width came from the scratchpad; the user has +`/orca 5` if it is wrong. No line means width 5. (Correcting the line to the default instead would throw away the one +thing it exists to protect: a same-day compaction and a same-day earlier session are indistinguishable from the date.) -## The contract while ON +## The contract 1. **Every unit of task work is delegated. No exception.** Reading a file for its content, searching, planning, editing, writing tests, running checks, reviewing — all of it happens in a subagent, including the units that would plainly be faster done directly. "Too small to delegate" is not a judgment this mode makes; `/orca off` is. -2. **The orchestrator keeps four things,** and all four are decisions rather than work: decomposition and assignment · +2. **Each assignment names a role, from the roster in CLAUDE.md → *Subagents*.** The role is the lens the brief + frames — `architect`, `implementer`, `reviewer`, `domain`, `product`, `docs`, `security` — and the wave report + names it. Seat the roles the change actually calls for, never a standing panel and never two agents with the same + lens: agreement between identical lenses is not evidence. **A code change always seats `reviewer`, and never the + agent that wrote it** — a fresh reading beats an author verifying the intent it already holds. +3. **The orchestrator keeps four things,** and all four are decisions rather than work: decomposition and assignment · read-only verification of what comes back (`git status`, `git diff`, reading the changed files) · integration and its gates (commit, push, `/pr`, `/ci`, `/rollback`, merge, deploy) · the report to the user. A gate handed to a subagent is a gate that answers itself — the subagent holds the tool and has nobody to ask. -3. **Subagents inherit the orchestrator's quality — by omission, not by setting.** Leave the model parameter off and +4. **Subagents inherit the orchestrator's quality — by omission, not by setting.** Leave the model parameter off and the subagent runs the session's model; leave the effort / reasoning parameter off, where the surface has one, and it runs the session's effort. Never pass a smaller model, never pass a lower effort, never route work to a cheaper agent to save tokens. Two places where inheritance does not happen on its own: a repo-local `.claude/agents/*.md` whose frontmatter pins a `model:` overrides it — pass the session's model explicitly for that agent type or do not use it; and `subagent_type: fork` always inherits the parent model whatever else is passed. -4. **Width: N in parallel, default 5.** Independent assignments go out in a single message, up to N; the rest waits +5. **Width: 5 in parallel unless overridden.** Independent assignments go out in a single message, up to N; the rest waits for a free slot. Dependent work is sequenced — never parallelized in the hope that the order works out. -5. **Disjoint write scopes.** Two subagents in the same wave never hold write access to the same file. Split by file, +6. **Disjoint write scopes.** Two subagents in the same wave never hold write access to the same file. Split by file, or sequence, or give each one its own git worktree (`isolation: "worktree"`) where the surface offers it. -6. **Assignments are self-contained.** A subagent has no conversation history: name the goal, the exact paths, what +7. **Assignments are self-contained.** A subagent has no conversation history: name the goal, the exact paths, what was already tried, the skill file to follow if one applies, the constraints, and what the return value must contain. Ask for a structured return — files touched, what changed, what was verified, what is still open. -7. **Verify the diff, not the summary.** A subagent's report describes intent. After every write-capable agent, read +8. **Verify the diff, not the summary.** A subagent's report describes intent. After every write-capable agent, read the actual change. A wave is done when the orchestrator has looked at what it produced, not when the agent says so. ## Rules @@ -62,13 +70,15 @@ on, then work in it — the user has `/orca off`. - **A failed subagent is a re-assignment, not a takeover.** Sharpen or split the assignment and send it again; the orchestrator never "just fixes it quickly" itself. Third failure on the same unit → `.claude/skills/stuck/SKILL.md`. - **Unattended runs** (`CLAUDE_CODE_REMOTE=true`) keep the mode and keep the ban on ending a turn with a question — - subagents cannot ask either, so the assignment states the assumption it runs under. See `CLAUDE.md` → _Autonomy_. + subagents cannot ask either, so the assignment states the assumption it runs under. See `CLAUDE.md` → *Autonomy*. - **Skills stay in force.** A skill the user invokes while the mode is on is followed by the orchestrator; the work that skill asks for is what gets delegated. - **This is the subagent contract, nothing wider.** It does not by itself authorize heavier multi-agent machinery (workflow-style fan-out over dozens of agents) — that stays an explicit user request. -- **Cost is the trade-off, and it is the user's to make.** The mode multiplies token use and adds latency per unit of - work; that buys parallel width and a main context that stays clean. Say it once when switching on, then never again. +- **Cost is real and already decided.** The mode multiplies token use and adds latency per unit of work; that buys + parallel width and a main context that stays clean. It is the project's default, so do not re-litigate it per task + and do not announce it every turn — mention it only if the user asks or if a task is genuinely the wrong shape for + it, and then say so once with the recommendation, not as a question. ## Report @@ -76,9 +86,9 @@ Close every wave with: ``` ### Orca — wave (/ parallel) -| Assignment | subagent_type | Scope | Result | Verified | -|------------|---------------|-------|--------|----------| -| | | | done / partial / failed | diff read ✅ / ❌ | +| Assignment | Role | subagent_type | Scope | Result | Verified | +|------------|------|---------------|-------|--------|----------| +| | | | | done / partial / failed | diff read ✅ / ❌ | Next: ``` diff --git a/CLAUDE.md b/CLAUDE.md index 2aa1e49c..1ee58790 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,33 +2,24 @@ ## Session Start -- Read Order -When a session begins, read in this order. Stop early if a file is missing. - -1. `MEMORY.md` -- long-term project knowledge -2. `SCRATCHPAD.md` -- short-term working context -3. `BACKLOG.md` -- only if user references prior findings or asks "what's open" -4. `agent_docs/review_process.md`, `agent_docs/memory_process.md` -- only when needed -5. `agent_docs/mcp_catalog.md` -- only when MCPs come up -6. `.claude/skills/*/SKILL.md` -- only when its trigger fires - -> Don't pre-load everything. The Tier-1 SessionStart hook already prints a reminder. +Read in this order, stopping early if a file is missing: `MEMORY.md` (long-term knowledge) -> `SCRATCHPAD.md` (working context) -> `BACKLOG.md` (only if the user references prior findings). `agent_docs/review_process.md`, `memory_process.md` and `mcp_catalog.md` come up on topic; a skill file only when its trigger fires. Don't pre-load everything -- the Tier-1 SessionStart hook prints a reminder. ## Workflow Triggers -| User says... | Skill to load | -| ------------------------------------------------- | ----------------------------------------- | -| "done" / "fertig" / "finished" / "/done" | `.claude/skills/done/SKILL.md` | -| "PR" / "create PR" / "/pr" | `.claude/skills/pr/SKILL.md` | -| "review" / "/review" | `.claude/skills/review/SKILL.md` | -| "security review" / "/security-review" | `.claude/skills/security-review/SKILL.md` | -| "rollback" / "revert" / "undo" / "/rollback" | `.claude/skills/rollback/SKILL.md` | -| "CI" / "fix CI" / "check the build" / "/ci" | `.claude/skills/ci/SKILL.md` | -| "stuck" / "loop" / "going in circles" / "/stuck" | `.claude/skills/stuck/SKILL.md` | -| "check dependencies" / "update deps" / "/beacon" | `.claude/skills/beacon/SKILL.md` | -| "schedule" / "routine" / "nightly" / "/scheduler" | `.claude/skills/scheduler/SKILL.md` | -| "orca" / "orchestrator mode" / "/orca" | `.claude/skills/orca/SKILL.md` | -| Verify a UI change in a real browser | `.claude/skills/verify/SKILL.md` | -| Diagram request | `agent_docs/diagram_prompt.md` | +Skills live at `.claude/skills//SKILL.md` -- load the one whose trigger fires. + +- `done` -- "done" / "fertig" / "finished" / "/done" +- `pr` -- "PR" / "create PR" / "/pr" +- `review` -- "review" / "/review" +- `security-review` -- "security review" / "/security-review" +- `rollback` -- "rollback" / "revert" / "undo" / "/rollback" +- `ci` -- "CI" / "fix CI" / "check the build" / "/ci" +- `stuck` -- "stuck" / "loop" / "going in circles" / "/stuck" +- `beacon` -- "check dependencies" / "update deps" / "/beacon" +- `scheduler` -- "schedule" / "routine" / "nightly" / "/scheduler" +- `orca` -- "orca" / "orchestrator mode" / "/orca" +- `verify` -- verify a UI change in a real browser +- Diagram request -> `agent_docs/diagram_prompt.md` > Review runs via the `review` skill -- done-skill does NOT auto-run it. Findings -> `BACKLOG.md` (`agent_docs/backlog_process.md`). Knowledge -> `MEMORY.md` / `SCRATCHPAD.md` (`agent_docs/memory_process.md`). > **On "done" / "fertig":** commit uncommitted changes, comment on + close the related issue (English), reference it in the commit (`fix: resolve crash #42`). **Do NOT push unless explicitly asked.** @@ -52,21 +43,35 @@ When a session begins, read in this order. Stop early if a file is missing. ## Performance / Modes - **Default model:** whatever the session resolves to -- never pin one here or in `.claude/settings.json`; `/model` switches mid-session. **Fast mode** (`/fast`) is the same Opus model with faster output, not a downgrade. -- **Caveman mode:** `caveman lite|full|ultra` / `stop caveman` -- chat only, never generated files. **Orca mode:** `/orca` toggles orchestrator-only work, `/orca ` sets the parallel width (default 5); off by default, contract in `.claude/skills/orca/SKILL.md`. **Plan mode** for non-trivial strategy, not for single-step tasks. +- **Caveman mode** (chat compression): default `full` in every session -- rules in its own section below. +- **Orchestrator mode** (`orca`): **the default**, width 5 -- see _Subagents_ below. +- **Plan mode** for non-trivial strategy, not for single-step tasks. Full mode reference: `agent_docs/modes.md`. +## Caveman Mode -- chat compression (default `full`) + +In force from the first reply of every session -- no activation step, no environment check. Chat, status messages and confirmations only; **never** files (`CLAUDE.md`, `agent_docs/*`, MEMORY/SCRATCHPAD/BACKLOG, skills), code, commits, PR bodies or issue comments -- those keep the form _Output Languages_ defines. + +- **Shorten by selection, not by compression.** Cut what would not change the reader's next move -- never squeeze prose into abbreviations, arrow chains (`A -> B -> fails`) or invented shorthand. +- Drop articles, filler, pleasantries, hedging. Fragments are fine for a status line. Technical terms exact, code blocks unchanged, error strings verbatim. +- **The closing summary is never compressed** -- outcome first, then what it rests on, in complete sentences, each file/commit/flag in its own plain clause. +- Normal prose for security warnings, irreversible-action confirmations, and whenever fragment order risks a misread. + +`caveman lite|full|ultra` switches mode mid-session; **`stop caveman` turns it off** for the rest of the session. Neither carries forward -- the next session starts at `full`. + ## Autonomy -Which session you are in is resolvable, so it is a rule and not a guess: `$CLAUDE_CODE_REMOTE` is `"true"` in Claude Code web/cloud sessions -- routine runs included -- and unset in the local CLI. +`$CLAUDE_CODE_REMOTE` is `"true"` in web/cloud sessions (routine runs included) and unset in the local CLI, so the mode is resolvable -- a rule, not a guess. + +- **Unattended:** never end a turn with a question -- decide under a stated assumption, finish everything unblocked, carry the open point into the report or `BACKLOG.md`. **Interactive:** ask only when two readings mean materially different work. +- **Both:** destructive _and_ not ordered _and_ not standard practice -> skip it, report it with the recommendation, finish the rest. Gates: merges -> `pr` skill `/pr merge`, reversals/force -> `rollback` skill, deploys + secrets -> _Deployment_ and `agent_docs/env-vars.md`. -- **Unattended** (`CLAUDE_CODE_REMOTE=true`, or the session's initial instructions are a routine): nobody is there to answer. Never end a turn with a question -- decide under an assumption you state, finish every part that isn't blocked, and carry the open point into the final report or `BACKLOG.md`. A routine run has no permission prompts, so a session that "waits for approval" waits forever. -- **Interactive** (local CLI): asking is cheap. Ask when two readings of the task produce materially different work; otherwise decide and mention the call. -- **Both:** an action that is destructive _and_ not ordered _and_ not standard practice gets the same answer either way -- skip it, report it with the recommendation, finish everything it does not block. Gates stay where they are: merges -> `.claude/skills/pr/SKILL.md -> /pr merge`, reversals and force operations -> `.claude/skills/rollback/SKILL.md`, deploys and secrets -> _Deployment_ and `agent_docs/env-vars.md`. +Full wording: `agent_docs/autonomy.md`. ## Scheduled Work -Three schedulers with different lifetimes: **Routines** (cloud, durable, >= 1 h, survive the session), **`/loop` + `CronCreate`/`CronList`/`CronDelete`** (this session only, 7-day expiry), **Desktop scheduled tasks** (local machine). Choosing one, creating/listing/deleting jobs, and the cleanup contract for agent-created jobs: `.claude/skills/scheduler/SKILL.md`. This repo's default prompt for a bare `/loop`: `.claude/loop.md`. +Three schedulers, three lifetimes: **Routines** (cloud, durable, >= 1 h), **`/loop` + `Cron*`** (this session only, 7-day expiry), **Desktop scheduled tasks** (local machine). Selection, job management and the cleanup contract for agent-created jobs: `.claude/skills/scheduler/SKILL.md`. Default prompt for a bare `/loop`: `.claude/loop.md`. ## Project Overview @@ -156,7 +161,7 @@ Component style, CSS conventions and the TS compiler settings: `agent_docs/codin ## Architecture Decisions -Significant decisions are recorded as ADRs under `docs/adr/`. Triggers + format: `agent_docs/adr_template.md`. Always grep `docs/adr/` before contradicting an existing decision. To reverse one, add a new ADR with `Status: Supersedes ADR-NNNN` -- never edit accepted ADRs. +ADRs live under `docs/adr/`; triggers + format: `agent_docs/adr_template.md`. Grep `docs/adr/` before contradicting a decision; reverse one only via a new ADR with `Status: Supersedes ADR-NNNN` -- never edit accepted ADRs. ## Git Conventions @@ -169,9 +174,7 @@ Significant decisions are recorded as ADRs under `docs/adr/`. Triggers + format: ## Dependency Management -- **New dependencies:** Only after user approval with reasoning. -- **devDependencies:** Can be added without approval for tooling/testing. -- **Lock file:** `package-lock.json` -- always commit. +New runtime dependencies only after user approval with reasoning; devDependencies fine without for tooling/testing. Lock file `package-lock.json` -- always commit. ## Environment Variables @@ -179,17 +182,14 @@ Significant decisions are recorded as ADRs under `docs/adr/`. Triggers + format: | -------------------------- | --------------------------------- | --------------------- | | `DATABASE_PATH` | SQLite database file | `./data/clawstash.db` | | `ADMIN_PASSWORD` | Admin login (unset = open access) | -- | -| `TRUST_PROXY` | Trust `X-Forwarded-*` | off | | `CLAWSTASH_ENCRYPTION_KEY` | Secrets at rest, 64 hex chars | auto-generated | -| `PORT` | Server port | `3000` | -Full list + secret locations: `agent_docs/env-vars.md`, `.env.example`. Never `gh secret set` without an explicit user command; `security-review` scans for committed secrets. +Full list (incl. `PORT`, `TRUST_PROXY`) + secret locations: `agent_docs/env-vars.md`, `.env.example`. Never `gh secret set` without an explicit user command; `security-review` scans for committed secrets. ## Deployment - **Trigger:** manual `workflow_dispatch` on `docker-publish.yml` -> multi-stage Docker build -> push to GHCR. Single image, any container host; DB volume at `/app/data`. -- **Agent scope:** push to feature branches, open/update PRs, suggest merge. **Agent does NOT trigger production deploys** without explicit user command. -- **Routine exception:** merges ordered by an owner-authorized routine count as an explicit user command -- conditions + full gate: `.claude/skills/pr/SKILL.md -> /pr merge` (single source of truth). +- **Agent scope:** push to feature branches, open/update PRs, suggest merge -- **no production deploys** without an explicit user command. The one exception (merges ordered by an owner-authorized routine) + full gate: `.claude/skills/pr/SKILL.md -> /pr merge` (single source of truth). - **Rollback:** `.claude/skills/rollback/SKILL.md`. Prefer revert-PR over redeploying an old build. Deployment detail: `docs/deployment.md`. @@ -208,19 +208,29 @@ Full reference: `docs/api-reference.md` - MCP tools: `docs/mcp.md` - auth/scopes ## External Integrations / MCPs -Project-intended and common MCPs: `agent_docs/mcp_catalog.md`. Never auto-detect host MCP availability -- fall back to standard tools (`Read`, `Bash`, `WebFetch`) when an MCP is absent, and never hard-require one. A server an unattended cloud or routine run needs must be a committed `.mcp.json` entry or a claude.ai connector -- a local `claude mcp add` does not travel with the clone. - -**Trigger tools.** `.claude/settings.json` -> `permissions.allow` pre-approves them, so scheduled check-ins, Routine cleanup and PR-watch subscriptions run unattended **wherever this repo's workspace is trusted -- which a web/cloud session never is** (`$CLAUDE_CODE_REMOTE=true`: fresh container, no trust dialog, block dropped at startup); there they keep prompting until the one-time user-scope fix. **Self-heal is local-only:** a tool that still prompts means its server spelling is missing -- append `mcp____*` and commit it, additive only, never `deny`/`ask`. Web/cloud appends nothing (it could not take effect in any session) -- name the fix once and carry on. Allowlist shape, both surfaces, user-level fallback: `agent_docs/mcp_catalog.md -> Prompt-free triggers everywhere`. +Project-intended and common MCPs, cloud/routine reachability (committed `.mcp.json` / claude.ai connectors) and both permission surfaces: `agent_docs/mcp_catalog.md`. Never auto-detect host MCP availability -- fall back to `Read` / `Bash` / `WebFetch`, and never hard-require an MCP. **Trigger-tool self-heal, local sessions only:** a tool that still prompts is a missing server spelling -- append `mcp____*` to `permissions.allow` and commit it, additive only, never `deny`/`ask`; in a web/cloud session (untrusted workspace, block dropped) append nothing -- name the one-time user-scope fix once instead (`agent_docs/mcp_catalog.md -> Prompt-free triggers everywhere`). ## CI -CI failure handling: `.claude/skills/ci/SKILL.md`. Triggered by `/ci`, "fix CI", "check the build". Auto-routes by run state (none / running / passed / failed / stale). Never auto-reruns; always verifies fixes locally before pushing. +CI failure handling: `.claude/skills/ci/SKILL.md`. Triggered by `/ci`, "fix CI", "check the build". Auto-routes by run state; never auto-reruns; always verifies fixes locally before pushing. `docker-publish.yml` is dispatch-only, so "no runs" on a pushed branch is configuration, not breakage: `agent_docs/development-notes.md -> CI/CD`. + +## Subagents -- orchestrator mode is the default + +**Every session starts in orchestrator mode, width 5.** The main agent decides and delegates; subagents do the task work -- not a mode to switch on. `/orca ` changes the width, `/orca off` drops to plain behavior for that session only. The orchestrator keeps only the decisions: decomposition, verification of what comes back, the integration gates, the report. Contract: `.claude/skills/orca/SKILL.md`. -Which workflows actually run -- `docker-publish.yml` is dispatch-only, so "no runs" on a pushed branch is configuration, not breakage: `agent_docs/development-notes.md -> CI/CD`. +**The type carries tool access** (`Explore`, `Plan`, `general-purpose`, `claude-code-guide`); **the role carries the lens**, named in the wave report: -## Subagents +| Role | Earns a seat when | +| ------------- | ------------------------------------------------------- | +| `implementer` | always, for any code change | +| `reviewer` | **any code change -- never its author** | +| `architect` | the change adds, moves or crosses a boundary | +| `domain` | it encodes a domain or business rule | +| `product` | the request is ambiguous or scope could drift | +| `docs` | a documented interface or contract changes | +| `security` | it touches trust boundaries, untrusted input or secrets | -`Explore` (read-only search) - `Plan` (strategy) - `general-purpose` (write+execute) - `claude-code-guide` (Claude Code itself). Direct tools beat subagents when the target is known; parallelize independent calls; pass full context -- subagents have no history. Repo-local agents in `.claude/agents/*.md` load automatically, cloud sessions included -- a `model:` pinned there overrides model inheritance. **Orca mode** (`/orca`) makes delegation the only path and voids the thresholds (`.claude/skills/orca/SKILL.md`). Full guide: `agent_docs/review_process.md -> Subagent Delegation`. +Seat the lenses the change calls for, never two agents with the same one. **Quality parity is by omission:** leave model and effort off and the subagent inherits the session's (a `model:` pinned in `.claude/agents/*.md` overrides). Disjoint write scopes per wave; verify the diff, not the summary. Full guide: `agent_docs/review_process.md -> Subagent Delegation`. ## Development Notes @@ -228,7 +238,7 @@ Runtime + process model, database, Docker and CI/CD specifics: `agent_docs/devel ## Refactoring Notes -Refactoring does NOT happen automatically -- only on explicit request, on repeated review smells, or when structure blocks a feature. Principles: `agent_docs/refactoring_guidelines.md` - candidate list with line counts and BACKLOG refs: `agent_docs/development-notes.md -> Refactoring candidates`. +Never automatic -- explicit request, repeated review smells, or structure blocking a feature only. Principles: `agent_docs/refactoring_guidelines.md` - candidates with line counts + BACKLOG refs: `agent_docs/development-notes.md -> Refactoring candidates`. ## Documentation Rules @@ -266,4 +276,4 @@ Indexed as **clawstash** (2191 symbols, 3899 relationships, 189 execution flows) - + diff --git a/agent_docs/autonomy.md b/agent_docs/autonomy.md new file mode 100644 index 00000000..c839a52e --- /dev/null +++ b/agent_docs/autonomy.md @@ -0,0 +1,9 @@ +# Autonomy -- full wording + +Offloaded from `CLAUDE.md` (context budget) -- the compact rules there are the entry point; this file carries the full wording, moved verbatim. + +Which session you are in is resolvable, so it is a rule and not a guess: `$CLAUDE_CODE_REMOTE` is `"true"` in Claude Code web/cloud sessions -- routine runs included -- and unset in the local CLI. + +- **Unattended** (`CLAUDE_CODE_REMOTE=true`, or the session's initial instructions are a routine): nobody is there to answer. Never end a turn with a question -- decide under an assumption you state, finish every part that isn't blocked, and carry the open point into the final report or `BACKLOG.md`. A routine run has no permission prompts, so a session that "waits for approval" waits forever. +- **Interactive** (local CLI): asking is cheap. Ask when two readings of the task produce materially different work; otherwise decide and mention the call. +- **Both:** an action that is destructive _and_ not ordered _and_ not standard practice gets the same answer either way -- skip it, report it with the recommendation, finish everything it does not block. Gates stay where they are: merges -> `.claude/skills/pr/SKILL.md -> /pr merge`, reversals and force operations -> `.claude/skills/rollback/SKILL.md`, deploys and secrets -> `CLAUDE.md -> Deployment` and `agent_docs/env-vars.md`. diff --git a/agent_docs/modes.md b/agent_docs/modes.md index 89d93625..353a4148 100644 --- a/agent_docs/modes.md +++ b/agent_docs/modes.md @@ -13,19 +13,22 @@ when latency beats reasoning depth; switch back for anything where a wrong answe ## Caveman mode (chat compression) -`caveman lite|full|ultra` turns it on, `stop caveman` turns it off. It compresses **chat replies only** — generated -files (`CLAUDE.md`, `agent_docs/*`, `MEMORY.md`, `SCRATCHPAD.md`, `BACKLOG.md`, skills, commit messages, PR bodies, -issue comments) always stay in full prose in the language `CLAUDE.md → Output Languages` assigns them. +**Default `full` in every session** — in force from the first reply, no activation step. The rules live in +`CLAUDE.md → Caveman Mode` (always loaded); this entry only records the switch surface: `caveman lite|full|ultra` +switches mode, `stop caveman` turns it off for the rest of the session, and neither carries forward — the next +session starts at `full` again. It compresses **chat replies only** — generated files (`CLAUDE.md`, `agent_docs/*`, +`MEMORY.md`, `SCRATCHPAD.md`, `BACKLOG.md`, skills, commit messages, PR bodies, issue comments) always stay in full +prose in the language `CLAUDE.md → Output Languages` assigns them. Technical terms stay English and verbatim in every mode — compression never reaches them. -## Orca mode (orchestrator-only) +## Orca mode (orchestrator mode — the default) -`/orca` toggles it, `/orca ` sets the parallel width (default 5), `/orca status` reports state without changing it. -While on, the agent itself does no task work — every unit goes to a subagent at the session's model and effort. - -**Off by default:** the skill file existing changes nothing until someone types `/orca`. Full contract — what the -orchestrator keeps, quality parity, disjoint write scopes, the wave report: `.claude/skills/orca/SKILL.md`. +**On by default, width 5** — every session starts orchestrating; the default is declared in `CLAUDE.md → Subagents`. +`/orca ` sets the parallel width, `/orca off` drops to plain behavior for the rest of that session and carries +nowhere, `/orca status` reports state without changing it. While on, the agent itself does no task work — every unit +goes to a role-framed subagent at the session's model and effort. Full contract — what the orchestrator keeps, +quality parity, disjoint write scopes, the wave report: `.claude/skills/orca/SKILL.md`. ## Plan mode diff --git a/agent_docs/review_process.md b/agent_docs/review_process.md index 73e488a8..ecafeba7 100644 --- a/agent_docs/review_process.md +++ b/agent_docs/review_process.md @@ -170,18 +170,17 @@ Rules: ## Subagent Delegation -For isolated, clearly bounded subtasks. Pick the matching `subagent_type` instead of always defaulting to `general-purpose`. The thresholds below are the default; while **Orca mode** is on (`.claude/skills/orca/SKILL.md`) they are void -- everything is delegated, whatever its size. - -| Task | When to delegate | Recommended `subagent_type` | -| ------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------- | -| **Locate code / find symbols** | Search across >3 paths or unknown location | `Explore` (read-only, fast, doesn't pollute main context) | -| **Plan refactoring/feature** | Non-trivial, >3 files affected, architectural choice | `Plan` | -| **Write tests** | >3 test files for a feature | `general-purpose` | -| **Doc updates** | >2 documentation files | `general-purpose` | -| **Refactoring chunks** | Independent subtasks of larger refactoring | `general-purpose` | -| **Boilerplate generation** | Migrations, schemas, repetitive configs | `general-purpose` | -| **Independent code review** | Second-opinion on diff | `general-purpose` (or project-specific reviewer subagent if defined) | -| **Q about Claude Code/SDK/API** | "Can Claude do X?", hooks, MCP, SDK questions | `claude-code-guide` | +**Delegation is the default, not a decision per task** -- orchestrator mode is on from session start (`CLAUDE.md -> Subagents`, contract in `.claude/skills/orca/SKILL.md`), so every unit of task work goes to a subagent at width 5. Where the surface allows it, run them asynchronously and keep working -- spawn-and-block gives up most of the benefit -- and step in when one goes off track or is missing context it cannot discover. + +**The review itself is delegated, and to a different agent than wrote the code.** A fresh-context reviewer reads the diff without holding the author's intent, which is why it finds what self-critique does not. Where a change can fail in more than one way, seat _distinct_ lenses from the roster (`architect`, `domain`, `security`, `docs`) rather than a second reviewer with the same one -- agreement between identical lenses is not evidence of correctness. The orchestrator still owns the process: it reads the returned diffs, decides what the findings mean, and holds the commit gate. + +| Task | Matching `subagent_type` | +| ---------------------------------------------------------------- | -------------------------------------------------------------------- | +| **Locate code / find symbols** | `Explore` (read-only, fast, doesn't pollute main context) | +| **Design an approach** | `Plan` | +| **Write tests · doc updates · refactoring chunks · boilerplate** | `general-purpose` | +| **Independent code review** | `general-purpose` (or project-specific reviewer subagent if defined) | +| **Q about Claude Code/SDK/API** | `claude-code-guide` | ## Subagent Selection Rules @@ -190,7 +189,7 @@ For isolated, clearly bounded subtasks. Pick the matching `subagent_type` instea - **Use `general-purpose` for write+execute** tasks. Default for "do this work" delegations. - **Use `claude-code-guide` for tooling questions** about Claude Code itself (slash commands, hooks, MCP servers, SDK). - **Parallelize independent work** -- multiple Agent calls in one message when no dependencies exist. -- **Prefer direct tools when target is known** -- `Read` for known path, `grep` via Bash for known symbol. Reserve subagents for open-ended or multi-step work. +- **Orchestrator mode changes what "known target" means.** Reading a file for its content is task work and goes to a subagent like anything else; the orchestrator's own reads are the _verification_ kind -- `git status`, `git diff`, reading a returned change. `/orca off` is what restores direct-tool-first behavior, not a judgment per call. - **Pass full context** -- subagents have no conversation history. Include file paths, line numbers, what was already tried, and the goal. - **Trust but verify** -- a subagent's summary describes intent, not necessarily the actual change. Inspect diffs after write-capable subagents finish.