From 272d3b6382ee9471bf18834da695c863a75822b3 Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Sat, 16 May 2026 11:12:30 +0800 Subject: [PATCH 1/5] docs: add architecture overview --- docs/architecture/OVERVIEW.md | 110 ++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 docs/architecture/OVERVIEW.md diff --git a/docs/architecture/OVERVIEW.md b/docs/architecture/OVERVIEW.md new file mode 100644 index 00000000..383863a1 --- /dev/null +++ b/docs/architecture/OVERVIEW.md @@ -0,0 +1,110 @@ +# Architecture Overview + +Retinue is a local subagent lifecycle layer for Codex-like MCP clients. The host agent delegates a coding task to an installed local agent runtime, gets a job handle quickly, and later polls, reads, closes, or cleans that job. + +Retinue is intentionally narrow: + +- more durable than a one-shot MCP wrapper, because it keeps job state and artifacts; +- smaller than a platform, because it does not route providers, choose models, host queues, or replace OpenCode / Claude Code. + +For the formal scope, see [Project Boundary](PROJECT_BOUNDARY.md). + +## Runtime Shape + +```text +Codex or another MCP client + -> Retinue skill and MCP tools + -> Retinue lifecycle API + -> backend adapter + -> OpenCode server or Claude Code CLI + -> local state and bounded artifacts +``` + +Backend choice is deployment configuration. The caller should use the product `retinue_*` tools rather than choosing OpenCode or Claude Code from each request. + +## Product Tool Surface + +| Tool | Purpose | +| --- | --- | +| `retinue_spawn_agent` | Start a child job through the configured backend and return a `jobId` with metadata. | +| `retinue_wait_agent` | Wait within a host-safe window and return either terminal output or running diagnostics. | +| `retinue_close_agent` | Close a child job and remove it from the active MCP-session pool. | +| `retinue_list_agents` | List active child jobs tracked by the current MCP server session. | + +Backend-specific `opencode_*` and `claude_*` tools are adapter/debug surfaces. They should stay hidden in normal plugin deployments unless `RETINUE_EXPOSE_BACKEND_TOOLS=1` is deliberately enabled. + +## Components + +| Component | Owns | Does not own | +| --- | --- | --- | +| MCP host | Deciding what to delegate and when to poll or close the child. | Backend profile, provider login, model routing. | +| Retinue MCP server | Product tools, wait limits, active child-agent slots. | Cloud orchestration or provider choice. | +| Lifecycle API | Job metadata, status, result, continuation, close, cleanup. | Agent-runtime internals. | +| Backend adapter | Translating lifecycle operations to OpenCode or Claude Code. | Reimplementing a full agent client. | +| OpenCode / Claude Code | Provider credentials, model defaults, profile policy, plugins, permissions. | Retinue job-state semantics. | +| State directory | Metadata, stdout/stderr logs, traces, artifact paths. | Long-term memory or credential storage. | + +## Job Lifecycle + +A normal product flow is: + +1. The host calls `retinue_spawn_agent` with a prompt, task name, and preferably an absolute `cwd`. +2. Retinue records job metadata and starts or attaches to the configured backend runtime. +3. Retinue returns a `jobId` without blocking the root agent on the whole child task. +4. The host calls `retinue_wait_agent` until the job reaches a terminal state. +5. Running responses include bounded output tails, artifact paths, and compact diagnostics. +6. Terminal responses include the result or an attention-required status such as failure or stall. +7. The host calls `retinue_close_agent` when the child is no longer needed. + +Each MCP server session keeps a small active child-agent pool. The default is 3 active children, matching the practical shape of three children plus one root thread. + +## Backend Notes + +OpenCode is the default 0.1.0 backend. The plugin deployment starts or attaches to a loopback OpenCode server and asks OpenCode to use the `plan` agent by default: + +```text +RETINUE_BACKEND=opencode +RETINUE_OPENCODE_AUTO_SERVE=1 +RETINUE_OPENCODE_HOST=127.0.0.1 +RETINUE_OPENCODE_AGENT=plan +``` + +Retinue-managed OpenCode prefers `127.0.0.1:4096` and can fall back through `4097` to `4127` when earlier ports are already used by external services. OpenCode still owns provider configuration, login, model defaults, endpoint routing, plugins, skills, and profile policy. See [OpenCode Backend](../backends/OPENCODE.md). + +Claude Code is available as an alternate backend for deployments that set: + +```text +RETINUE_BACKEND=claude-code +``` + +Claude Code still owns its own model, endpoint, quota, permission, and profile behavior. + +## Safety And Observability Defaults + +Retinue defaults to local, bounded behavior: + +- prompts are kept out of child-agent process arguments; +- default status responses do not include full prompts; +- MCP responses return bounded output tails and artifact paths instead of unbounded logs; +- OpenCode product spawns are read-only by default; +- managed local services bind to loopback by default; +- stale or corrupted state should become an explicit status rather than fake success; +- real backend probes are still required because static tests cannot catch every local runtime contract drift. + +Common diagnostic paths under `RETINUE_STATE_DIR`: + +```text +/logs/retinue.jsonl +/jobs//meta.json +/jobs//stdout.log +/jobs//stderr.log +``` + +## What To Read Next + +- [Project Boundary](PROJECT_BOUNDARY.md) +- [OpenCode Backend](../backends/OPENCODE.md) +- [Plugin Deployment](../deployment/PLUGIN_DEPLOYMENT.md) +- [Source Install And Development](../development/SOURCE_INSTALL.md) +- [Hermes Agent Integration](../integrations/HERMES.md) +- [Documentation Governance](../DOCUMENTATION_GOVERNANCE.md) From 5c911a86a33eb5c3791ca7809841481cf77298e0 Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Sat, 16 May 2026 11:14:34 +0800 Subject: [PATCH 2/5] docs: add documentation governance --- docs/DOCUMENTATION_GOVERNANCE.md | 104 +++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 docs/DOCUMENTATION_GOVERNANCE.md diff --git a/docs/DOCUMENTATION_GOVERNANCE.md b/docs/DOCUMENTATION_GOVERNANCE.md new file mode 100644 index 00000000..6846a22b --- /dev/null +++ b/docs/DOCUMENTATION_GOVERNANCE.md @@ -0,0 +1,104 @@ +# Documentation Governance + +Retinue documentation should stay useful for three groups: + +1. users who only want to install the Codex plugin and run a child agent; +2. operators who need deployment defaults, diagnostics, and real-runtime probes; +3. contributors who need to change the runtime safely. + +When one document starts serving multiple audiences, split it or add an audience note near the top. + +## Source Of Truth + +| Topic | Source of truth | Notes | +| --- | --- | --- | +| Product positioning and user quickstart | Root `README.md` and `README.en.md` | Keep these focused on the current user path. | +| Documentation map | `docs/README.md` | Every durable doc should be reachable from here. | +| Architecture and boundary | `docs/architecture/OVERVIEW.md` and `docs/architecture/PROJECT_BOUNDARY.md` | Stable concepts, data flow, and non-goals. | +| OpenCode behavior | `docs/backends/OPENCODE.md` | Default backend behavior, access mode, diagnostics, and adapter notes. | +| Codex plugin packaging | `docs/deployment/PLUGIN_DEPLOYMENT.md` | Plugin install shape, bundled runtime, cache behavior, and production E2E boundary. | +| Source development | `docs/development/SOURCE_INSTALL.md` | Contributor setup, build, tests, hooks, and source-tree verification. | +| Release facts | `docs/release/*` | Versioned release notes and readiness records. Do not silently rewrite old release history. | +| Agent-facing behavior | `plugins/retinue/skills/retinue/SKILL.md` | Keep aligned with product MCP tools and safety defaults. | +| Hermes integration | `docs/integrations/HERMES.md` and `integrations/hermes/*` | Hermes is an MCP host integration, not a Retinue backend. | + +## Document Types + +Use these categories consistently: + +- **README / quickstart**: current user path only; avoid implementation history. +- **Architecture**: stable concepts, data flow, boundaries, and non-goals. +- **Backend contract**: runtime-specific behavior and environment knobs. +- **Deployment**: installation shape, packaging, plugin cache, and operational defaults. +- **Development**: source checkout, tests, local probes, generated artifacts. +- **Runbook**: concrete steps for a real environment or incident class. +- **Release**: versioned records; historical once published. +- **Archive**: old reviews, metadata notes, and superseded records kept for traceability. + +Research notes and speculative plans should stay under `docs/research/` or `docs/superpowers/` unless they are promoted into the docs index as current guidance. + +## Required Updates When Behavior Changes + +| Change | Docs to check | +| --- | --- | +| Product MCP tool added or removed | Root READMEs, architecture overview, Retinue skill doc | +| Backend default or backend selection behavior changes | Root READMEs, architecture overview, backend doc, plugin deployment doc | +| OpenCode auto-serve, port, timeout, or access-mode behavior changes | OpenCode backend doc, root READMEs, plugin deployment doc, skill doc | +| Plugin manifest, `.mcp.json`, bootstrap, or cache behavior changes | Plugin deployment doc, source install doc, root READMEs if user-visible | +| New environment variable | Relevant backend or deployment doc; root README only if normal users need it | +| State directory, log field, artifact, or diagnostic shape changes | Backend doc, deployment doc, runbooks, verification docs | +| Release process or package contents change | Release docs, source install doc, plugin deployment doc | +| Hermes integration changes | Hermes integration docs and `integrations/hermes/*` | + +If a change is intentionally internal and not user-visible, say that in the PR body instead of forcing noisy README edits. + +## Style Rules + +- Prefer current behavior over project history. +- Put commands in copyable fenced blocks. +- Mark risky or environment-mutating steps explicitly. +- Keep secrets, tokens, account names, and API keys out of docs and traces. +- Use concrete tool names such as `retinue_spawn_agent`. +- Distinguish product tools from raw adapter/debug tools. +- Avoid claiming a real-runtime path is verified unless a real probe has passed. +- Use absolute paths in examples when workspace drift would matter. +- Keep Chinese and English READMEs semantically aligned when the user-facing install path changes. + +## Documentation PR Checklist + +```markdown +## Documentation checklist + +- [ ] I identified the audience for each changed doc. +- [ ] I kept root README changes focused on current user paths. +- [ ] I updated `docs/README.md` when adding durable docs. +- [ ] I checked whether the Retinue skill guidance needs the same behavior update. +- [ ] I did not rewrite historical release notes except for typo/link fixes. +- [ ] I avoided secrets, local credentials, and unredacted provider details. +- [ ] I recorded whether verification was docs-only or included runtime gates. +``` + +For docs-only PRs, the minimum verification is a link/path review plus Markdown readability. Runtime gates are not required unless the doc claims a command or real probe currently works. + +## Archive Policy + +Move documents to `docs/archive/` when they are useful for traceability but no longer represent current product guidance. Add a short note at the top when practical: + +```markdown +> Archived: this page records historical context and is not current setup guidance. +``` + +Do not delete release records or old review notes just because a newer path exists. Prefer demotion from the docs index to archive over deletion. + +## Keeping The Docs Navigable + +`docs/README.md` should remain the stable map for durable docs. Keep it grouped by user intent: + +- current product and architecture; +- installation and deployment; +- development and verification; +- real-runtime runbooks; +- release records; +- archive and research. + +A new doc that is not linked from `docs/README.md` should be treated as temporary or incomplete. From 62efaff1ccd61263c28ee70897dd58247ee30ebc Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Sat, 16 May 2026 11:15:09 +0800 Subject: [PATCH 3/5] docs: reorganize documentation index --- docs/README.md | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/README.md b/docs/README.md index 32f3fc2c..62bb0fe9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,37 +1,44 @@ # Retinue Docs -Start here. Current product guidance is separated from historical notes so the root `docs/` -directory stays readable. +Start here when you need more detail than the root README. This index separates current product guidance from deployment notes, development docs, runbooks, release records, and archive material. -## Current Product +## Current Product And Architecture -- [0.1.0 Release Readiness](release/0.1.0_RELEASE_PLAN.md) - release boundary, closed work, release gate, and deferred issues. -- [0.1.0 Hardening Record](release/0.1.0_HARDENING_ISSUES.md) - closed smoke/E2E issues and current verification requirements. -- [v0.1.0 Release Notes](release/v0.1.0_RELEASE_NOTES.md) - user-facing release summary. -- [v0.1.0 Release Notes zh-CN](release/v0.1.0_RELEASE_NOTES.zh-CN.md) - Chinese reference. -- [Long-Term Vision](LONG_TERM_VISION.md) - Codex-compatible spawn direction, backend policy, and phased roadmap. +- [Architecture Overview](architecture/OVERVIEW.md) - runtime shape, product tool surface, lifecycle, backend notes, and safety defaults. - [Project Boundary](architecture/PROJECT_BOUNDARY.md) - what Retinue is and is not. -- [OpenCode Backend](backends/OPENCODE.md) - OpenCode adapter behavior and constraints. +- [OpenCode Backend](backends/OPENCODE.md) - default backend behavior, auto-serve policy, access mode, diagnostics, and raw adapter surfaces. +- [Long-Term Vision](LONG_TERM_VISION.md) - Codex-compatible spawn direction, backend policy, and phased roadmap. +- [Documentation Governance](DOCUMENTATION_GOVERNANCE.md) - source-of-truth map, behavior-change update matrix, style rules, PR checklist, and archive policy. + +## Installation And Deployment + +- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging, installed plugin cache shape, local diagnostics, and production E2E boundary. +- [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) - daemon start, inspect, and stop workflow. - [Hermes Agent Integration](integrations/HERMES.md) - Hermes native MCP setup for calling Retinue/OpenCode. -## Deployment +## Development And Verification -- [Plugin Deployment](deployment/PLUGIN_DEPLOYMENT.md) - Codex plugin packaging and install shape. -- [Source Install And Development](development/SOURCE_INSTALL.md) - contributor setup and source-tree verification. +- [Source Install And Development](development/SOURCE_INSTALL.md) - contributor setup, source-tree verification, local gates, and probe commands. - [Plugin Reload Workflow](development/PLUGIN_RELOAD.md) - fast WSL/Windows cache sync during plugin development. -- [Service Lifecycle](deployment/SERVICE_LIFECYCLE.md) - daemon start, inspect, and stop workflow. - [Verification](VERIFICATION.md) - short test and packaging gates. ## Real Runtime Runbooks - [Production OpenCode E2E](runbooks/PRODUCTION_OPENCODE_E2E.md) -- [Real Claude Code Probes](runbooks/REAL_CLAUDE_PROBES.md) - [Real OpenCode Probes](runbooks/REAL_OPENCODE_PROBES.md) +- [Real Claude Code Probes](runbooks/REAL_CLAUDE_PROBES.md) + +## Release Records + +- [0.1.0 Release Readiness](release/0.1.0_RELEASE_PLAN.md) - release boundary, closed work, release gate, and deferred issues. +- [0.1.0 Hardening Record](release/0.1.0_HARDENING_ISSUES.md) - closed smoke/E2E issues and current verification requirements. +- [v0.1.0 Release Notes](release/v0.1.0_RELEASE_NOTES.md) - user-facing release summary. +- [v0.1.0 Release Notes zh-CN](release/v0.1.0_RELEASE_NOTES.zh-CN.md) - Chinese reference. -## Archive +## Archive And Research - [Verification History](archive/VERIFICATION_HISTORY.md) - [PR #58 Static Review](archive/PR58_STATIC_REVIEW.md) - [Repository Metadata Notes](archive/REPOSITORY_METADATA.md) -Implementation plans and research notes remain under `docs/superpowers/` and `docs/research/`. +Implementation plans and research notes remain under `docs/superpowers/` and `docs/research/`. They are not current product guidance unless this index explicitly promotes them into the sections above. From 7485cbecb7ee9532e978060fca9eab486e9dd28c Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Sat, 16 May 2026 11:16:22 +0800 Subject: [PATCH 4/5] docs: link architecture and governance from zh readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f3953e45..a88c152a 100644 --- a/README.md +++ b/README.md @@ -195,10 +195,12 @@ pnpm run probe:hermes-retinue ## 开发者文档 - [源码安装和开发](docs/development/SOURCE_INSTALL.md) +- [架构总览](docs/architecture/OVERVIEW.md) - [0.1.0 Release Notes](docs/release/v0.1.0_RELEASE_NOTES.md) - [0.1.0 发布说明（中文）](docs/release/v0.1.0_RELEASE_NOTES.zh-CN.md) - [0.1.0 发布就绪记录](docs/release/0.1.0_RELEASE_PLAN.md) - [Docs Index](docs/README.md) +- [文档治理](docs/DOCUMENTATION_GOVERNANCE.md) - [Long-Term Vision](docs/LONG_TERM_VISION.md) - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md) - [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md) From 65c42ad00d749b60f09c2d39e5455e599e8ece9c Mon Sep 17 00:00:00 2001 From: raystorm <2557058999@qq.com> Date: Sat, 16 May 2026 11:17:11 +0800 Subject: [PATCH 5/5] docs: link architecture and governance from en readme --- README.en.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.en.md b/README.en.md index 4dcbc825..f6c5d1c1 100644 --- a/README.en.md +++ b/README.en.md @@ -196,10 +196,12 @@ pnpm run probe:hermes-retinue ## Developer Docs - [Source install and development](docs/development/SOURCE_INSTALL.md) +- [Architecture overview](docs/architecture/OVERVIEW.md) - [0.1.0 Release Notes](docs/release/v0.1.0_RELEASE_NOTES.md) - [0.1.0 Release Notes zh-CN](docs/release/v0.1.0_RELEASE_NOTES.zh-CN.md) - [0.1.0 Release Readiness](docs/release/0.1.0_RELEASE_PLAN.md) - [Docs index](docs/README.md) +- [Documentation governance](docs/DOCUMENTATION_GOVERNANCE.md) - [Long-Term Vision](docs/LONG_TERM_VISION.md) - [Project Boundary](docs/architecture/PROJECT_BOUNDARY.md) - [Service Lifecycle](docs/deployment/SERVICE_LIFECYCLE.md)