# 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 , 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 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 "", 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 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): 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 voluntary, clean session handoff. At 80% utilization a fresh handoff-write becomes MANDATORY: it records the goal context and prepares the handoff record, but a successful write does NOT mandate an immediate new session -- keep working. After a verified auto-compaction, exactly one turn MANDATES a handoff-read to resume from the prepared handoff. 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 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 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 `` 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 ``. - 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`.