agentic-loadout 0.2.0__tar.gz → 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. agentic_loadout-0.5.0/.codex/hooks.json +88 -0
  2. agentic_loadout-0.5.0/.entire/.gitignore +5 -0
  3. agentic_loadout-0.5.0/.entire/settings.json +12 -0
  4. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/CHANGELOG.md +18 -0
  5. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/PKG-INFO +70 -16
  6. agentic_loadout-0.5.0/PLAN.md +149 -0
  7. agentic_loadout-0.5.0/PLAN.orig.md +78 -0
  8. agentic_loadout-0.5.0/README.md +174 -0
  9. agentic_loadout-0.5.0/docs/agentic-loadout.jpeg +0 -0
  10. agentic_loadout-0.5.0/docs/entire-investigation.md +36 -0
  11. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/pyproject.toml +1 -1
  12. agentic_loadout-0.5.0/src/agentic_loadout/__init__.py +1 -0
  13. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/agents.py +18 -0
  14. agentic_loadout-0.5.0/src/agentic_loadout/assets/agents/tiers/code-reviewer.md +10 -0
  15. agentic_loadout-0.5.0/src/agentic_loadout/assets/agents/tiers/coder-small.supplement.md +2 -0
  16. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/development-workflow.md +9 -1
  17. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/agents-rules.md +3 -1
  18. agentic_loadout-0.5.0/src/agentic_loadout/assets/templates/coders/go.md +11 -0
  19. agentic_loadout-0.5.0/src/agentic_loadout/assets/templates/entire-rules.md +11 -0
  20. agentic_loadout-0.5.0/src/agentic_loadout/assets/templates/small-delegation.md +11 -0
  21. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/cli.py +8 -4
  22. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/coders.py +49 -10
  23. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/detect.py +2 -1
  24. agentic_loadout-0.5.0/src/agentic_loadout/entire.py +77 -0
  25. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/git_state.py +2 -1
  26. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/install.py +15 -4
  27. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/instructions.py +1 -1
  28. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/mcp_config.py +44 -0
  29. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/options.py +2 -1
  30. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/pins.py +2 -1
  31. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/preflight.py +12 -0
  32. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/runners.py +3 -2
  33. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/vendors.py +17 -2
  34. agentic_loadout-0.5.0/tests/baseline-agent-hashes.json +15 -0
  35. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/conftest.py +1 -1
  36. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/test_detect_and_brew.py +21 -0
  37. agentic_loadout-0.5.0/tests/test_entire.py +90 -0
  38. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/test_install.py +36 -1
  39. agentic_loadout-0.5.0/tests/test_small_agents.py +170 -0
  40. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/uv.lock +1 -1
  41. agentic_loadout-0.2.0/README.md +0 -120
  42. agentic_loadout-0.2.0/src/agentic_loadout/__init__.py +0 -1
  43. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/.gitattributes +0 -0
  44. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/.github/workflows/ci.yml +0 -0
  45. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/.github/workflows/release.yaml +0 -0
  46. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/.gitignore +0 -0
  47. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/LICENSE +0 -0
  48. /agentic_loadout-0.2.0/PLAN.md → /agentic_loadout-0.5.0/docs/original-implementation-plan.md +0 -0
  49. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/scripts/release_notes.py +0 -0
  50. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/agents/architect.md +0 -0
  51. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/agents/code-grader.head.md +0 -0
  52. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/agents/coder.md +0 -0
  53. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/agents/utility.md +0 -0
  54. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/coders/python.md +0 -0
  55. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/coders/swift.md +0 -0
  56. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/coders/typescript.md +0 -0
  57. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/memory-rules.md +0 -0
  58. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/sdd-rules.md +0 -0
  59. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/assets/templates/worktree-rules.md +0 -0
  60. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/brew.py +0 -0
  61. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/files.py +0 -0
  62. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/src/agentic_loadout/ui.py +0 -0
  63. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/__init__.py +0 -0
  64. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/test_instructions.py +0 -0
  65. {agentic_loadout-0.2.0 → agentic_loadout-0.5.0}/tests/test_mcp_config.py +0 -0
@@ -0,0 +1,88 @@
1
+ {
2
+ "hooks": {
3
+ "PostToolUse": [
4
+ {
5
+ "matcher": null,
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex post-tool-use'",
10
+ "timeout": 30
11
+ }
12
+ ]
13
+ }
14
+ ],
15
+ "SessionEnd": [
16
+ {
17
+ "matcher": null,
18
+ "hooks": [
19
+ {
20
+ "type": "command",
21
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex session-end'",
22
+ "timeout": 3
23
+ }
24
+ ]
25
+ }
26
+ ],
27
+ "SessionStart": [
28
+ {
29
+ "matcher": null,
30
+ "hooks": [
31
+ {
32
+ "type": "command",
33
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then printf \"%s\\n\" \"{\\\"systemMessage\\\":\\\"Entire CLI is enabled but not installed or not on PATH. Installation guide: https://docs.entire.io/cli/installation#installation-methods\\\"}\"; exit 0; fi; exec entire hooks codex session-start'",
34
+ "timeout": 30
35
+ }
36
+ ]
37
+ }
38
+ ],
39
+ "Stop": [
40
+ {
41
+ "matcher": null,
42
+ "hooks": [
43
+ {
44
+ "type": "command",
45
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex stop'",
46
+ "timeout": 30
47
+ }
48
+ ]
49
+ }
50
+ ],
51
+ "SubagentStart": [
52
+ {
53
+ "matcher": null,
54
+ "hooks": [
55
+ {
56
+ "type": "command",
57
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex subagent-start'",
58
+ "timeout": 30
59
+ }
60
+ ]
61
+ }
62
+ ],
63
+ "SubagentStop": [
64
+ {
65
+ "matcher": null,
66
+ "hooks": [
67
+ {
68
+ "type": "command",
69
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex subagent-stop'",
70
+ "timeout": 30
71
+ }
72
+ ]
73
+ }
74
+ ],
75
+ "UserPromptSubmit": [
76
+ {
77
+ "matcher": null,
78
+ "hooks": [
79
+ {
80
+ "type": "command",
81
+ "command": "sh -c 'if ! command -v entire >/dev/null 2>&1; then exit 0; fi; exec entire hooks codex user-prompt-submit'",
82
+ "timeout": 30
83
+ }
84
+ ]
85
+ }
86
+ ]
87
+ }
88
+ }
@@ -0,0 +1,5 @@
1
+ tmp/
2
+ settings.local.json
3
+ metadata/
4
+ logs/
5
+ redactors/local/
@@ -0,0 +1,12 @@
1
+ {
2
+ "enabled": true,
3
+ "strategy_options": {
4
+ "push_sessions": false
5
+ },
6
+ "telemetry": false,
7
+ "checkpoints": {
8
+ "primary": {
9
+ "type": "git-refs"
10
+ }
11
+ }
12
+ }
@@ -1,5 +1,23 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.5.0] - 2026-11-04
4
+
5
+ - Add normal and small Go coders with codenav-go MCP navigation and Go module/workspace detection. The public MCP runs
6
+ through `go run ...@latest`; reruns migrate the previous WIP binary path while preserving environment settings.
7
+ - Add optional Entire checkpoint capture and agent guidance, enabled when Entire is installed. Automatic transcript
8
+ uploads are disabled by default and require explicit opt-in.
9
+ - Update agemem to 0.2.2 and preserve existing project provider settings, including QSIV-to-Jev cascade, on reruns.
10
+ - Update the project image and installer prompt to explain how Entire complements agemem without requiring Entire hosting.
11
+
12
+ ## [0.3.0] - 2026-11-03
13
+
14
+ - Install small-model coder variants and an independent reviewer alongside standard coders, with shared language navigation and delegation guidance.
15
+ - Existing installations gain the new files on re-run. Customized generated files are preserved unless `--force` is used; omitted components are not deleted. Model availability and Cursor fallback depend on the account.
16
+
17
+ ## [0.2.1] - 2026-10-29
18
+
19
+ - Requires agemem 0.2.1, which makes the shared memory store safe when several worktrees or processes write at once.
20
+
3
21
  ## [0.2.0] - 2026-10-29
4
22
 
5
23
  - Requires agemem 0.2.0, whose MCP and hook entries no longer contain this machine's project path, so `.mcp.json`,
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: agentic-loadout
3
- Version: 0.2.0
3
+ Version: 0.5.0
4
4
  Summary: One command that gives a project an agent setup: memory (agemem), the SDD skill, subagents and language coders with code-navigation MCPs. Project-scoped, for Claude Code, Cursor and Codex.
5
5
  Project-URL: Repository, https://github.com/illescasDaniel/agentic-loadout
6
6
  Project-URL: Issues, https://github.com/illescasDaniel/agentic-loadout/issues
@@ -26,22 +26,28 @@ Description-Content-Type: text/markdown
26
26
 
27
27
  One command that gives a project a coding-agent setup, for Claude Code, Cursor and Codex.
28
28
 
29
+ <p align="center">
30
+ <img src="https://raw.githubusercontent.com/illescasDaniel/agentic-loadout/main/docs/agentic-loadout.jpeg" alt="agentic-loadout" height="450">
31
+ </p>
32
+
29
33
  - **Memory:** [agemem](https://github.com/illescasDaniel/agemem) keeps current state, decisions and durable notes in
30
- `memory/`, so a new session picks up where the last one stopped. For Claude Code, agemem (0.2.0+) also
34
+ `memory/`, so a new session picks up where the last one stopped. For Claude Code, agemem (0.2.2+) also
31
35
  disables Claude's built-in auto-memory for the project, to avoid double memory.
32
36
  - **Spec-driven development:** the `sdd-feature` skill takes a feature through design, spec, tests, implementation and
33
37
  an independent grade, with an approval gate between phases.
38
+ - **Session history:** when the [Entire CLI](https://github.com/entireio/cli) is installed, capture agent sessions as
39
+ checkpoints linked to commits. Checkpoint uploads are disabled by default.
34
40
  - **Subagents:** an orchestrator delegates to `architect` (design), `coder` (implementation), `code-grader` (review)
35
41
  and `utility` (commits, checks), following one shared workflow.
36
- - **Language coders:** `coder-python`, `coder-typescript` and `coder-swift` come with code-navigation MCPs, so they
42
+ - **Language coders:** `coder-go`, `coder-python`, `coder-typescript` and `coder-swift` come with code-navigation MCPs, so they
37
43
  rename and refactor through the compiler or type checker instead of `grep` and `sed`.
38
44
 
39
45
  Each piece is handed to the tool that already installs it; agentic-loadout only writes what no tool covers.
40
46
 
41
- Needs `uv` (agemem, Python coder) and Node.js 20+ (skill, TypeScript coder).
47
+ Needs `uv` (agemem, Python coder), Node.js 20+ (skills, TypeScript coder), and Go with gopls for the Go coder.
42
48
 
43
- `--python 3.12` makes `uvx` use a tested Python instead of whichever is newest on your machine. For a reproducible run,
44
- also pin the version: `uvx --python 3.12 agentic-loadout@0.1.0 .`
49
+ `--python 3.12` makes `uvx` use a tested Python instead of whichever is newest on your machine. To pin the loadout
50
+ version, run `uvx --python 3.12 agentic-loadout@0.5.0 .`; individual dependencies may have their own version policy.
45
51
 
46
52
  ## Use
47
53
 
@@ -59,10 +65,13 @@ uvx --python 3.12 agentic-loadout . --personal-settings --yes
59
65
  > project's existing instructions, agents, skills, MCP config and settings (`AGENTS.md`, `CLAUDE.md`, `.claude/`,
60
66
  > `.cursor/`, `.codex/`, `.agents/`, `.mcp.json`). Run `uvx --python 3.12 agentic-loadout . --dry-run` and review the
61
67
  > plan with me: which clients to target (`--tools claude,cursor,codex`), which parts to leave out (`--without
62
- > sdd|agemem|agents|coders|worktree`), which language coders it detected (`--with python,swift,typescript`), the memory
68
+ > sdd|agemem|agents|coders|worktree|entire`), which language coders it detected (`--with go,python,swift,typescript`), the memory
63
69
  > provider (`--memory-model jev|qsiv`), and anything that contradicts the project's current rules or setup. Never
64
70
  > overwrite or move my existing rules; resolve conflicts with me, and ask before using `--force`. Ask me before it runs
65
- > Homebrew for the Swift coder. Then run the real install, review the resulting diff, warnings and next steps, adapt
71
+ > Homebrew for the Swift coder. If the Entire CLI is missing, recommend installing it: it links agent session history
72
+ > to Git commits as checkpoints, giving agents useful context alongside agemem's project memory. It works with an
73
+ > existing Git repository; the project does not need to be hosted on Entire. Keep checkpoint uploads disabled unless
74
+ > I explicitly opt in. Then run the real install, review the resulting diff, warnings and next steps, adapt
66
75
  > the generated sections (quality-gate command, layering, conventions, how to set up the environment in a new
67
76
  > worktree) to this project, and tell me what is left for me to do, such as restarting the client and approving the new
68
77
  > MCP servers and hooks. If memory uses the jev provider, tell me where the API key goes; never ask me to paste it into
@@ -74,9 +83,9 @@ uvx --python 3.12 agentic-loadout . --personal-settings --yes
74
83
 
75
84
  </details>
76
85
 
77
- **Everything stays inside the project.** Nothing is written to `~/.claude`, `~/.codex`, `~/.cursor` or any user-wide
78
- config. The two exceptions: agemem keeps its own private `~/.config/agemem/config.yaml` for the API key, and the Swift
79
- coder's binary is installed with Homebrew, only after you say yes (even with `--yes`; `--allow-brew` skips the question).
86
+ Project configuration stays inside the project. Nothing is written to `~/.claude`, `~/.codex` or `~/.cursor`.
87
+ Agemem keeps its private configuration and shared model cache in your user directories. The Swift coder's binary is
88
+ installed with Homebrew only after you say yes (even with `--yes`; `--allow-brew` skips the question).
80
89
 
81
90
  Rules go to `AGENTS.md`, or to `CLAUDE.md` if the project already has one that isn't just an `@AGENTS.md` import. Each
82
91
  section sits between `<!-- agentic-loadout:begin NAME -->` markers, so re-running updates it in place.
@@ -88,8 +97,9 @@ section sits between `<!-- agentic-loadout:begin NAME -->` markers, so re-runnin
88
97
  | Project memory (`memory/`, notes, MCP, hooks) | [agemem](https://github.com/illescasDaniel/agemem) `project init` |
89
98
  | Spec-driven development skill | `npx skills add illescasDaniel/sdd-feature-skill` |
90
99
  | Worktree skill (`/worktree create\|save\|apply\|delete`) | `npx skills add illescasDaniel/worktree-skill` |
100
+ | Entire checkpoint capture, when its CLI is installed | `entire enable` and `entire agent add` |
91
101
  | Subagents (`architect`, `coder`, `code-grader`, `utility`) and the workflow rules | agentic-loadout |
92
- | Language coders (`coder-python`, `coder-typescript`, `coder-swift`) with their navigation MCPs | agentic-loadout |
102
+ | Language coders (`coder-go`, `coder-python`, `coder-typescript`, `coder-swift`) with their navigation MCPs | agentic-loadout |
93
103
 
94
104
  ### Worktrees
95
105
 
@@ -99,23 +109,63 @@ it. agentic-loadout adds a short rule to your instructions: when your checkout h
99
109
  make, it asks once whether to use a worktree, and after the task it offers `save`, `apply` and `delete`. It never
100
110
  merges, pushes or deletes without your yes. Leave it out with `--without worktree`.
101
111
 
112
+ ### Entire session history
113
+
114
+ Entire records agent sessions and connects captured work to Git commits with checkpoints. It gives an agent or reviewer
115
+ historical context about the request, discussion and files behind a change. Agemem complements this with the current
116
+ project state and selected durable facts and decisions: an agent can inspect a relevant checkpoint, verify a useful
117
+ lesson against current sources, then capture it in agemem with provenance. Neither a transcript nor a memory note
118
+ replaces the code, tests or an independent review.
119
+
120
+ Entire is included by default if its CLI is already installed and the target is a Git repository. It installs Git and
121
+ client hooks; review and approve client hooks when prompted. Loadout does not install Entire itself or initialize Git.
122
+ Use `--without entire` to omit it. `--no-hooks` skips Entire as well as agemem's hooks. A missing CLI or Git repository
123
+ is reported and the remaining installation continues.
124
+
125
+ Loadout configures Entire with automatic checkpoint uploads disabled, including an existing local override, and verifies
126
+ the effective status. Checkpoints stay local unless you explicitly opt in using `--entire-upload-sessions` or change
127
+ Entire's settings yourself. This flag permits uploads to the configured checkpoint destination, which may be public:
128
+ transcripts can contain sensitive information and redaction is best effort. Review `entire status` and
129
+ `entire checkpoint list --outgoing` before pushing. This setting does not prevent manual pushes or later changes.
130
+ For a public project, use a private checkpoint destination if you choose to upload. Existing worktrees and local
131
+ settings can differ; check the effective status in each one.
132
+
133
+ Loadout adds project instructions for using checkpoints as untrusted evidence; no separate Entire skill is required.
134
+ Agents can use `entire agent-help` for the commands supported by the installed CLI. Session capture depends on the
135
+ client hooks being active; it is not a guarantee that every action or subagent is recorded.
136
+
102
137
  ### Language coders
103
138
 
139
+ Each standard coder comes with a `-small` counterpart for bounded work and an independent `code-reviewer`. For example, use `coder-python-small` for a clearly specified Python change and `coder-python` for more complex work. Both use the same navigation MCP. When usage limits or parallel work are a concern, the orchestrator can suggest small coders and follow your preference. The reviewer checks the diff and complements the SDD final grade.
140
+
141
+ Claude uses Haiku for small coders and Sonnet for the reviewer. Codex uses Luna and Terra for these new roles; existing roles keep their current settings. Cursor uses configured models but may fall back when a model is unavailable: check which model actually ran. Model availability varies by account. Edit a generated agent file to change its model; re-runs preserve that edit unless `--force` is used. Read-only reviewer instructions are a convention, not a sandbox boundary.
142
+
143
+ Claude and Codex small-coder files explicitly set high reasoning effort: `effort: high` in Claude's agent frontmatter and `model_reasoning_effort = "high"` in Codex's agent TOML. Claude invocation settings or the `CLAUDE_CODE_EFFORT_LEVEL` environment variable can override its agent setting. Cursor's generated agent files do not specify reasoning effort. Existing customized agent files are preserved on re-runs; use `--force` to replace them with the generated defaults after reviewing your edits.
144
+
145
+ Re-running an existing installation adds the small agents, reviewer and `.agents/delegation-tiers.md`. Re-running with components omitted does not remove previously installed files; use `trash` on unwanted generated agents and guidance manually after reviewing their paths.
146
+
104
147
  A coder is one unit: the `coder-<lang>` subagent, the language's navigation MCP and a routing rule. They are always
105
148
  installed together, because without the subagent's instructions the agent doesn't use the MCP.
106
149
 
107
150
  ```bash
108
151
  uvx --python 3.12 agentic-loadout coders # detect languages, confirm, install
109
- uvx --python 3.12 agentic-loadout coders python typescript # or name them (python, typescript, swift, all)
152
+ uvx --python 3.12 agentic-loadout coders go typescript # or name them (go, python, typescript, swift, all)
110
153
  uvx --python 3.12 agentic-loadout coders --list # catalogue, what is detected, what is installed
111
154
  ```
112
155
 
113
156
  | Language | MCP | Detected by |
114
157
  |---|---|---|
158
+ | go | codenav-go (Go and gopls required) | `go.mod`, `go.work` |
115
159
  | python | codenav | `pyproject.toml`, `setup.py`, `requirements*.txt`, `Pipfile`, `uv.lock` |
116
160
  | typescript | webnav | `package.json`, `tsconfig.json`, `jsconfig.json`, `deno.json` |
117
161
  | swift | codenav-swift (needs the Homebrew binary, macOS) | `Package.swift`, `*.xcodeproj`, `*.xcworkspace`, `Podfile` |
118
162
 
163
+ The Go MCP runs via `go run github.com/illescasDaniel/codenav-go-mcp/cmd/codenav-go-mcp@latest`. Go fetches the public
164
+ module when needed; `@latest` can select a newer release over time. Re-running the installer migrates the exact old WIP
165
+ binary path to this launcher while retaining its environment settings; custom MCP launchers are left alone.
166
+ Cursor's configuration sets the workspace explicitly. Projects with build tags should configure
167
+ `CODENAV_GO_MCP_BUILD_FLAGS` for their build, so gopls sees the right files.
168
+
119
169
  ### Keeping it out of git
120
170
 
121
171
  `--personal-settings` writes rules to `CLAUDE.local.md` (Claude Code only; it starts with `@AGENTS.md` if you have one),
@@ -126,17 +176,21 @@ lists it with your options. With Cursor or Codex selected the rules go to `AGENT
126
176
 
127
177
  ### Flags
128
178
 
129
- `--tools claude,cursor,codex` · `--with python,swift,typescript|all` · `--without sdd|agemem|agents|coders|worktree` ·
179
+ `--tools claude,cursor,codex` · `--with go,python,swift,typescript|all` · `--without sdd|agemem|agents|coders|worktree|entire` ·
130
180
  `--memory-model jev|qsiv` · `--no-hooks` · `--model ALIAS` · `--claude-compat` · `--dry-run` · `--no-input` · `--yes` ·
131
- `--allow-brew` · `--force`. With `--no-input` and no `--yes`/`--with`, no language coder is installed and the command to
181
+ `--allow-brew` · `--entire-upload-sessions` · `--force`. With `--no-input` and no `--yes`/`--with`, no language coder is installed and the command to
132
182
  run is printed.
133
183
 
134
184
  The Jev key is never asked for here. Set `AGEMEM_JEV_API_KEY` or edit `~/.config/agemem/config.yaml`.
135
185
 
186
+ When re-running in an existing Agemem project, leave out `--memory-model` to preserve its configured provider,
187
+ including `cascade` (QSIV with Jev fallback), and avoid repeating provider setup. An explicit `--memory-model` that
188
+ conflicts with the project's configured provider is rejected before installation; change provider settings separately.
189
+
136
190
  ## Development
137
191
 
138
192
  ```bash
139
193
  uv run pytest
140
194
  ```
141
195
 
142
- The design and the decisions behind it are in [PLAN.md](PLAN.md). The real Homebrew path can only be checked on macOS.
196
+ The design and the decisions behind it are in [original implementation plan](docs/original-implementation-plan.md). The real Homebrew path can only be checked on macOS.
@@ -0,0 +1,149 @@
1
+ # Plan: model tiers for delegated work
2
+
3
+ Status: proposal for review, 2026-11-03 (human decisions applied, see Review notes). No implementation is authorized by this plan alone.
4
+
5
+ ## Goal and decisions
6
+
7
+ Make small-model delegation available for well-defined work while preserving language-specific navigation and independent review. Keep the current standard coders; add generic and language-specific `-small` counterparts. The small variants and the reviewer are not opt-in: they are installed alongside the standard coders. The orchestrator chooses an appropriate role for the task and honors the developer's choice.
8
+
9
+ When a developer mentions usage limits or asks for multiple parallel subagents, suggest small-model agents as an option when appropriate. Explain the tradeoff briefly and proceed according to their answer. An explicit request to use a tier is sufficient; do not ask again. Do not automatically switch models merely because limits are mentioned, read usage data, configure a status line, or infer that quotas are separate. Routine delegation without either trigger should not generate repeated suggestions. Keep established preferences for the session and avoid prompting on every block.
10
+
11
+ The earlier project implementation plan is preserved in `docs/original-implementation-plan.md` (currently untracked: commit it, otherwise it only exists in the working tree). `README.md` (line 124), `src/agentic_loadout/instructions.py` (docstring), `install.py` and `tests/conftest.py` still cite the old `PLAN.md` / `PLAN.md §8a`; WP0 repoints them.
12
+
13
+ ## Current behavior and constraints
14
+
15
+ - `assets/agents/coder.md` is a Sonnet agent. `coders.py` builds each language coder from that shared body plus its navigation fragment and tool list. The language routing sections currently direct all relevant code to the standard specialist.
16
+ - `assets/development-workflow.md` describes the generic and language coders, independent SDD grading, task routing and orchestrator responsibilities. The `code-grader` is sourced from the installed SDD skill and is an Opus final grade, not a general implementation reviewer.
17
+ - `vendors.py` converts Claude-format agents for Cursor and Codex. Cursor currently inherits the parent model; Codex conversion currently drops the Claude model. Merely naming an agent `small` therefore does not guarantee a smaller model.
18
+ - Code facts the implementation must respect (verified against the tree):
19
+ - `agents.install_agents` installs every `assets/agents/*.md` (non-recursive glob, skipping `*.head.md`). The small-coder supplement and `code-reviewer.md` must not be installed by that glob accident (the supplement is not an agent, and the glob knows nothing about coder selection). Keep them in a separate directory, `assets/agents/tiers/` (not matched by the glob), and install them through explicit code that runs exactly when coder agents are installed. Check the wheel still ships the directory (CI builds the wheel and runs the CLI from an empty venv).
20
+ - `write_bytes` never overwrites a differing file without `--force` (it logs `skipped`). Consequences: (a) any change that alters the bytes of an existing standard agent or of `.agents/development-workflow.md` is invisible to existing users until `--force`, so tier guidance must not live in `development-workflow.md`; marker sections in `AGENTS.md` are the only content replaced in place; (b) existing standard agent files must stay byte-identical, and a re-run must add the new files without touching customized ones.
21
+ - `vendors.convert_agent` hardcodes `model: inherit` for Cursor and never writes `model` for Codex; Codex `model_reasoning_effort` comes only from the source `effort` field. `agent_source` is currently unused; do not rely on it for round trips.
22
+ - `coders.agent_bytes` drops `name`, `description` and `disallowedTools` from `coder.md` and keeps the rest (`model`, `color`); small variants need `model`/`effort`/`color` overrides there. `vendors._is_read_only` keys off `Edit` in `disallowedTools`: the reviewer must list `Edit` or Cursor `readonly` and the Codex read-only prefix are not emitted.
23
+ - `coders.status()`/`list_coders()` only look at the standard agent; `Coder.section` is one marker section named after the agent (`coder-python`). Rendering small-tier routing inside that same section keeps re-runs replacing in place.
24
+ - `templates/agents-rules.md` hardcodes `architect`, `coder`, `code-grader`, `utility`. The standalone `coders` flow (`install._run_coders`) writes no workflow file and no `agents` section, so anything it installs must be self-explanatory from its own routing section.
25
+ - There is no uninstall and `_run_install` states "Nothing is rolled back"; re-runs are the recovery path.
26
+ - Coders may be installed without the generic agent suite through `agentic-loadout coders`. `--without agents`, `--without sdd` and `--without agemem` are independent choices. Navigation MCPs and generated instruction sections must still work in those combinations.
27
+ - Existing user-owned instructions, agent files and MCP entries must retain the installer's current conflict and `--force` behavior. The installer is project-scoped; keep the established personal-settings and exclusion semantics.
28
+
29
+ ## Roles and model policy
30
+
31
+ | Role | Agent names | Claude default | Codex default | Responsibility |
32
+ |---|---|---|---|---|
33
+ | Small implementation | `coder-small`, `coder-python-small`, `coder-typescript-small`, `coder-swift-small` | Haiku, high effort where supported | Luna, high effort where supported | Execute bounded briefs, use the language MCP and report uncertainty. |
34
+ | Standard implementation | Existing `coder` and `coder-<language>` | Sonnet | Terra | Handle normal implementation and more ambiguous or intricate work. |
35
+ | Independent reviewer | `code-reviewer` | Sonnet | Terra | Review the actual changes and evidence; return actionable findings. |
36
+ | Architecture/advice | Existing `architect` | Opus | Sol by default; Astra available for especially demanding work | Resolve architecture and difficult decisions; do not make model choice a claim of equivalence. |
37
+ | Utility | Existing `utility` | Haiku | Luna | Bounded checks and mechanical tasks, subject to existing permissions and workflow. |
38
+ | Final SDD grade | Existing `code-grader` | Opus | Sol or Astra, subject to client support | Preserve the existing SDD skill's independent final grade and protocol. |
39
+
40
+ The Codex model names (Luna, Terra, Sol, Astra) are authoritative: they come from Codex itself, so they go straight into the `CLIENT_MODELS` table. WP1 still records the exact accepted ID spelling and the client's behavior for an unknown ID. Only if the spike shows a name is rejected does that role fall back to no explicit Codex model (inherit the session), with that disclosed. `code-reviewer` is a new, read-only agent (`disallowedTools: Edit, Write, NotebookEdit` plus the agemem write tools, as in `architect.md`); it keeps `Bash` so it can run tests and `git diff`, which means read-only is a convention, not an enforced boundary.
41
+
42
+ These are configurable defaults, not equivalence, quality, cost or availability guarantees. Confirm effort settings and availability in each supported client during implementation. Existing standard agents and their defaults must not silently change on upgrade; this includes the current utility, architect and grader behavior. Record any validated default change in the README and upgrade notes. An unavailable configured model must produce a clear warning or client error; do not silently claim a small model was used.
43
+
44
+ For Cursor, verify current model-selection support before committing to a mapping. If supported reliably, use an explicit model. Otherwise preserve `inherit`, state clearly that the small role controls instructions rather than guaranteeing model size, and let the developer select the actual model. For Codex, add explicit client-specific model mapping rather than passing Claude aliases through the existing converter; never assume Claude model aliases exist in Codex. Shape: one table in `vendors.py`, `CLIENT_MODELS[(tool, role)] -> (model, effort) | None`, where `None` keeps today's behavior (Cursor `inherit`, Codex no model); `convert_agent` reads it instead of the hardcoded `inherit`, and standard roles map to `None` so their output cannot change. Override UX for v1: edit the generated agent file (re-runs skip it without `--force`, which already protects the edit). No flags or config file. Reasoning effort and model are independent settings and must use values supported by that client/model.
45
+
46
+ ## Delegation and review
47
+
48
+ 1. **Choose the role.** Use small coders for clear, bounded work with concrete acceptance criteria and verifiable outcomes. Larger tasks may be split into independent blocks; length alone is not a reason to use or reject the small tier. Use the standard coder or architect for unresolved behavioral decisions, broad interaction risks, unclear specifications or repeated failures. Honor a developer's explicit model or role choice.
49
+ 2. **Brief the coder.** Give the goal, relevant paths, allowed scope, behavior and edge cases, acceptance criteria, verification commands, dependencies, integration base and how to report blockers. Preserve the shared language-specific tool instructions and forbid unrelated edits, unapproved dependencies, memory writes and git operations unless the brief authorizes them. Small coders stop and report consequential ambiguities rather than inventing design decisions.
50
+ 3. **Review independently.** The orchestrator gives `code-reviewer` the original brief, relevant specification, exact diff or isolated worktree and base, test results, and known uncertainties. Ask for correctness, regressions, missing requirements and meaningful verification; do not suggest a verdict. The reviewer is read-only, provides prioritized findings with file/line evidence, and distinguishes verified behavior from assumptions. A review is not a substitute for required tests or the SDD final grade.
51
+ 4. **Repair and re-review.** Send findings to the same coder when practical. Re-review the resulting diff, especially changes addressing material findings. The orchestrator owns unresolved findings, integration and the final report; after repeated failure or unresolved design questions, escalate to the standard coder or architect. Never silently accept failed review. If an independent reviewer cannot be launched, tell the developer and follow project instructions rather than claiming independent review took place.
52
+ 5. **Parallelize safely.** Assign independent blocks with clear ownership and dependencies. Use isolated worktrees when supported and appropriate; coordinate overlapping changes and review/integrate each result against its actual base. Avoid destructive worktree operations and follow the existing worktree workflow and user instructions. No blanket requirement to create worktrees for every task. Run relevant checks after integration; report skipped checks and conflicts. A coder does not commit or merge unless its brief authorizes it.
53
+
54
+ Review applies to small-coder implementation, including fixes to findings. For trivial read-only utility results, the orchestrator can verify them directly; don't spawn a reviewer for every command. Existing SDD approval gates, the architect and grader contracts, and memory ownership remain intact.
55
+
56
+ ## Installation and upgrade design
57
+
58
+ Small variants and the reviewer are part of the coder install, not a separate feature. There is no new flag and no new option.
59
+
60
+ Install rules:
61
+
62
+ - Whenever a normal coder agent is installed, its small variant is installed with it: generic `coder` -> `coder-small`; each language coder (full install or standalone `coders` command) -> `coder-<lang>-small`. Languages are never added beyond what was selected; MCP servers stay shared, not duplicated.
63
+ - `code-reviewer` is installed whenever any coder agent (generic or language) is installed, independent of SDD. It has no component name of its own: it is tied to coders, and `--without` excludes it only by excluding all coder agents. Rationale: a separate exclusion adds a combination to test for little value, and small output without a reviewer would break the review loop.
64
+ - Consequences for `--without`: `--without agents` omits the generic `coder`/`coder-small` but language specialists, their small variants and the reviewer still install; `--without sdd` and `--without agemem` change nothing about these agents. If no coder agent is installed, neither are small variants nor reviewer.
65
+ - Re-runs and dropped components: the small agents behave exactly like the normal coder agents. A re-run adds missing files, leaves differing (customized) files untouched without `--force`, reports `unchanged` otherwise; omitting a component with `--without` does not delete anything already installed. No special-casing, no deletion.
66
+
67
+ Concrete shape (names are proposals; keep them unless the spike contradicts them):
68
+
69
+ - No `Options`/`cli.py` change.
70
+ - `assets/agents/tiers/code-reviewer.md` and `assets/agents/tiers/coder-small.supplement.md` (short text appended to the shared coder body; the generic `coder-small` is `coder.md` with `name/description/model: haiku/effort: high` overridden plus the supplement).
71
+ - `coders.py`: `small_agent(coder) -> f"{coder.agent}-small"`; `agent_bytes(coder, memory, small=False)`; `Coder.section_text()` always names both tiers (the standard text is rewritten in place, since it is a marker section); `status()` reports small variants (extra `small` column in `list_coders`).
72
+ - `agents.py`: `install_tier_agents(ctx, tools, memory, generic, reviewer)` called from `_run_install` and `_run_coders` right where the standard coders are installed, so presence is decided by the same selection logic. Because small agents are always present with coders, routing needs no "small tier present" detection: wherever the standard coder is named, the small counterpart is named too.
73
+ - Tier guidance goes in a new `.agents/delegation-tiers.md` written via `write_bytes` whenever coders are installed, referenced from the routing section. It names only roles installed with coders (small coders, reviewer), never `architect`, `code-grader`, `utility` or SDD. Do not edit `development-workflow.md` for this (see code facts); a one-line pointer in the workflow is acceptable only if the tests are updated deliberately and the change is called out in CHANGELOG.
74
+ - Parameterize generation by role/tier: reuse the current coder body and the exact same language fragment and navigation tool list, with the concise small-coder supplement. Avoid copying long prompts or diverging language tool lists. Distinct names and descriptions must make the two roles discoverable.
75
+ - Update the generated language routing section so language choice and model tier are separate: Python changes always go to a Python specialist, standard or small according to the workflow and developer choice. Multi-language work may be split by language. Instructions never refer to agents that were not installed (a user who deleted a small file gets it back on the next re-run).
76
+ - Extend role metadata and client conversion deliberately. Preserve model and reasoning fields when copying or converting between clients where appropriate; don't accidentally translate a custom source agent into a different model. Preserve client-specific read-only restrictions where supported and use explicit instructions otherwise; document that instructions alone are not an enforcement boundary.
77
+ - Re-runs, dry runs, `--force`, collision handling, status/list output and personal mode must account for each new agent and the reviewer. Preflight reports the precise files and any conflicts before writing. Existing customized agents, navigation servers, unrelated settings and unmarked instructions remain protected. Print clear upgrade messages (new agents added by this version) and unavailable-model messages.
78
+
79
+ ## Work packages
80
+
81
+ Dependency graph: WP0 -> WP1 -> WP2 -> (WP3 and WP4 in parallel, disjoint files) -> WP5 -> WP6. WP2 builds the generation code but does not wire it into installs, so default output stays unchanged until WP4. (The original text said 2 and 3 were independent; both edit `coders.py` and the routing templates, so they are sequenced here.)
82
+
83
+ 0. **Baseline and housekeeping (no behavior change).** Repoint the `PLAN.md` references listed above to `docs/original-implementation-plan.md`; commit that doc. On unmodified code add a baseline test (`tests/test_golden_default.py`) that runs a default install (`--with all --without agemem,sdd,worktree --tools claude,cursor,codex --yes --no-input`, FakeExecutor, Linux `System`) and asserts a `{relative path: sha256}` map for `.claude/agents`, `.cursor/agents`, `.codex/agents`, `AGENTS.md` and `.agents/`. Also save the pre-change install tree as a test fixture (hash map plus generated files) for the upgrade test. Files: README.md, instructions.py, install.py, tests/conftest.py, tests/test_golden_default.py.
84
+
85
+ 1. **Capability and UX spike (no code).** Verify current Claude Code, Codex and Cursor custom-agent schema, supported model selection and effort, read-only capabilities, model availability/failure behavior and installed client versions. Confirm the exact accepted spelling of the Codex IDs (Luna, Terra, Sol, Astra) and record behavior for an unknown ID. Decide exact per-client defaults for Cursor. Verify existing behavior for `coders` alone and component exclusions. Output: a "Spike results" section appended to this file (client versions, date, the exact frontmatter/TOML keys accepted, observed behavior for an unknown model ID, final `CLIENT_MODELS` table). WP2 may not start without it; a Codex entry falls back to `None` only if the spike shows that name is rejected.
86
+
87
+ 2. **Roles and shared templates.** Files: `vendors.py`, `coders.py`, `agents.py` (function only, not yet called from the install paths), `assets/agents/tiers/*`, `tests/test_small_agents.py`. Implement the small coder supplement and read-only reviewer. Extend agent metadata/generation and per-client model configuration. Standard agents' bytes are unchanged.
88
+
89
+ 3. **Routing and workflow.** Files: `coders.py` (`section_text` only, after WP2 merges), `assets/templates/agents-rules.md` (list roles according to what is installed), `assets/templates/small-delegation.md` and the `.agents/delegation-tiers.md` source. Update language routing, model-choice guidance, triggered suggestion behavior, review loop, parallel blocks and integration rules. Ensure standalone coders and no-SDD setups never reference missing roles.
90
+
91
+ 4. **Installer and lifecycle.** Files: `install.py`, `preflight.py`, tests in `tests/test_install.py`. Wire tier agents and `delegation-tiers.md` into `_run_install` and `_run_coders`, preflight, dry-run, listing and upgrade paths. Handle re-runs, conflicts, personal settings and shared navigation servers consistently. This is the first WP that changes default output: regenerate the golden test deliberately (existing files keep their baseline hashes; new small, reviewer and tiers files are added) and add the upgrade test (install the WP0 baseline tree, re-run with the new code: new agents added, customized existing files untouched without `--force`, replaced with `--force`).
92
+
93
+ 5. **Verification and documentation.** Files: README.md (Language coders section, which files now install by default, manual cleanup note), CHANGELOG.md (entry text only; version bump is WP6). Add focused automated tests and manual client checks below; document examples, how to override a model by editing the generated file, model availability caveats, and the distinction between independent review and SDD grading. Update the README and relevant change notes.
94
+
95
+ 6. **Version bump (last, after WP5 tests pass).** Bump to 0.3.0 in `pyproject.toml` and `__init__.py` (check `pins.py`/release workflow for other places) and finalize the CHANGELOG 0.3.0 entry (new default files, upgrade behavior). Run `uv run pytest -q`, `uv build` and the replay once more on the final tree. Do not bump earlier.
96
+
97
+ Do not implement this proposal until the human has approved it.
98
+
99
+ ## Acceptance and verification
100
+
101
+ - A default install now creates the small variants and the reviewer next to the standard coders; this exact output is pinned by the updated golden test. Existing standard agent files, `development-workflow.md` and navigation entries are byte-identical to the baseline. MCP entries are shared, not duplicated.
102
+ - Upgrade: on a project installed by the previous version, a plain re-run adds the small agents, reviewer and `delegation-tiers.md`, rewrites marker sections in place, leaves customized existing files untouched without `--force`, and reports `unchanged` on a second run.
103
+ - Exercise fresh install, upgrade, rerun, dry-run and conflict/`--force` behavior, plus standalone `coders`, `--without agents`, `--without sdd`, `--without agemem`, personal settings and multiple selected clients. Include customized agent/config preservation, partial installs, and that dropping a component on a later run deletes nothing.
104
+ - For every client, parse generated agent files and verify role names, navigation instructions, tools, model/effort mapping and reviewer restrictions. Check that unavailable or unsupported model selection is disclosed and that `inherit` is not presented as a guaranteed small model. Validate conversions and existing custom agent round trips.
105
+ - Test routing text for standard versus small language coders and for setups without a generic coder, SDD or agemem (no references to missing roles). Verify a developer's explicit choice and session preference take precedence over suggestions; mention of limits or a parallel request triggers an offer rather than a silent switch. No usage telemetry or automatic quota lookup is installed.
106
+ - Run the project's test suite and quality checks appropriate to the change. In supported clients, manually smoke-test a bounded change delegated to a small coder, an independent review and a reviewer-requested correction; check actual model identity, navigation MCP access and integration. Report any client/model combinations not tested, including Swift/macOS where unavailable.
107
+ - Evaluate on representative tasks with comparable briefs and record review findings, retries, elapsed time and available usage data before asserting savings or broad model equivalence.
108
+
109
+ ### Test commands and gates
110
+
111
+ - Per package: `uv run pytest -q` (CI runs exactly this on the OS matrix; there is no ruff/mypy config, so do not invent one). The lead also runs `uv build` and the CI wheel smoke step for any change under `assets/`.
112
+ - Black-box replay (required in every WP report from WP4 on, with the commands and output): in a scratch git repo, `uv run agentic-loadout <scratch> --tools claude,cursor,codex --with python --without agemem,sdd,worktree --yes --no-input`, then a second identical run (expect all `unchanged`) and a `--dry-run` (nothing written). Parse the generated Claude YAML, Cursor YAML and Codex TOML and print name, model, effort and tools for each small agent and the reviewer. Upgrade replay: in a second scratch repo install with the baseline commit (`git worktree` of the pre-change commit), then run the new code on it; expect new files added, existing files `unchanged`, and a hand-edited agent left `skipped`. For WP0-WP3 (no install wiring yet) the replay must instead show default output identical to the baseline.
113
+ - Tests must go through `run_install`/`run_coders` or the CLI `main()`, not only through `agent_bytes`-style helpers; a unit test of a helper alone does not satisfy an acceptance bullet.
114
+
115
+ ## Execution protocol (multi-agent)
116
+
117
+ Evidence from a comparable QA-then-fix campaign: cheap fixers (Haiku, high effort, one worktree each, 3 in parallel, one commit plus a `git format-patch` per block) worked, but a Sonnet reviewer found real defects in about one block in three (silent wrong writes, over-broad refusals, missing end-to-end tests, wrong trailer). Typical fixer failures: skipping black-box replays, unit-only tests, edits outside scope, overwriting shared scratch dirs, stopping on rate limits. Apply this:
118
+
119
+ 1. **Blocks.** One block per work package above (WP2 may split into vendors/coders vs agents/assets if the interface in "Concrete shape" is fixed first). Max 3 in parallel and only blocks with disjoint file lists. The lead (Opus/Sonnet) owns WP0, WP1 review, WP6, integration and final checks; Haiku is acceptable for WP3/WP5 text and docs, Sonnet for WP2/WP4 code.
120
+ 2. **Isolation.** Each fixer gets its own worktree from the current integration commit and its own scratch dir `/tmp/<wp>-<agent>/` (never a shared path). Brief states the base commit, the allowed file list (anything else changed is rejected), the acceptance bullets it owns and the black-box replay above.
121
+ 3. **Deliverable per block.** One commit plus `git format-patch -1` output, a report listing files changed vs the allowed list, test commands with results, replay output, and the exact commit trailer: `Co-Authored-By: <the model name the session is actually running>` per the session's attribution reminder (check it; do not copy another agent's). The reviewer verifies the trailer.
122
+ 4. **Review.** A reviewer per patch (Sonnet, read-only) gets the brief, the patch and the acceptance bullets, and must end with `VERDICT: APPROVE` or `VERDICT: CHANGES` plus numbered findings. A reply with no verdict counts as not reviewed: re-run it. It checks specifically: silent wrong writes (what happens on `skipped`/conflict), over-broad refusals, an integration-path test for each acceptance bullet, standard-agent bytes and the golden test changed only where the WP allows (WP4), files within scope, trailer. The fixer amends once; the reviewer re-checks only the amended hunks; a second failure goes to the lead.
123
+ 5. **Integration.** The lead cherry-picks approved commits in dependency order, resolves conflicts, then runs `uv run pytest -q`, the golden and upgrade tests, `uv build` and the replay on the merged tree. Never merge a block whose review lacks a verdict.
124
+ 6. **Resilience.** A fixer that stops on a rate limit leaves its worktree intact; the lead resumes it with the same brief (SendMessage) or restarts it from its last commit. Never delete a worktree with unreviewed work; use `trash` for cleanup of scratch dirs only.
125
+ 7. **Rollback.** Changes are additive (new files; marker sections rewritten in place); to back out, revert the integration commits (one per block). Generated files in a user's project are not removed by a re-run; document `trash .claude/agents/*-small.md ...` style cleanup in the README rather than automating deletion.
126
+
127
+ ## Review decisions still open
128
+
129
+ - Escalation threshold after repeated review failures: start with the current workflow's two-attempt rule where applicable; confirm or change.
130
+
131
+ ## Review notes (Claude review of the GPT-6 draft, 2026-11-03; original in `PLAN.orig.md`)
132
+
133
+ Changed and why:
134
+ - Added "code facts" after reading the source: the `assets/agents/*.md` glob would install new agents by accident, so tier assets live in their own directory and install through explicit code; `write_bytes` skips differing files, so edits to `development-workflow.md` never reach existing users (tier guidance moved to a new `.agents/delegation-tiers.md` and the `AGENTS.md` marker section); Cursor `model: inherit` is hardcoded; `agent_source` is dead code; the standalone `coders` flow has no workflow file.
135
+ - Stale references: this file replaced the old PLAN.md, but README and three code comments still point at it, and the old plan is untracked. Added WP0.
136
+ - Added concrete interfaces and file lists (`agent_bytes(..., small)`, `CLIENT_MODELS`, `install_tier_agents`), resequenced WP2/WP3 (they touch the same files), concrete test commands, a black-box replay and an integration-path test rule.
137
+ - Added the multi-agent execution protocol from the observed fixer/reviewer campaign, with required verdict format, scope allowlists, scratch-dir isolation, trailer check and rollback.
138
+ - Left unchanged: roles, delegation and review text (sound).
139
+
140
+ Human decisions (applied throughout):
141
+ 1. Luna, Terra, Sol and Astra are authoritative Codex IDs (the plan comes from Codex) and go into `CLIENT_MODELS`; the spike still records exact spelling and unknown-ID behavior, with a fallback only if a name is rejected.
142
+ 2. Model overrides: editing the generated agent file is enough for v1; no flags or config file.
143
+ 3. Small coders are not opt-in and have no flag: they are always installed with the normal coders (generic and language, full install or `coders`). The reviewer is tied to coders as well, with no separate exclusion. Default output therefore changes; the byte-identity guarantee is replaced by a golden test of the new default output plus upgrade-behavior tests. The interactive-installer question is moot. Note: the opt-in design (`--small-coders`, `Options.small_coders`, flag combinations, "nothing to install" error, `assets/agents/optional/`) from the earlier draft was replaced by this always-with-coders design.
144
+ 4. Re-runs and `--without` treat small agents exactly like the normal coder agents: nothing is deleted, no special-casing.
145
+ 5. Version 0.3.0 with a CHANGELOG entry, done last (WP6) after the implementation is tested.
146
+
147
+ ## Capability observations (2026-11-03)
148
+
149
+ Claude Code 2.1.314 documents `model: haiku|sonnet|opus`, `effort`, and `disallowedTools` in subagent frontmatter. Cursor 3.27.22 documents `model` as `inherit` or a model ID and `readonly: true`; it may fall back when the requested model is unavailable. Codex CLI 0.166.0 documents custom-agent TOML `model` and `model_reasoning_effort` and this session lists `gpt-6-luna`, `gpt-6.1-terra`, `gpt-6.1-sol`, and `gpt-6-astra` as available. New small/reviewer roles use Luna/high and Terra in Codex and Luna/Terra in Cursor; existing roles remain unchanged. See https://code.claude.com/docs/en/sub-agents, https://cursor.com/docs/subagents and https://learn.chatgpt.com/docs/agent-configuration/subagents. These are schema and session-availability checks, not live subagent executions; unknown-model behavior and account-specific Cursor access were not verified.
@@ -0,0 +1,78 @@
1
+ # Plan: model tiers for delegated work
2
+
3
+ Status: proposal for review, 2026-11-03. No implementation is authorized by this plan alone.
4
+
5
+ ## Goal and decisions
6
+
7
+ Make small-model delegation available for well-defined work while preserving language-specific navigation and independent review. Keep the current standard coders; add generic and language-specific `-small` counterparts. The orchestrator chooses an appropriate role for the task and honors the developer's choice.
8
+
9
+ When a developer mentions usage limits or asks for multiple parallel subagents, suggest small-model agents as an option when appropriate. Explain the tradeoff briefly and proceed according to their answer. An explicit request to use a tier is sufficient; do not ask again. Do not automatically switch models merely because limits are mentioned, read usage data, configure a status line, or infer that quotas are separate. Routine delegation without either trigger should not generate repeated suggestions. Keep established preferences for the session and avoid prompting on every block.
10
+
11
+ The earlier project implementation plan is preserved in `docs/original-implementation-plan.md`.
12
+
13
+ ## Current behavior and constraints
14
+
15
+ - `assets/agents/coder.md` is a Sonnet agent. `coders.py` builds each language coder from that shared body plus its navigation fragment and tool list. The language routing sections currently direct all relevant code to the standard specialist.
16
+ - `assets/development-workflow.md` describes the generic and language coders, independent SDD grading, task routing and orchestrator responsibilities. The `code-grader` is sourced from the installed SDD skill and is an Opus final grade, not a general implementation reviewer.
17
+ - `vendors.py` converts Claude-format agents for Cursor and Codex. Cursor currently inherits the parent model; Codex conversion currently drops the Claude model. Merely naming an agent `small` therefore does not guarantee a smaller model.
18
+ - Coders may be installed without the generic agent suite through `agentic-loadout coders`. `--without agents`, `--without sdd` and `--without agemem` are independent choices. Navigation MCPs and generated instruction sections must still work in those combinations.
19
+ - Existing user-owned instructions, agent files and MCP entries must retain the installer's current conflict and `--force` behavior. The installer is project-scoped; keep the established personal-settings and exclusion semantics.
20
+
21
+ ## Roles and model policy
22
+
23
+ | Role | Agent names | Claude default | Codex proposed default | Responsibility |
24
+ |---|---|---|---|---|
25
+ | Small implementation | `coder-small`, `coder-python-small`, `coder-typescript-small`, `coder-swift-small` | Haiku, high effort where supported | Luna, high effort where supported | Execute bounded briefs, use the language MCP and report uncertainty. |
26
+ | Standard implementation | Existing `coder` and `coder-<language>` | Sonnet | Terra, subject to capability validation | Handle normal implementation and more ambiguous or intricate work. |
27
+ | Independent reviewer | `code-reviewer` | Sonnet | Terra, subject to capability validation | Review the actual changes and evidence; return actionable findings. |
28
+ | Architecture/advice | Existing `architect` | Opus | Sol by default; Astra available for especially demanding work | Resolve architecture and difficult decisions; do not make model choice a claim of equivalence. |
29
+ | Utility | Existing `utility` | Haiku | Luna | Bounded checks and mechanical tasks, subject to existing permissions and workflow. |
30
+ | Final SDD grade | Existing `code-grader` | Opus | Sol or Astra, subject to client support | Preserve the existing SDD skill's independent final grade and protocol. |
31
+
32
+ These are proposed configurable defaults, not equivalence, quality, cost or availability guarantees. Confirm exact model IDs, effort settings and availability in each supported client during implementation. Existing standard agents and their defaults must not silently change on upgrade without an explicit migration choice; this includes the current utility, architect and grader behavior. Record any validated default change in the README and upgrade notes. An unavailable configured model must produce a clear warning or client error; do not silently claim a small model was used.
33
+
34
+ For Cursor, verify current model-selection support before committing to a mapping. If supported reliably, use an explicit configurable model. Otherwise preserve `inherit`, state clearly that the small role controls instructions rather than guaranteeing model size, and let the developer select the actual model. For Codex, add explicit client-specific model mapping rather than passing Claude aliases through the existing converter. Keep overrides per client and role; never assume Claude model aliases exist in Codex. Reasoning effort and model are independent settings and must use values supported by that client/model.
35
+
36
+ ## Delegation and review
37
+
38
+ 1. **Choose the role.** Use small coders for clear, bounded work with concrete acceptance criteria and verifiable outcomes. Larger tasks may be split into independent blocks; length alone is not a reason to use or reject the small tier. Use the standard coder or architect for unresolved behavioral decisions, broad interaction risks, unclear specifications or repeated failures. Honor a developer's explicit model or role choice.
39
+ 2. **Brief the coder.** Give the goal, relevant paths, allowed scope, behavior and edge cases, acceptance criteria, verification commands, dependencies, integration base and how to report blockers. Preserve the shared language-specific tool instructions and forbid unrelated edits, unapproved dependencies, memory writes and git operations unless the brief authorizes them. Small coders stop and report consequential ambiguities rather than inventing design decisions.
40
+ 3. **Review independently.** The orchestrator gives `code-reviewer` the original brief, relevant specification, exact diff or isolated worktree and base, test results, and known uncertainties. Ask for correctness, regressions, missing requirements and meaningful verification; do not suggest a verdict. The reviewer is read-only, provides prioritized findings with file/line evidence, and distinguishes verified behavior from assumptions. A review is not a substitute for required tests or the SDD final grade.
41
+ 4. **Repair and re-review.** Send findings to the same coder when practical. Re-review the resulting diff, especially changes addressing material findings. The orchestrator owns unresolved findings, integration and the final report; after repeated failure or unresolved design questions, escalate to the standard coder or architect. Never silently accept failed review. If an independent reviewer cannot be launched, tell the developer and follow project instructions rather than claiming independent review took place.
42
+ 5. **Parallelize safely.** Assign independent blocks with clear ownership and dependencies. Use isolated worktrees when supported and appropriate; coordinate overlapping changes and review/integrate each result against its actual base. Avoid destructive worktree operations and follow the existing worktree workflow and user instructions. No blanket requirement to create worktrees for every task. Run relevant checks after integration; report skipped checks and conflicts. A coder does not commit or merge unless its brief authorizes it.
43
+
44
+ Review applies to small-coder implementation, including fixes to findings. For trivial read-only utility results, the orchestrator can verify them directly; don't spawn a reviewer for every command. Existing SDD approval gates, the architect and grader contracts, and memory ownership remain intact.
45
+
46
+ ## Installation and upgrade design
47
+
48
+ - Add small coders as an **opt-in** feature. Define an explicit CLI option for both the full install and `coders` command, e.g. `--small-coders`; settle exact spelling during implementation. Default and existing invocations keep their present output and behavior. The option enables the generic small coder when generic agents are installed, and the small specialist for each selected or already-installed language specialist; a standalone `coders` run installs the requested language specialists and their small variants without requiring the generic suite. Avoid silently adding unrequested languages or duplicating MCP servers.
49
+ - Include a reviewer when the opt-in small workflow is installed, including standalone language-coder installs, independent of SDD. Ensure `--without agents` and `--without sdd` have clearly documented behavior: language specialists and the minimal reviewer required by an explicit small-coder request may still be installed, while the generic suite and SDD grader remain omitted. Preflight should report the precise files and any conflicts before writing.
50
+ - Parameterize generation by role/tier: reuse the current coder body and the exact same language fragment and navigation tool list, with a concise small-coder instruction supplement. Avoid copying long prompts or diverging language tool lists. Distinct names and descriptions must make the two roles discoverable.
51
+ - Update the generated language routing section so language choice and model tier are separate: Python changes always go to a Python specialist, with either the standard or small specialist selected according to the workflow and developer choice. Multi-language work may be split by language. Ensure instructions never refer to agents that were not installed.
52
+ - Extend role metadata and client conversion deliberately. Preserve model and reasoning fields when copying or converting between clients where appropriate; don't accidentally translate a custom source agent into a different model. Preserve client-specific read-only restrictions where supported and use explicit instructions otherwise; document that instructions alone are not an enforcement boundary. Test the actual generated format and supported client behavior.
53
+ - Re-runs, dry runs, `--force`, collision handling, status/list output and personal mode must account for each newly generated agent and the reviewer. Existing customized agents, navigation servers, unrelated settings and unmarked instructions remain protected. Print clear upgrade and unavailable-model messages, and document how to select or override role-to-model mappings without editing generated files where feasible.
54
+
55
+ ## Work packages
56
+
57
+ 1. **Capability and UX spike.** Verify current Claude Code, Codex and Cursor custom-agent schema, supported model selection and effort, read-only capabilities, model availability/failure behavior and installed client versions. Decide exact per-client defaults and an override mechanism; record limitations and source/date. Verify existing behavior for `coders` alone and component exclusions. Resolve whether generated defaults can be portable across accounts before implementing.
58
+ 2. **Roles and shared templates.** Implement the small coder supplement and read-only reviewer. Extend agent metadata/generation and per-client model configuration. Preserve standard agents by default, and include generic and per-language roles according to explicit installation choices.
59
+ 3. **Routing and workflow.** Update language routing, model-choice guidance, triggered suggestion behavior, review loop, parallel blocks and integration rules. Ensure standalone coders and no-SDD setups never reference missing roles.
60
+ 4. **Installer and lifecycle.** Add the opt-in flag to both entry points, preflight, dry-run, listing and upgrade paths. Handle re-runs, conflicts, personal settings and shared navigation servers consistently.
61
+ 5. **Verification and documentation.** Add focused automated tests and manual client checks below; document examples, mapping/overrides, model availability caveats, and the distinction between independent review and SDD grading. Update the README and relevant change notes.
62
+
63
+ Work packages 2 and 3 can be developed independently after package 1 if their role contracts are agreed; package 4 integrates them, followed by package 5. Do not implement this proposal until reviewed.
64
+
65
+ ## Acceptance and verification
66
+
67
+ - A default install and an upgrade without the opt-in preserve existing roles and routing. Opting in creates only the selected language variants, generic variant where applicable, and reviewer; MCP entries are shared, not duplicated.
68
+ - Exercise fresh install, upgrade, rerun, dry-run and conflict/`--force` behavior, plus standalone `coders`, `--without agents`, `--without sdd`, `--without agemem`, personal settings and multiple selected clients. Include customized agent/config preservation and partial installs.
69
+ - For every client, parse generated agent files and verify role names, navigation instructions, tools, model/effort mapping and reviewer restrictions. Check that unavailable or unsupported model selection is disclosed and that `inherit` is not presented as a guaranteed small model. Validate conversions and existing custom agent round trips.
70
+ - Test routing text for standard versus small language coders and for missing optional roles. Verify a developer's explicit choice and session preference take precedence over suggestions; mention of limits or a parallel request triggers an offer rather than a silent switch. No usage telemetry or automatic quota lookup is installed.
71
+ - Run the project's test suite and quality checks appropriate to the change. In supported clients, manually smoke-test a bounded change delegated to a small coder, an independent review and a reviewer-requested correction; check actual model identity, navigation MCP access and integration. Report any client/model combinations not tested, including Swift/macOS where unavailable.
72
+ - Evaluate on representative tasks with comparable briefs and record review findings, retries, elapsed time and available usage data before asserting savings or broad model equivalence.
73
+
74
+ ## Review decisions
75
+
76
+ - Confirm the proposed per-client default models and override UX after the capability spike, particularly Terra versus Sol for standard Codex coding and review.
77
+ - Confirm the CLI option name and whether enabling small coders should be presented in the interactive installer as well as by explicit flag.
78
+ - Confirm the desired escalation threshold after repeated review failures; start with the current workflow's two-attempt rule where applicable.