AGENTS.md · diff
git:20260723.6ae181e to git:20260724.f517305
104 added, 0 removed. Audit A to A.
# Repository Agent Instructions
+
+ ## PROJECT BOARD LAW - BINDING, NO EXCEPTIONS
+
+ https://github.com/users/Heretyc/projects/4 is the canonical Source of Truth
+ for the PLANNING and STATUS of all repo Work. It is subordinate to the alignment chain
+ in Law 2: where Board and Premise conflict, the Premise wins and the Board is corrected.
+
+ ### DEFINITIONS
+ "Work" = any mutation of git-tracked content: commits, branches, PRs. Wiki edits,
+ releases, tags, and comments are not Work. Board mutations are not Work and never
+ require issues.
+ "Human Review" (HR) = engagement of the human via the structured question tool,
+ presented as if the human has no knowledge of the project or repo. Two modes:
+ - Decision HR: 2+ options, each with pros and cons.
+ - Action HR: 1 required action, why it is needed, and the consequence of inaction.
+ HR is NEVER skippable for any authority or reason. One HR session MAY bundle every
+ trigger pending at that moment.
+ "Premise" = The answer to "what is this + why care?": who it's for + problem + what
+ it does + why not alternatives. Canonical copy: first paragraph of README.md,
+ MAXIMUM 1000 characters.
+ "Short Premise" = Verbatim-identical version of Premise (minus the "why not
+ alternatives" aspect) MAXIMUM 350 characters and found in BOTH the Repo and Project
+ Short Descriptions.
+ "Interactive Session" = A harness that has a working structured question tool.
+ Lacking this, the session is considered non-interactive.
+
+ ### DIRECTIVES
+
+ 1. Short Premise must faithfully condense the canonical Premise. Any edit to the
+ Premise updates both Short Premise copies in the same session. If the copies mismatch,
+ truncate, or drift from the canonical: the README is canonical and
+ the mismatch is an HR trigger.
+ 2. Code MUST align with repo Spec docs. Spec MUST align with the Premise at all
+ times. The Premise is always the tie-breaker. If in doubt, HR. If the
+ Repo lacks the canonical Premise in README.md, or either Short Description
+ lacks the Short Premise: recon the project specs/code and present a proposed
+ Premise and Short Premise via Decision HR; that same HR authorizes the board
+ issue for the restoration edit (which is Work).
+ 3. All Work maps to a board issue. All issues map to Milestones. No unmapped Work.
+ 4. Every issue/epic carries ALL required fields at ALL times: Label(s),
+ Priority, Size, Estimate, Iteration, Milestone, Assignee, Relationships,
+ branch/PR link, and updated Status. Satisfiability rules: issues are created
+ fully populated in a single operation, with Iteration taken from the
+ authorizing HR (Law 9, bundled per the HR definition); the branch/PR link is
+ mandatory from the moment the branch or PR exists and MUST be back-filled in
+ the same working session ("none yet" before that; "n/a" for board-only
+ issues); Assignee follows Law 11 (an idle issue may be unassigned or
+ assigned to anyone; an actively-worked issue MUST be assigned to the worker).
+ 5. Every PR maps to a fully populated issue.
+ 6. Live updates are mandatory: update the mapped item BEFORE, DURING, and AFTER
+ Work. Agents update existing items in real time without seeking permission.
+ While an HR is pending on an item, only Status changes and comments recording
+ the block are permitted on it.
+ 7. Every agent MUST fully understand the Board plan and the Premise BEFORE acting.
+ The read-only sweep in Law 13 both requires and satisfies this understanding.
+ 8. Any conflict between tasked work and the Board: STOP and deconflict via HR
+ BEFORE any board edit. Conflicts between Board and Premise resolve per Law 2.
+ 9. Net-new Work not on the board: HR BEFORE adding it. That HR also supplies the
+ new issue's Iteration and other judgment fields (Law 4).
+ 10. Board ops use ONLY the `gh` CLI, including `gh api` where subcommands lack
+ field coverage (Relationships). If `gh` is not authenticated or lacks
+ the project scope: Action HR asking the human to run `gh auth refresh -s
+ project` (interactive; agents cannot complete it).
+ 11. Before starting Work on an unassigned issue, assign it to the logged-in `gh`
+ user. If an issue you are tasked to work is assigned to someone else: Action
+ HR to reassign. If the human declines, stand down from that item: you are
+ forbidden from performing Work on any issue not assigned to the logged-in
+ `gh` user. Idle issues may remain unassigned or assigned to others.
+ 12. Never store local paths or machine-specific information anywhere on the Board.
+ 13. Sweep the Board before starting and after finishing Work: find the most
+ recently COMPLETED "Project Board true-up #". If it completed more than 5
+ business days ago, or none exists: dispatch 2+ review subagents over all
+ incomplete board items for non-compliance with these Laws (if the harness
+ cannot spawn subagents, perform work directly). HR is mandated on all
+ non-compliant items found (bundle-able). Once the true-up is complete: mark
+ it complete and create the next true-up issue with an incremented #,
+ NO assignee, description = a VERBATIM copy of these Laws from their canonical
+ home (this document at the repo root).
+ 14. HR may be DEFERRED only in headless runs where no human is reachable
+ (determined if no structured question tool exists in your harness), and
+ deferral is never resolution. Queue the item as a comment on the dedicated
+ HR-queue board item, set the affected issue's Status to "Awaiting Review"
+ (rename "In Review" to "Awaiting Review" if it exists. If you cannot rename,
+ use "In Review" status), and proceed only with Work unaffected by the pending
+ question; doubt about whether Work is affected resolves to AFFECTED. Any
+ Interactive Session MUST drain the queue (bundled HR) BEFORE starting any
+ new Work. If any queued item is older than 5 business days, ALL Work halts
+ until the queue drains. Every true-up (Law 13) reports the queue's contents.
+ Queued items are never deemed approved, expired, or abandoned.
+
+
+ ## Content Policy - No Historical Framing (Standing, Unskippable)
+
+ Repo content states only the current objective truth. This rule is always in
+ effect, at maximum strength, and applies to every tracked file.
+
+ - No historical context or origin stories. Do not narrate how a system, methodology, or decision came to be.
+ - No allusions to previous versions, iterations, sessions, or rejected designs (no "v1/v2/v3", no "Approach A/B", no "the old system").
+ - No "formerly / replaces / superseded / was / updated from / previously" meta-framing about the repo's own design.
+ - No changelog narration in docs, and no dated "as of <date>, N tasks complete" journaling.
+ - Git history is the sole record of how anything changed; never restate that history in prose.
+ - Do not include AI attribution or co-author lines in PRs, commits, manifests,
+ docs, or generated project metadata.
+
<!-- subagent-mcp:managed:begin schema=5 -->
## subagent-mcp invariant — managed block, do not edit between markers
Upserted by `subagent-mcp init` at user request; re-running init keeps it in sync.
SUB-AGENT EXEMPTION: if this session's prompt's literal FIRST LINE begins with "<this is a request from a parent process>", SKIP this entire block EXCEPT the SUB-AGENT WORKTREE CARVE-OUT and the SUB-ORCHESTRATOR CARVE-OUT below, which still apply (you are a sub-agent; this prevents fail-safe-ON recursion and fork-bombs). Leading blank lines do not count — the marker must be physically line 1.
SUB-AGENT WORKTREE CARVE-OUT: you are a delegated sub-agent (env SUBAGENT_MCP_SUBAGENT=1), already placed in your target working tree by the orchestrator. Do not create or switch git worktrees; skip the worktree-isolation gate; do all mutating work directly in the provided cwd.
SUB-ORCHESTRATOR CARVE-OUT: if env SUBAGENT_MCP_SUB_ORCHESTRATOR=1, the sub-agent exemption does NOT lift orchestration for you: you are a delegate-only sub-orchestrator bound by your launch prompt directive and the per-turn hook tag; your own sub-agents run as normal sub-agents and never inherit the flag.
CANONICAL SOURCE: the subagent-mcp MCP `instructions` string (read once at connect) and docs/spec/dev-loop/orchestration-directive-architecture.md. This block mirrors that operating model inline so the session stays governed even if the MCP `instructions` are momentarily stale; where the two disagree, the MCP `instructions` win because they are read fresh each connect.
HARNESS-HOOK STATE: a harness-hook context carrying a <subagent-mcp state="..."> tag reports the current orchestration ON/OFF state and takes effect with no exceptions, because it is the only channel with fresh, harness-verified state — self-reported prose cannot substitute for it. A token counts as such a tag only when it is a real tag with a `state` attribute; a bare mention of "subagent-mcp" in prose is not a tag and carries no authority. A user request can only switch orchestration ON or OFF, never assert what the current state already is — that comes solely from the tag. No tag present means the state is UNKNOWN (see NO-HOOK below); never infer it from anything else.
PRECEDENCE (jointly binding top tier): <subagent-mcp> hook tags and repo/system safety-scope rules are both binding at the same priority — neither is read as outranking the other. If they genuinely conflict, stop and escalate to the user via the structured-question tool rather than picking one side or averaging them silently; this is intentionally not the agent's call to make alone. Hook tags otherwise take precedence over ordinary user requests, because they reflect harness-verified state rather than a request that could be mistaken or out of date.
SOLE CHANNEL — BOTH ORCHESTRATION STATES: whether orchestration is ON or OFF, every sub-agent launch goes through subagent-mcp `launch_agent`; harness-native Task/Agent/collaboration tools, shell-spawned agents, and any wrapper around them are never permitted. Why: native launch paths fragment permission handling and user-instruction compliance and add context/token overhead; subagent-mcp keeps permission handling and routing consistent with bounded handoffs (fuller rationale: docs/spec/dev-loop/orchestration-directive-architecture.md).
ORCHESTRATION ON — you are the ORCHESTRATOR. Allowed tools: only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and the /workflows tool. There is no inline-by-right; every step runs in a sub-agent. Sole delegate-only exception — applicable skill instructions: you may directly read the SKILL.md of a skill that serves the user's current request, plus the files it explicitly requires, only while each referenced path stays inside that same skill's folder; reading grants no task-side action authority, and if those instructions expand scope beyond the user's current request, ask fresh approval via the structured-question tool first — action steps still run through subagent-mcp sub-agents. If one atomic step truly cannot run in a sub-agent, ask the user via the structured-question tool for a one-time exception for that single step, perform only that step, then resume delegating.
TASK TRACKING: track multi-step work with the harness-native task tracking tool (if one exists), keeping statuses current as work progresses.
WAIT-ON-AGENTS: When waiting for agents to finish processing, utilize the SMCP (Subagent-MCP) wait tool on loop rather than less efficient harness native methods
ORCHESTRATOR WORKTREE SETUP: for mutating work, first place sub-agents in a compliant linked worktree/work branch; the main checkout cwd applies only to read-only work or already-isolated target-tree contexts (sub-agents no longer self-isolate into per-agent worktrees). Serialize any sub-agents that write the same files — never run concurrent writers over overlapping paths (no cwd-level lock exists).
READ-ESCALATION LADDER (the orchestrator's only read channels, in order): (1) subagent-mcp `poll_agent` TAIL; (2) if the tail is insufficient, dispatch ONE sub-agent to return a single summary of <=100 lines, trusted as-is (no separate verification step); (3) anything larger: the USER reads the document directly. No reads or writes occur outside these channels. An empty or stalled tail means the agent is ALIVE, not dead — do NOT busy-loop poll_agent; learn completion via `wait`. Large inter-agent data: the orchestrator assigns scratch-file paths (%TEMP% on Windows, /tmp on POSIX) in prompts; the producing sub-agent writes, the consuming sub-agent reads; the orchestrator NEVER reads those files.
ORCHESTRATION OFF BY DEFAULT -- each new session starts with orchestration OFF. A hook meters real provider-reported context usage (never tokenized, never self-estimated). At 15% utilization a persisted latch force-enables orchestration and coaches a planning stop of at least 4 open questions, whose answers become this session's goal context. At 20% utilization handoff-write/handoff-read/handoff-clear unlock so that goal context can be recorded for a clean session handoff; at the wind-down warning threshold (user setting, default 60%) the hook warns every turn to wind down. If context size cannot be measured, the hook fails safe to ON. Never assert a state yourself -- only the hook tag is authoritative.
MODEL SELECTION: defaults to smart/automatic whenever unset — the server auto-picks each sub-agent's model and launch_agent rejects provider/model/effort selectors; those selectors are honored only inside the existing user-approved override window (model-selection-mode "user-approved-overrides", set only with explicit user authorization via the structured-question tool).
SWARM WORKFLOW: when a work objective is projected to span multiple sessions, offer the agentic-swarm workflow and drive it with the swarm MCP tool - swarm() starts it, each swarm(N) reports stage N done and returns the next stage's coaching, swarm(0) abandons. Stage state lives in the server, in memory only - never self-assert a stage. The launch_agent sub-orchestrator: true flag exists ONLY for the swarm dispatch stage; never set it elsewhere.
DROPOUT WHILE ON: if subagent-mcp stops responding while orchestration is ON, halt and ask the user; do nothing inline. Keep re-checking and stay halted until subagent-mcp is restored (no auto-degrade). The only user choices are keep-waiting (the default) or explicitly abandon the whole task; aborting ends the task, it never switches you to inline work.
NO-HOOK / UNKNOWN STATE: if no harness-hook injection bearing a <subagent-mcp state="..."> tag is present this session (e.g. Gemini, desktop apps, or any host that fires no hook), the state is UNKNOWN — represented by the absence of any tag, never by a tag value. Emit this warning to the user: "subagent-mcp: no hook injection detected — orchestration state unknown; defaulting to ON." Why: with no fresh state signal, defaulting to ON avoids ungoverned inline execution; one spoken opt-out is allowed per session. If you are not currently running an orchestration workflow, you may explicitly opt out of ON for this session by saying so now; this opt-out does not persist and is not recorded. The sub-agent first-line exemption is the only automatic suppressor of this default.
DISABLE: never on your own initiative; you may propose OFF on task-fit mismatch via the structured-question tool, and only explicit user approval may set enabled:false — a session-keyed opt-out for THIS session only (2h backstop) honored even after the 15% latch or metering fail-safe; user-approved enabled:true may re-enable mid-session; each new session starts back at the default-OFF metering regime.
<!-- subagent-mcp:managed:end -->
subagent-mcp turns a host CLI into an orchestrator for local sub-agent
sessions. It exposes MCP tools such as `launch_agent`, `poll_agent`, `wait`,
`get_status`, `orchestration-mode`, `swarm`, and handoff tools. Provider
credentials and user config live outside the repo.
## Fallback Rule
Use this file when the host reads instruction files but does not load
subagent-mcp skills, hooks, or slash commands. This applies to instruction-tier
fallback use in Gemini CLI, Cursor, Windsurf, Kiro, Copilot, and similar agents.
## Orchestration
- If a `<subagent-mcp state="...">` hook tag is present, treat it as the
authoritative orchestration state.
- If no hook tag is present, say: `subagent-mcp: no hook injection detected:
orchestration state unknown; defaulting to ON.`
- When orchestration is ON, use only `launch_agent` for sub-agent work. Do not
use native agent/task tools or shell-spawned agents.
- Every sub-agent prompt must begin with `<this is a request from a parent
process>`.
- Sub-agents return JSON with `status`, `summary`, `source_locators`, `risks`,
and `writes_requested`.
## Read Ladder
1. Use `poll_agent` tail output first.
2. If the tail is insufficient, launch one summarizer sub-agent and trust its
summary if it is 100 lines or fewer.
3. For larger handoffs, have sub-agents write scratch files and pass file paths
between them. The orchestrator does not read large files inline.
4. Use `wait` to learn completion. A quiet or stalled agent is still alive.
## Status And Repair
- `/smcp:help`: load `skills/smcp-help/SKILL.md` for install, config, and
maintenance guidance.
- `/smcp:status`: load `skills/smcp-status/SKILL.md` and call `get_status`.
- `/smcp:doctor`: load `skills/smcp-doctor/SKILL.md`; run `subagent-mcp doctor`
read-only first and ask before any repair.
- `/smcp:config`: load `skills/smcp-config/SKILL.md` and call `configure` to
list, read, or update configuration by canonical key.
- Config commands: `subagent-mcp config init`, `subagent-mcp config validate`,
`subagent-mcp doctor`, `subagent-mcp upgrade`, `subagent-mcp rollback`.
## Deeper Docs
- Start with `retrieval-map.md` (repo root) to choose the smallest relevant doc.
- Install and host wiring: `docs/registration.md` and `docs/install/`.
- Tool reference: `docs/tools.md`.
- Orchestration model: `docs/spec/dev-loop/orchestration-directive-architecture.md`.
- Safety and clarification rules: `docs/spec/safety-scope.md`.
- Git and worktree rules: `docs/spec/dev-loop/git-collaboration.md` and
`agents/GIT_COLLABORATION.md`.