Deliver the composed charter as a replacement system prompt, not as CLAUDE.md layered on Claude Code's own #1360

New issue

Open

opened 2026-08-28 21:39:50 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-28 21:39:50 +00:00

Owner

What happens today

A Claude launch passes exactly two flags. agent-compose/docs/claude-launch-identity.md says so under a heading called "The two flags", and cmd/agent-compose/main.go:1030-1034 builds them:

--name <annotation> - the seat annotation
--settings <bundle>/claude-settings.json - theme, spinner verbs, tips

Neither --system-prompt nor --append-system-prompt appears anywhere in agentic-os or agent-compose. The composed charter instead arrives as a CLAUDE.md load point plus a projected skill tree. Measured from a live composed session (ad84): 56,589 bytes of ~/.claude/CLAUDE.md and 50 skills, layered on top of Claude Code's complete default system prompt.

Why that is the problem

The charter can only add to a voice and a ruleset it has no way to remove. Kai's observation is that composed seats leak Claude's register, and this is the structural cause: the base system prompt is always fully present.

--append-system-prompt does not fix this. Only --system-prompt replaces.

The plumbing is already proven

coilyco-flight-deck/agent-compose#346 verified end to end, from inside another session:

claude -p --append-system-prompt "$(cat content/instructions.md)" \
  --name 'Angie [she] (...)' '<prompt>'

returned the composed identity correctly. The installed claude is 2.1.246 and carries --system-prompt, --append-system-prompt, and both --system-prompt-file / --append-system-prompt-file variants.

Prefer the -file form. The bundle already writes content/instructions.md to disk, so a path avoids pushing tens of kilobytes through argv and avoids a shell-quoting surface.

The hard part, and the reason this is not a switch flip

Replacing the system prompt removes Claude Code's own tool-use instructions, harness conventions, permission framing, and output rules along with its voice. A replacement charter that does not re-supply what tool calling depends on will produce a seat that cannot use its tools.

The unknown worth naming first: what minimum does a replacement prompt have to carry for tool use, permission prompts, and the harness contract to keep working? That question decides whether this is viable at all, and it is cheaper to answer than to build around.

Suggested shape

A delivery mode on the launch path rather than a hard switch, so replacement and today's layering both remain reachable and comparable.
--system-prompt-file <bundle>/content/instructions.md for the replacement mode.
Whatever tool-use preamble the answer above turns out to require, composed into the bundle rather than hand-maintained beside it.

Acceptance

A composed Claude launch can deliver its charter as a replacement system prompt.
Tool use, permission prompts, and file editing work in a replacement-mode session, demonstrated rather than argued.
Boundaries still bind in replacement mode, checked against the four boundary skills.
Today's layered delivery still works and is still selectable.
docs/claude-launch-identity.md stops saying "the two flags" if it becomes three.

Boundary note

The flag construction lives in agent-compose/cmd/agent-compose/main.go, and agent-compose is inside the science seat's build-foundational-software scope. I am handing that half over rather than assuming it, on Kai's instruction. If platform would rather the science seat build the agent-compose side and platform take only aos-cli, say so on this issue and I will pick it up.

Not in scope here

Whether replacement actually changes the voice is a measurement, and it stays with the science seat on the housecast board, running against deepseek rather than Claude. That work is tracked separately.

Filed by Evie, science seat, session ad84.

Handover to platform. Kai asked for the AOS-layer mechanism to move to Angie while the science seat takes the voice measurement. This issue is the mechanism only; no measurement work is asked for here. ## What happens today A Claude launch passes exactly **two** flags. `agent-compose/docs/claude-launch-identity.md` says so under a heading called "The two flags", and `cmd/agent-compose/main.go:1030-1034` builds them: * `--name <annotation>` - the seat annotation * `--settings <bundle>/claude-settings.json` - theme, spinner verbs, tips **Neither `--system-prompt` nor `--append-system-prompt` appears anywhere in agentic-os or agent-compose.** The composed charter instead arrives as a `CLAUDE.md` load point plus a projected skill tree. Measured from a live composed session (`ad84`): **56,589 bytes of `~/.claude/CLAUDE.md` and 50 skills**, layered on top of Claude Code's complete default system prompt. ## Why that is the problem The charter can only **add** to a voice and a ruleset it has no way to remove. Kai's observation is that composed seats leak Claude's register, and this is the structural cause: the base system prompt is always fully present. `--append-system-prompt` does not fix this. Only `--system-prompt` replaces. ## The plumbing is already proven `coilyco-flight-deck/agent-compose#346` verified end to end, from inside another session: claude -p --append-system-prompt "$(cat content/instructions.md)" \ --name 'Angie [she] (...)' '<prompt>' returned the composed identity correctly. The installed `claude` is **2.1.246** and carries `--system-prompt`, `--append-system-prompt`, and both `--system-prompt-file` / `--append-system-prompt-file` variants. **Prefer the `-file` form.** The bundle already writes `content/instructions.md` to disk, so a path avoids pushing tens of kilobytes through argv and avoids a shell-quoting surface. ## The hard part, and the reason this is not a switch flip Replacing the system prompt removes Claude Code's own tool-use instructions, harness conventions, permission framing, and output rules along with its voice. A replacement charter that does not re-supply what tool calling depends on will produce a seat that cannot use its tools. **The unknown worth naming first: what minimum does a replacement prompt have to carry for tool use, permission prompts, and the harness contract to keep working?** That question decides whether this is viable at all, and it is cheaper to answer than to build around. ## Suggested shape * A delivery mode on the launch path rather than a hard switch, so replacement and today's layering both remain reachable and comparable. * `--system-prompt-file <bundle>/content/instructions.md` for the replacement mode. * Whatever tool-use preamble the answer above turns out to require, composed into the bundle rather than hand-maintained beside it. ## Acceptance - [ ] A composed Claude launch can deliver its charter as a replacement system prompt. - [ ] Tool use, permission prompts, and file editing work in a replacement-mode session, demonstrated rather than argued. - [ ] Boundaries still bind in replacement mode, checked against the four boundary skills. - [ ] Today's layered delivery still works and is still selectable. - [ ] `docs/claude-launch-identity.md` stops saying "the two flags" if it becomes three. ## Boundary note The flag construction lives in `agent-compose/cmd/agent-compose/main.go`, and agent-compose is inside the science seat's `build-foundational-software` scope. **I am handing that half over rather than assuming it**, on Kai's instruction. If platform would rather the science seat build the agent-compose side and platform take only `aos-cli`, say so on this issue and I will pick it up. ## Not in scope here Whether replacement actually changes the voice is a measurement, and it stays with the science seat on the housecast board, running against deepseek rather than Claude. That work is tracked separately. Filed by Evie, science seat, session `ad84`.

coilyco-ops added the

priority

role/platform

labels

2026-08-28 21:39:55 +00:00

coilyco-ops added the

autonomy

async-consult

label

2026-08-29 07:04:24 +00:00