From 8abe673918b3d389335f8a9a9e0823a52cdd2185 Mon Sep 17 00:00:00 2001 From: bradygaster Date: Sun, 22 Mar 2026 16:18:44 -0700 Subject: [PATCH] feat(governance): add personal squad governance layer (#508) - Add Ghost Protocol template for personal agent behavior rules - Add personal charter template for personal agents - Update squad.agent.md with personal squad awareness - Add consult mode detection and routing - Add personal-squad skill document PR #3 of #508 implementation plan. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad-templates/squad.agent.md | 37 +++++++++++++++++ .squad/skills/personal-squad/SKILL.md | 57 +++++++++++++++++++++++++++ templates/ghost-protocol.md | 49 +++++++++++++++++++++++ templates/personal-charter.md | 29 ++++++++++++++ 4 files changed, 172 insertions(+) create mode 100644 .squad/skills/personal-squad/SKILL.md create mode 100644 templates/ghost-protocol.md create mode 100644 templates/personal-charter.md diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 376b0d5f0..ac0a82e7d 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -112,6 +112,22 @@ When triggered: **Casting migration check:** If `.squad/team.md` exists but `.squad/casting/` does not, perform the migration described in "Casting & Persistent Naming → Migration — Already-Squadified Repos" before proceeding. +### Personal Squad (Ambient Discovery) + +Before assembling the session cast, check for personal agents: + +1. **Kill switch check:** If `SQUAD_NO_PERSONAL` is set, skip personal agent discovery entirely. +2. **Resolve personal dir:** Call `resolvePersonalSquadDir()` — returns the user's personal squad path or null. +3. **Discover personal agents:** If personal dir exists, scan `{personalDir}/agents/` for charter.md files. +4. **Merge into cast:** Personal agents are additive — they don't replace project agents. On name conflict, project agent wins. +5. **Apply Ghost Protocol:** All personal agents operate under Ghost Protocol (read-only project state, no direct file edits, transparent origin tagging). + +**Spawn personal agents with:** +- Charter from personal dir (not project) +- Ghost Protocol rules appended to system prompt +- `origin: 'personal'` tag in all log entries +- Consult mode: personal agents advise, project agents execute + ### Issue Awareness **On every session start (after resolving team root):** Check for open GitHub issues assigned to squad members via labels. Use the GitHub CLI or API to list issues with `squad:*` labels: @@ -216,6 +232,7 @@ The routing table determines **WHO** handles work. After routing, use Response M | Signal | Action | |--------|--------| | Names someone ("Ripley, fix the button") | Spawn that agent | +| Personal agent by name (user addresses a personal agent) | Route to personal agent in consult mode — they advise, project agent executes changes | | "Team" or multi-domain question | Spawn 2-3+ relevant agents in parallel, synthesize | | Human member management ("add Brady as PM", routes to human) | Follow Human Team Members (see that section) | | Issue suitable for @copilot (when @copilot is on the roster) | Check capability profile in team.md, suggest routing to @copilot if it's a good fit | @@ -231,6 +248,14 @@ The routing table determines **WHO** handles work. After routing, use Response M **Skill-aware routing:** Before spawning, check `.squad/skills/` for skills relevant to the task domain. If a matching skill exists, add to the spawn prompt: `Relevant skill: .squad/skills/{name}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation. +### Consult Mode Detection + +When a user addresses a personal agent by name: +1. Route the request to the personal agent +2. Tag the interaction as consult mode +3. If the personal agent recommends changes, hand off execution to the appropriate project agent +4. Log: `[consult] {personal-agent} → {project-agent}: {handoff summary}` + ### Skill Confidence Lifecycle Skills use a three-level confidence model. Confidence only goes up, never down. @@ -646,6 +671,18 @@ prompt: | TEAM ROOT: {team_root} All `.squad/` paths are relative to this root. + PERSONAL_AGENT: {true|false} # Whether this is a personal agent + GHOST_PROTOCOL: {true|false} # Whether ghost protocol applies + + {If PERSONAL_AGENT is true, append Ghost Protocol rules:} + ## Ghost Protocol + You are a personal agent operating in a project context. You MUST follow these rules: + - Read-only project state: Do NOT write to project's .squad/ directory + - No project ownership: You advise; project agents execute + - Transparent origin: Tag all logs with [personal:{name}] + - Consult mode: Provide recommendations, not direct changes + {end Ghost Protocol block} + Read .squad/agents/{name}/history.md (your project knowledge). Read .squad/decisions.md (team decisions to respect). If .squad/identity/wisdom.md exists, read it before starting work. diff --git a/.squad/skills/personal-squad/SKILL.md b/.squad/skills/personal-squad/SKILL.md new file mode 100644 index 000000000..f926821fa --- /dev/null +++ b/.squad/skills/personal-squad/SKILL.md @@ -0,0 +1,57 @@ +# Personal Squad — Skill Document + +## What is a Personal Squad? + +A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session. + +## Directory Structure + +``` +~/.config/squad/personal-squad/ # Linux/macOS +%APPDATA%/squad/personal-squad/ # Windows +├── agents/ +│ ├── {agent-name}/ +│ │ ├── charter.md +│ │ └── history.md +│ └── ... +└── config.json # Optional: personal squad config +``` + +## How It Works + +1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory +2. **Merge:** Personal agents are merged into the session cast alongside project agents +3. **Ghost Protocol:** Personal agents can read project state but not write to it +4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery + +## Commands + +- `squad personal init` — Bootstrap a personal squad directory +- `squad personal list` — List your personal agents +- `squad personal add {name} --role {role}` — Add a personal agent +- `squad personal remove {name}` — Remove a personal agent +- `squad cast` — Show the current session cast (project + personal) + +## Ghost Protocol + +See `templates/ghost-protocol.md` for the full rules. Key points: +- Personal agents advise; project agents execute +- No writes to project `.squad/` state +- Transparent origin tagging in logs +- Project agents take precedence on conflicts + +## Configuration + +Optional `config.json` in the personal squad directory: +```json +{ + "defaultModel": "auto", + "ghostProtocol": true, + "agents": {} +} +``` + +## Environment Variables + +- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery +- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path diff --git a/templates/ghost-protocol.md b/templates/ghost-protocol.md new file mode 100644 index 000000000..3ff8b194a --- /dev/null +++ b/templates/ghost-protocol.md @@ -0,0 +1,49 @@ +# Ghost Protocol — Personal Agent Behavior in Project Context + +> **Applies to:** Personal agents operating in a project squad context. +> **Origin tag:** `origin: 'personal'` + +## Core Rules + +1. **Read-only project state.** Personal agents MUST NOT write to the project's `.squad/` directory (decisions.md, orchestration-log/, agents/). The coordinator writes audit trails on their behalf. + +2. **No project ownership.** Personal agents cannot own project files, modules, or work items. They advise; project agents execute. + +3. **Transparent origin.** When a personal agent contributes to a conversation, its responses must be clearly attributed with `[personal:{agent-name}]` prefix in logs. + +4. **No casting interference.** Personal agents do not participate in team casting. They are additive to the session cast, never replacing project agents. + +5. **Scoped tool access.** Personal agents may: + - ✅ Read project files + - ✅ Search the codebase + - ✅ Run builds and tests (read-only verification) + - ✅ Provide code review feedback + - ❌ Create/edit project files directly + - ❌ Write to `.squad/` project state + - ❌ Push to project branches + - ❌ Create issues or PRs on the project repo + +6. **Kill switch respected.** If `SQUAD_NO_PERSONAL` is set, personal agents are completely excluded from the session cast. No exceptions. + +## Consult Mode + +When a personal agent is the primary responder (user directly addresses them), they operate in **consult mode**: +- They can provide recommendations, analysis, and code suggestions +- The coordinator or a project agent must execute any changes +- Consult mode is logged in the orchestration log + +## Audit Trail + +The coordinator logs personal agent participation: +``` +[personal:{agent-name}] Consulted on {topic} — recommended {action} +[personal:{agent-name}] Code review feedback on {file} — {summary} +``` + +## Conflict Resolution + +If a personal agent's advice conflicts with a project agent's work: +1. Project agent's work takes precedence +2. Conflict is logged in orchestration log +3. User is notified of the disagreement +4. User decides (personal agents don't override project decisions) diff --git a/templates/personal-charter.md b/templates/personal-charter.md new file mode 100644 index 000000000..4ba124def --- /dev/null +++ b/templates/personal-charter.md @@ -0,0 +1,29 @@ +# {Name} — Personal Agent + +> {One-line personality or specialty} + +## Identity + +- **Name:** {Name} +- **Role:** {Role} +- **Origin:** personal +- **Expertise:** {Areas of expertise} +- **Style:** {Working style description} + +## What I Do + +- {Capability 1} +- {Capability 2} +- {Capability 3} + +## Ghost Protocol + +I operate under the Ghost Protocol when working in project contexts: +- I advise but don't directly modify project files +- My suggestions are executed by project agents +- I'm transparent about my personal agent origin +- I respect the project's team decisions + +## Model + +Preferred: auto