AOI-6: docs — inheritance contract page #735

New issue

Closed

opened 2026-05-02 11:01:47 +00:00 by claude-desktop · 0 comments

claude-desktop commented

2026-05-02 11:01:47 +00:00

Collaborator

Acceptance criteria

`docs/inheritance-contract.md` (new)

One-paragraph statement of the invariant up top:

Type scope owns the role contract. Instance scope is additive plus tunable. An instance can ADD net-new plugins, MCP servers, skills. An instance can OVERRIDE the env of an inherited MCP and the body of an inherited skill. An instance CANNOT REMOVE anything its type provides. To remove a capability for all instances of a type, edit at agent_type scope. To remove for everyone, edit at global scope.

Per-artifact rules table:

Artifact	Instance can add	Instance can override	Instance can remove
Plugins	yes	(no overridable fields)	NO
MCP servers	yes	env only (AOI-2)	NO
Skills	yes	body	NO (caveat: empty-body footgun)
System prompt	(single record per agent)	template / short	NO
`agent_type_config` knobs	(single record)	replace	(caveat: blank → baked default)

Escape hatches subsection:
- Edit at agent_type scope → removes for all instances of that type.
- Edit at global scope → removes for everyone (cross-type kill switch).
- Edit scope='builtin' source files (agents.json, mcp-builtin.json, marketplaces-builtin.json) via PR → factory default change, takes effect on next boot.
Cross-link to AOI-1..5 commit history for the rationale.

`docs/agents-architecture.md`

§ resolver updated: links to new inheritance-contract doc.
Existing language about layer-merging with enabled=false shadowing updated — that pattern now applies only at agent_type / global / builtin, not instance.

Cross-references

CLAUDE.md Agents section gains a one-line link to docs/inheritance-contract.md.
apps/server/src/domain/agent-config/resolver.ts header comment links to the new doc.

Out of scope

Operator playbooks / runbooks for common scenarios (e.g. "I broke dev by removing forge MCP at type scope, how do I recover").
Migration guide for users currently relying on instance-scope enabled=false (the boot log from AOI-5 is the operator-facing notice).

References

AOI-1..5 deliverables.
Discussion 2026-05-02.

As an operator or developer reading the project docs, I want a single page describing the add-only-inheritance contract — what the type guarantees, what the instance can and cannot do — so that the rules are discoverable without reading resolver source. ## Acceptance criteria ### `docs/inheritance-contract.md` (new) - [ ] One-paragraph statement of the invariant up top: > Type scope owns the role contract. Instance scope is additive plus tunable. An instance can ADD net-new plugins, MCP servers, skills. An instance can OVERRIDE the env of an inherited MCP and the body of an inherited skill. An instance CANNOT REMOVE anything its type provides. To remove a capability for all instances of a type, edit at `agent_type` scope. To remove for everyone, edit at `global` scope. - [ ] Per-artifact rules table: | Artifact | Instance can add | Instance can override | Instance can remove | |---|---|---|---| | Plugins | yes | (no overridable fields) | NO | | MCP servers | yes | env only (AOI-2) | NO | | Skills | yes | body | NO (caveat: empty-body footgun) | | System prompt | (single record per agent) | template / short | NO | | `agent_type_config` knobs | (single record) | replace | (caveat: blank → baked default) | - [ ] Escape hatches subsection: - Edit at `agent_type` scope → removes for all instances of that type. - Edit at `global` scope → removes for everyone (cross-type kill switch). - Edit `scope='builtin'` source files (`agents.json`, `mcp-builtin.json`, `marketplaces-builtin.json`) via PR → factory default change, takes effect on next boot. - [ ] Cross-link to AOI-1..5 commit history for the rationale. ### `docs/agents-architecture.md` - [ ] § resolver updated: links to new inheritance-contract doc. - [ ] Existing language about layer-merging with `enabled=false` shadowing updated — that pattern now applies only at `agent_type` / `global` / `builtin`, not `instance`. ### Cross-references - [ ] `CLAUDE.md` Agents section gains a one-line link to `docs/inheritance-contract.md`. - [ ] `apps/server/src/domain/agent-config/resolver.ts` header comment links to the new doc. ## Out of scope - Operator playbooks / runbooks for common scenarios (e.g. "I broke `dev` by removing forge MCP at type scope, how do I recover"). - Migration guide for users currently relying on instance-scope `enabled=false` (the boot log from AOI-5 is the operator-facing notice). ## References - AOI-1..5 deliverables. - Discussion 2026-05-02.

claude-desktop added this to the add-only-inheritance milestone

2026-05-02 11:01:47 +00:00

claude-desktop added the

area:meta

type:user-story

labels

2026-05-02 11:01:47 +00:00