feat(protocol): add authored runtime and team configs

spec/agent-runtime-v1.md

@@ -0,0 +1,105 @@
+# Agent Runtime Config v1
+
+`SETTINGS.yaml` is the human-authored source of truth for portable runtime intent in this repo.
+
+Team inventory metadata is defined separately in `TEAM.yaml` (see `spec/team-protocol-v1.md`). This spec only covers runtime policy.
+
+## Goals
+
+- Keep one editable config for approval, filesystem, network, and model intent.
+- Generate backward-compatible Claude and Codex outputs from that shared intent.
+- Make adapter lossiness explicit where provider config surfaces do not line up.
+
+## Scope
+
+Version 1 standardizes:
+
+- portable model tier and reasoning level
+- filesystem access intent
+- approval intent
+- network access intent
+- portable tool classes
+- protected path rules
+- dangerous shell command prompts
+- target-specific escape hatches only when the target exposes settings with no shared equivalent
+
+Version 1 does not attempt to standardize:
+
+- every provider model name
+- provider-specific tool grammars
+- every future runtime capability for local agents, IDE plugins, or hosted agents
+
+## Shared fields
+
+### `model`
+
+- `class`: `fast | balanced | powerful`
+- `reasoning`: `low | medium | high | max`
+
+### `runtime`
+
+- `filesystem`: `read-only | workspace-write`
+- `approval`: `manual | guarded-auto | full-auto`
+- `network_access`: boolean
+- `tools`: portable tool classes such as `shell`, `read`, `edit`, `write`, `glob`, `grep`, `web_fetch`, `web_search`
+
+### `safety`
+
+- `protected_paths`: glob patterns that should remain blocked from normal reads or writes
+- `dangerous_shell_commands.ask`: shell command patterns that should remain approval-gated
+
+### `targets`
+
+Target blocks are escape hatches, not the main schema. Use them only where a runtime exposes a knob with no shared equivalent.
+
+Current target-specific fields:
+
+- `targets.claude.claude_md_excludes`
+- `targets.codex.approval_policy`
+- `targets.codex.network_access`
+
+## Adapter rules
+
+### Claude Code
+
+`settings.json` is generated as a compatibility artifact.
+
+- `runtime.filesystem = read-only` -> `permissions.defaultMode = "plan"`
+- `runtime.filesystem = workspace-write` -> `permissions.defaultMode = "acceptEdits"`
+- `runtime.tools` -> Claude tool allow-list
+- `safety.protected_paths` -> Claude `deny` entries for `Read`, `Write`, and `Edit`
+- `dangerous_shell_commands.ask` -> Claude `ask` entries wrapped as `Bash(...)`
+
+Lossiness:
+
+- Claude vends `allow` / `deny` / `ask` as tool-pattern rules.
+- Shared `approval` intent does not map 1:1 to Claude beyond `plan` vs `acceptEdits`.
+
+### Codex CLI
+
+`codex/config.toml` is generated directly from shared intent.
+
+- `runtime.filesystem = read-only` -> `sandbox_mode = "read-only"`
+- `runtime.filesystem = workspace-write` -> `sandbox_mode = "workspace-write"`
+- `runtime.approval = manual` -> `approval_policy = "on-request"`
+- `runtime.approval = guarded-auto` -> `approval_policy = "untrusted"`
+- `runtime.approval = full-auto` -> `approval_policy = "never"`
+- `runtime.network_access` -> `[sandbox_workspace_write].network_access`
+
+Lossiness:
+
+- Codex does not expose Claude-style per-tool `allow` / `deny` / `ask` pattern controls in `config.toml`.
+- Protected paths and dangerous command prompts are therefore only partially representable in Codex config today.
+
+## Compatibility contract
+
+The repo preserves these compatibility artifacts:
+
+- `settings.json`
+- `claude/settings.json`
+- `claude/CLAUDE.md`
+- `codex/config.toml`
+- `codex/AGENTS.md`
+- generated agent outputs for both targets
+
+These are build artifacts, not authored source files. `SETTINGS.yaml` is the required runtime input.

spec/team-protocol-v1.md

@@ -0,0 +1,136 @@
+# Team Protocol v1
+
+`TEAM.yaml` defines the team metadata and inventory protocol for portable generation targets in this repo.
+
+Implementation status:
+
+- Wave 1: protocol + documentation introduced
+- Wave 2: generator + install integration completed; TEAM metadata is the active source of truth for team inventory behavior
+
+## Goals
+
+- Define a neutral, schema-backed source for agents, skills, and rules metadata.
+- Keep Claude and Codex as adapter targets rather than protocol sources.
+- Preserve Markdown as the human-authored instruction content format.
+- Preserve current generated output behavior unless a narrow caveat is explicitly documented.
+
+## Scope
+
+Version 1 standardizes:
+
+- agent inventory and metadata required for generation
+- skill inventory metadata
+- rule inventory and deterministic ordering
+- adapter boundaries for Claude and Codex
+- validation requirements needed by the generator
+
+Version 1 does not standardize:
+
+- full prose structure for skills/rules/agents
+- provider-specific runtime/tool grammars
+- every future adapter target
+
+## Source-of-Truth Split
+
+- `SETTINGS.yaml`: runtime policy protocol (filesystem, approval intent, network, model intent)
+- `TEAM.yaml`: team inventory protocol (agents, skills, rules metadata and references)
+- Markdown files: instruction bodies
+  - agents: `agents/*.md`
+  - skills: `skills/*/SKILL.md`
+  - rules: `rules/*.md`
+
+Generated artifacts remain:
+
+- `settings.json`
+- `claude/`
+- `codex/`
+
+## Required TEAM Inventories
+
+`TEAM.yaml` must contain:
+
+- `agents`
+- `skills`
+- `rules`
+
+## Agent Contract
+
+Each agent entry includes metadata required for adapter generation:
+
+- `id`
+- `name`
+- `description`
+- `model`
+- `effort`
+- `permission_mode`
+- `tools`
+- `disallowed_tools`
+- `max_turns`
+- `skills`
+- optional `background`
+- optional `memory`
+- optional `isolation`
+- `instruction_file`
+
+`instruction_file` points to the Markdown source for long-form instructions.
+
+## Skill Contract
+
+Each skill entry includes lightweight metadata and content reference:
+
+- `id`
+- `description`
+- `instruction_file`
+- optional target/install metadata
+
+Skill prose remains in `skills/*/SKILL.md`.
+
+## Rule Contract
+
+Each rule entry includes:
+
+- `id`
+- `source_file`
+- deterministic order metadata
+- optional target metadata
+
+Rule prose remains in `rules/*.md`.
+
+## Adapter Boundaries
+
+Claude and Codex are render targets.
+
+Current target behavior:
+
+- Claude generation consumes TEAM metadata + Markdown content and outputs:
+  - `claude/CLAUDE.md`
+  - `claude/settings.json`
+  - `claude/agents/*.md`
+- Codex generation consumes TEAM metadata + Markdown content and outputs:
+  - `codex/config.toml`
+  - `codex/AGENTS.md`
+  - `codex/agents/*.toml`
+
+## Validation Requirements
+
+TEAM validation enforces schema + runtime checks for:
+
+- schema version correctness
+- required sections present
+- unique IDs for agents/skills/rules
+- referenced files exist
+- deterministic rule ordering inputs are valid
+- `order` IDs match declared inventory keys
+- item `id` matches keyed map entry
+
+## Compatibility Caveats
+
+- Existing YAML frontmatter in `agents/*.md` may remain for editorial continuity, but generation does not use it for team metadata.
+- Output diffs that are purely formatting-related are acceptable; semantic behavior changes are not unless explicitly documented.
+- TEAM schema is intentionally rigid/repo-specific in v1; inventory additions/removals require schema updates in lockstep.
+
+## Out of Scope
+
+- Rewriting instruction prose for style
+- Full content schemas for skill/rule prose
+- Generalizing all future adapters in v1