tunestra 0.4.0 → 0.6.0

package/README.md

@@ -70,14 +70,31 @@ the manifest only holds metadata and overrides.
   rules/<key>.md            # rules, one topic per file
   skills/<key>/SKILL.md     # skills (Agent Skills format)
   commands/<key>.md         # slash commands
+  agents/<key>.md           # subagents
   mcp/<key>.yaml            # MCP servers
 ```
 
+A subagent is a markdown file with frontmatter; the text after it is the instructions:
+
+```md
+---
+description: Reviews a diff for bugs and missing tests   # required: when to use it
+model:                      # optional: the model for each agent
+  claude: sonnet            #   otherwise the agent uses the model of the main session
+  codex: gpt-5.5
+effort: medium              # optional: low | medium | high | xhigh
+readOnly: true              # optional: the subagent must not change files
+---
+Review the diff. Report each finding with a file and a line.
+```
+
+The file name is the name of the subagent: lowercase letters, digits and single hyphens.
+
 ### Manifest: `tunestra.preset.yaml`
 
 ```yaml
 name: team                  # required, unique in the chain
-level: team                 # required: base | domain | team
+level: team                 # required: base | domain | team | local
 description: Frontend team conventions
 extends:                    # optional, from general to specific
   - ../base
@@ -110,11 +127,49 @@ exclude: {}
 overrides: {}
 ```
 
+### Personal level: `tunestra.local.yaml`
+
+A developer can tune the setup for themselves with `tunestra.local.yaml` and `.tunestra.local/`
+in the project; `tunestra init --local` creates both. tunestra always puts both in
+`.gitignore`. The personal level comes after the project, so it can add artifacts, override
+them by key and exclude them, like any other level.
+
+```yaml
+name: local                 # optional, defaults to local
+extends:                    # optional: personal presets with level: local
+  - ~/presets/me
+exclude:
+  skills: [storybook]
+env:
+  HTTPS_PROXY: http://localhost:3128
+permissions:
+  allow: [Bash(make *)]
+```
+
+A personal preset has `level: local` in its manifest and can be shared between your projects.
+The personal level can extend only such presets, and no shared level can extend them.
+
+The committed files stay the same for the whole team: AGENTS.md, CLAUDE.md and
+`.claude/settings.json` are built without the personal level. Every other generated file
+follows the chain with it. A personal level cannot exclude `env` or permissions, because
+Claude Code joins the personal settings with the committed ones and cannot remove a
+committed entry.
+
+| Agent | What it gets |
+|---|---|
+| Claude Code | `CLAUDE.local.md`, which it reads after CLAUDE.md: what the personal level adds, overrides and turns off. Personal `env` and permissions are added to `.claude/settings.local.json` |
+| Codex | `AGENTS.override.md`, which it reads instead of AGENTS.md: the whole index with the personal level |
+
+Claude Code writes `.claude/settings.local.json` too, for example when you allow a command for
+good. tunestra remembers which entries it added and changes only those: your settings and
+the rules of Claude Code stay. A variable that you changed by hand is yours and stays too.
+
 ### Sources
 
 | Reference | Example |
 |---|---|
 | Relative path | `../presets/team` (relative to the file that references it) |
+| Home directory | `~/presets/me`, for personal presets |
 | GitHub | `github:<owner>/<repo>/<path>#<ref>` |
 | GitLab | `gitlab:<owner>/<repo>/<path>#<ref>` |
 
@@ -143,6 +198,7 @@ chain once, before both of them.
 | Level instructions (`AGENTS.md`) | `instructions@<preset name>` | never collides: every level keeps its own | `exclude.rules` |
 | Skill | `name` from `SKILL.md`, otherwise the folder name | replaces it | `exclude.skills` |
 | Command | file name without `.md` | replaces it | `exclude.commands` |
+| Subagent | file name without `.md` | replaces it | `exclude.subagents` |
 | MCP server | file name without `.yaml` | replaces it | `exclude.mcp` |
 | Environment variable | name in `env` | replaces it | `exclude.env` |
 | Permission rule | the rule, like `Bash(npm test *)` | lists are joined: every level adds its rules | `exclude.permissions`, only for `allow` and `ask` |
@@ -166,7 +222,9 @@ are merged by key (the specific value wins); `command`, `args` and `url` are rep
 - an `env` value refers to another variable, like `${TOKEN}`: agents do not expand it in
   their settings, so write the value itself and keep secrets out of presets;
 - `env` sets a variable that Claude Code ignores in project settings (see below);
-- `exclude.permissions` tries to remove a `deny` rule.
+- `exclude.permissions` tries to remove a `deny` rule;
+- a subagent has no `description` or no instructions, an unknown field, or a file name that
+  cannot be a subagent name.
 
 All problems are reported at once, in the order of the files, so you can fix them in one pass.
 
@@ -176,10 +234,11 @@ For every agent:
 
 | Path | Content | Committed |
 |---|---|---|
-| `AGENTS.md` | Index: hierarchy, rules, skills, commands, MCP servers | yes |
+| `AGENTS.md` | Index: hierarchy, rules, skills, commands, MCP servers, subagents | yes |
 | `.agents/rules/<NN>-<level>-<key>.md` | Rule texts, ordered from specific to general | no |
 | `.agents/skills/<key>/` | Skills | no |
 | `.tunestra/state/` | What tunestra generated last time | no |
+| `AGENTS.override.md`, `CLAUDE.local.md` | The personal level, when there is one | no |
 | `.gitignore` | A block between `# >>> tunestra` and `# <<< tunestra` | yes |
 
 ### Claude Code
@@ -190,6 +249,7 @@ For every agent:
 | `.claude/rules/tunestra/<NN>-<level>-<key>.md` | Copies of the rules; Claude Code loads them in every session | no |
 | `.claude/skills/<key>` | Symlinks to `.agents/skills/<key>` | no |
 | `.claude/commands/<key>.md` | Commands | no |
+| `.claude/agents/<key>.md` | Subagents | no |
 | `.mcp.json` | MCP servers | no |
 | `.claude/settings.json` | `env` and `permissions`, when presets set them | yes |
 
@@ -207,6 +267,9 @@ the ones that choose its own directories (`HOME`, `XDG_*`, `CLAUDE_CONFIG_DIR`).
 on them, because they would not work; set them in managed settings, `~/.claude/settings.json`
 or your shell. Values that turn telemetry off, like `OTEL_LOGS_EXPORTER: none`, are allowed.
 
+A read-only subagent of Claude Code loses the tools that change files: `Write`, `Edit`,
+`NotebookEdit` and `Bash`. It keeps the tools that read and search, and MCP tools.
+
 ### Codex
 
 Codex reads `AGENTS.md` and `.agents/skills/` by itself. It does not follow the links in
@@ -217,6 +280,7 @@ Codex reads `AGENTS.md` and `.agents/skills/` by itself. It does not follow the
 | `.codex/config.toml` | `developer_instructions` with every rule, from specific to general, `[shell_environment_policy] set` with `env`, and `[mcp_servers]` | no |
 | `.codex/rules/tunestra.rules` | `deny` and `ask` rules for shell commands as `prefix_rule`: `forbidden` and `prompt` | no |
 | `.agents/skills/<command>/` | Each command as a skill that runs only when you call it: `$release-notes` | no |
+| `.codex/agents/<key>.toml` | Subagents | no |
 
 Codex reads `.codex/config.toml` only in a trusted project: trust the project when Codex asks.
 Codex gets `env` as the environment of the commands it runs; it does not change how Codex
@@ -232,7 +296,12 @@ Codex has no `type` for MCP servers and does not support SSE: an SSE server is s
 note, and `headers` become `http_headers`. tunestra owns the whole `.codex/config.toml`; keep
 your personal Codex settings in `~/.codex/config.toml`.
 
-`<NN>` orders rules from specific to general: `10` project, `20` team, `30` domain, `40` base.
+A Codex subagent gets the sandbox, the permissions and the MCP servers of the main session; its
+file can change only the model and the instructions. So Codex cannot make a subagent
+read-only: tunestra turns off its shell (`features.shell_tool = false`) and asks it not to
+edit files in the instructions, and setup says so in a note.
+
+`<NN>` orders rules from specific to general: `00` personal, `10` project, `20` team, `30` domain, `40` base.
 Level instructions get the key `instructions`, and the preset name when it differs from the
 level: `20-team-instructions.md`, but `20-team-instructions-frontend.md` for a `team` preset
 named `frontend`.
@@ -268,10 +337,11 @@ Generated files are never kept because of manual edits: change the sources inste
 | Command | What it does |
 |---|---|
 | `tunestra init` | Creates `tunestra.yaml`; `--extends <presets...>` fills `extends`. Moves a hand-written `AGENTS.md` to `.tunestra/AGENTS.md` and a `CLAUDE.md` with its own text to `.tunestra/rules/claude-md.md`; a `CLAUDE.md` that only imports `AGENTS.md` is removed |
+| `tunestra init --local` | Creates your personal level, `tunestra.local.yaml` and `.tunestra.local/rules/`, in a project with `tunestra.yaml`. `--extends` adds personal presets |
 | `tunestra setup` | Resolves the chain and regenerates every output |
 | `tunestra setup --dry-run` | Prints what would be written or removed, and the warnings |
 | `tunestra setup --verbose` | Also prints where every artifact comes from and what it overrides |
-| `tunestra uninstall` | Removes everything tunestra generated and its block in `.gitignore`; `tunestra.yaml` and `.tunestra/` stay. `--dry-run` shows the list first |
+| `tunestra uninstall` | Removes everything tunestra generated and its block in `.gitignore`, and takes its entries out of `.claude/settings.local.json`; the sources stay. `--dry-run` shows the list first |
 
 `tunestra setup` refuses to overwrite an `AGENTS.md` or `CLAUDE.md` that it did not generate
 and tells you where to move their text.
@@ -282,7 +352,7 @@ and tells you where to move their text.
 |---|---|
 | v0.1 | Inheritance for Claude Code |
 | v0.2 | Codex (this document) |
-| v0.3 | `env` and permissions, then subagents and a personal `local` level |
+| v0.3 | `env`, permissions, subagents and a personal `local` level |
 | v0.4 | Spaces, npm sources, lockfile |
 | v0.5 | `required` / `locked` policies, CI check |
 | v0.6 | Hooks |