Skip to content

Starter agent organization and Claude Code subagent generator - #86

Merged
Akilleez-QA merged 3 commits into
mainfrom
feat/starter-agents
Nov 17, 2026
Merged

Akilleez-QA merged 3 commits into
mainfrom
feat/starter-agents

Conversation

@Akilleez-QA

Copy link
Copy Markdown
Owner

Change

Wave 1C: serve the pinned Foundations as read-only MCP tools for an agent ("Sage" or any other) in one bot's AOR, so domain answers come with their receipts and every call is a witnessed POODO decision.

tools/foundations_mcp.py --aor <slug> --foundation <name> ... launches adapters/foundations_mcp.py, an MCP stdio server that:

  • lists <foundation>.<tool> (for example refrigeration.saturation_pressure) for each Foundation the host named at launch that the bot's AOR does not deny, with input schemas from the pinned tool inventories. A request cannot add a Foundation; an unregistered name, a runtime such as cstack_forge, a repeat or an empty choice stops the launch;
  • checks arguments against the exact pinned input schema before any decision, so malformed input never spends budget or writes the ledger;
  • runs every other call through the bot's AorSession: a standing POODO goal per Foundation, host-authored checkpoints, a precommitted decision on the read-only ToolFace grant, then execution through the existing pinned adapter (manifest verified, live inventory pinned and, for the shared adapter, receipt input digest recomputed);
  • returns the Foundation's isError and structuredContent (receipt, evidence, boundary flags) unchanged, with the POODO record in _meta["cstack/poodo"]. CHECK values and the evidence ceiling are never rewritten. A refused, tampered, unadmitted, pending or over-budget call is a tool error; nothing is retried.

Rationale.

  • Reuse, not a second setup: build_aor_session gains an optional foundations subset, so cores, grants, witnessed ledgers, approvals and shields are the ones tools/cstack_mcp.py already uses. The server subclasses McpServer for framing and strict parsing; the only change there is that McpServer.INSTRUCTIONS became a class attribute (same text).
  • A top-level allOf/oneOf/anyOf (math.exact_scalar, robotics.mechanism_check) is merged into one object schema in tools/list, because some clients reject top-level combinators; the server still validates against the exact schema.
  • An Engine result that is not an object is returned as text only, because MCP structuredContent must be an object.
  • No core change.

Requirements, design and interface impact

  • Requirements added: CS-REQ-091 (Foundations MCP server), Baselined. The id sits deliberately above the ids other in-flight branches use (078, 080 to 082, 084 to 086), so the branches don't collide on merge.
  • SDD: new component SDD-C31 (chosen above the in-flight C25, C26, C28) and a flowchart edge. ICD: new "Foundations MCP interface" section in docs/icd/icd-foundations.md; pointer in contracts/INTERFACES.md. contracts/ADAPTERS.json: two rows (foundations-mcp-server, foundations-mcp-launcher), checked by tests/test_adapter_inventory.py.
  • Verification matrix updated: yes, one row against tests/test_foundations_mcp.py.
  • Small edits to shared files (bootstrap.py, adapters/mcp_stdio_server.py, ADAPTERS.json, requirements/verification docs), because feat/handoff-channel and feat/cstack-init edit the same files.

Verification

These ran on the head commit 54e2a9d on macOS with Python 3.15 in a throwaway venv (ci/requirements.txt installed). No model calls were made and no credentials were set.

  • python -B -m unittest discover -s tests: Ran 746, failures=76, errors=4, skipped=8. main at 0a9703b, same machine: Ran 734, failures=76, errors=4, skipped=8. The failing tests are identical on both (diffed). They are the known macOS workcell/EndoForge failures (workcell_not_executed) plus the tests that need npm ci for the workcell toolchain, which was not run. All 12 new tests pass. Linux CI is the authority.
  • bash ci/run-local.sh python links trace: suite results as above; check_links 1442 paths, 0 broken; check_trace 78 requirements, 77/77 test files traced, 0 failures.
  • gitleaks / TruffleHog: not run locally (not installed); the CI job runs them. I scanned the diff by hand for personal data, hosts and secrets and found none. All test inputs are synthetic.

New tests (tests/test_foundations_mcp.py): the tool list matches the pinned schemas; each vendored Foundation's representative tool is called over the real pinned bridges and its receipt comes back unchanged; unknown tool returns invalid params; malformed input never reaches the core; an out-of-profile number is refused before dispatch; the host chooses the Foundations; unknown, empty or repeated choices are refused; a denied domain lists nothing; an ask-class call waits for the owner; a tampered manifest is refused; the stdio launcher lists and calls; an unregistered Foundation stops the launch.

Not done

  • No session from a real MCP client or agent host (Claude Code subagent for Sage) is recorded. The tests use the in-process server and a minimal stdio client.
  • One session allows 64 calls per Foundation (the existing read grant budget).
  • With a witnessed ledger, this server and tools/cstack_mcp.py cannot both hold the same bot and domain at once (the existing lifetime store claim).
  • No STR regenerated; the matrix row says "Not yet in a recorded run".

Peer review record

  • Reviewers: none yet. An agent wrote this, so a review by another agent would not be independent.
  • Review type: code / docs / requirements / design
  • Findings: none recorded
  • Outcome: awaiting review. Draft: do not merge without the owner.

Checklist

  • One concern; about 400 changed lines maximum. (491 added, 5 removed. About 215 of the added lines are tests.)
  • No code comments added. The only # noqa: E402 markers follow the existing launcher pattern in tools/cstack_mcp.py.
  • Expected test results unchanged.
  • AI assistance disclosed: written by Claude Code.
  • Docs whose derivation paths this PR touches are updated.

🤖 Generated with Claude Code

Cstack and others added 3 commits November 16, 2026 23:37
Nine named starter agents (Chief, Scribe, Oracle, Sage, Smith, Warden,
Lab, Keeper, Archivist) in an engine-neutral definition format
(contracts/agent.schema.json), each with an AOR in aors/fleet.json, a
single-writer hand-off table and concurrency policy (agents/org.json),
shared expert practice (agents/PRACTICE.md) and six generic area-of-life
templates.

tools/agent_profiles.py now writes Claude Code project subagents to
.claude/agents/ with tools, permissionMode, mcpServers and a PreToolUse
guard hook (tools/agent_guard.py) derived from each AOR, so effects hold
outside MCP. --check fails on drift, undeclared fields and targets that
would drop wiring (plugins). The unread .agent/ output and mcpInheritance
are removed.

POODO's twenty-option rule is fixed in every definition (options 20,
research gate required); only research and red-team effort varies.
tools/check_options.py rejects options records without twenty options,
missing kinds, shared mechanisms or near-duplicates.

CS-REQ-080 to CS-REQ-083, SDD-C26.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in #84 (Foundations MCP server) and #85 (cstack init, durable
ledger required in agent mode). Conflicts in CHANGELOG.md,
docs/architecture/architecture.md and docs/guides/how-to/define-bots.md
resolved by keeping both sides' entries; EXPORT-MANIFEST.json
regenerated with tools/build_export_manifest.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#85 added test_generated_bot_profiles_never_allow_the_memory_ledger
against the old agent_profiles.build(fleet, root, uv, state_root). This
branch replaced that with build(repo, target) -> (files, problems), so
the test raised TypeError after merging main. The test now checks every
generated subagent for every target, plus server_args and cstack_server,
for --allow-memory-ledger. No generator behaviour changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Akilleez-QA
Akilleez-QA marked this pull request as ready for review November 17, 2026 07:45
@Akilleez-QA
Akilleez-QA merged commit 9cd1a49 into main Nov 17, 2026
2 checks passed
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
Brings in #84 (Foundations MCP server), #85 (cstack init) and #86
(starter agents). Conflicts in docs/architecture/architecture.md and
docs/requirements/requirements.md resolved by keeping both sides:
component rows in SDD order (C26, C28, C29, C31) and requirements
CS-REQ-084 to CS-REQ-086 before CS-REQ-087. EXPORT-MANIFEST.json
regenerated with tools/build_export_manifest.py; data dictionary
--check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant