docs(governance): personal squad awareness in squad.agent.md (#508)

.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.

.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

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)

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