| name | init |
| description | Initialize an agent session, resolve the project profile, audit required capabilities, and emit the deterministic constraint manifest. Use at the start of repository work or whenever profile, branch, roadmap, or capability state changes. |
init — session initialization
Canonical repository skill. Codex discovers it natively from .agents/skills/;
Claude Code reaches it through the matching .claude/skills/ delegate.
Detects project type, produces a bounded manifest of applicable constraint
paths, writes .agents/session_state.json (and .claude/session_state.json for
compatibility), and warns about protected branches and active roadmaps.
Execution
.agents/bin/agent-init --platform claude
.agents/bin/agent-init --platform codex
Behaviour (guaranteed)
- Reads
.agents/project.yml for project type; falls back to heuristic scan.
- Runs the capability audit defined by
.agents/capabilities.yml.
- Prints a deterministic, profile-aware manifest of selected constraints.
Read the listed files before work to which they apply; this keeps initial
context bounded and makes the source of each rule inspectable.
- Creates
.agents/session_state.json (+ .claude/session_state.json mirror) —
hooks and wrappers use this file to gate mutations.
Failure mode
If the capability audit fails, the wrapper exits non-zero. The session is
considered blocked for mutating operations until the failure is resolved
and .agents/bin/agent-init is re-run.
Detailed reference
Read references/guide.md when troubleshooting session
initialization or constraint selection.
