From 2926645b10627236c06f76d6620f4dd84c0f3d1b Mon Sep 17 00:00:00 2001
From: teernisse <teernisse@visiostack.com>
Date: Thu, 26 Feb 2026 15:25:02 -0500
Subject: [PATCH] docs: add implementation plans for upcoming features

Planning documents for future AMC features:

PLAN-slash-autocomplete.md:
- Slash-command autocomplete for SimpleInput
- Skills API endpoint, SlashMenu dropdown, keyboard navigation
- 8 implementation steps with file locations and dependencies

plans/agent-spawning.md:
- Agent spawning acceptance criteria documentation
- Spawn command integration, status tracking, error handling
- Written as testable acceptance criteria (AC-1 through AC-10)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 PLAN-slash-autocomplete.md | 509 +++++++++++++++++++++
 plans/agent-spawning.md    | 910 +++++++++++++++++++++++++++++++++++++
 2 files changed, 1419 insertions(+)
 create mode 100644 PLAN-slash-autocomplete.md
 create mode 100644 plans/agent-spawning.md

diff --git a/PLAN-slash-autocomplete.md b/PLAN-slash-autocomplete.md
new file mode 100644
index 0000000..a96c41e
--- /dev/null
+++ b/PLAN-slash-autocomplete.md
@@ -0,0 +1,509 @@
+# Plan: Skill Autocomplete for Agent Sessions
+
+## Summary
+
+Add autocomplete functionality to the SimpleInput component that displays available skills when the user types the agent-specific trigger character (`/` for Claude, `$` for Codex). Autocomplete triggers at the start of input or after any whitespace, enabling quick skill discovery and selection mid-message.
+
+## User Workflow
+
+1. User opens a session modal or card with the input field
+2. User types the trigger character (`/` for Claude, `$` for Codex):
+   - At position 0, OR
+   - After a space/newline (mid-message)
+3. Autocomplete dropdown appears showing available skills (alphabetically sorted)
+4. User can:
+   - Continue typing to filter the list
+   - Use arrow keys to navigate
+   - Press Enter/Tab to select and insert the skill name
+   - Press Escape or click outside to dismiss
+5. Selected skill replaces the trigger with `{trigger}skill-name ` (e.g., `/commit ` or `$yeet `)
+
+## Acceptance Criteria
+
+### Core Functionality
+- **AC-1**: Autocomplete triggers when trigger character is typed at position 0 or after whitespace
+- **AC-2**: Claude sessions use `/` trigger; Codex sessions use `$` trigger
+- **AC-3**: Wrong trigger character for agent type is ignored (no autocomplete)
+- **AC-4**: Dropdown displays skill names with trigger prefix and descriptions
+- **AC-5**: Skills are sorted alphabetically by name
+- **AC-6**: Typing additional characters filters the skill list (case-insensitive match on name)
+- **AC-7**: Arrow up/down navigates the highlighted option
+- **AC-8**: Enter or Tab inserts the selected skill name (with trigger) followed by a space
+- **AC-9**: Escape, clicking outside, or backspacing over the trigger character dismisses the dropdown without insertion
+- **AC-10**: Cursor movement (arrow left/right) is ignored while autocomplete is open; dropdown position is locked to trigger location
+- **AC-11**: If no skills match the filter, dropdown shows "No matching skills"
+
+### Data Flow
+- **AC-12**: On session open, an agent-specific config is loaded containing: (a) trigger character (`/` for Claude, `$` for Codex), (b) enumerated skills list
+- **AC-13**: Claude skills are enumerated from `~/.claude/skills/`
+- **AC-14**: Codex skills are loaded from `~/.codex/vendor_imports/skills-curated-cache.json` plus `~/.codex/skills/`
+- **AC-15**: If session has no skills, dropdown shows "No skills available" when trigger is typed
+
+### UX Polish
+- **AC-16**: Dropdown positions above the input (bottom-anchored), aligned left
+- **AC-17**: Dropdown has max height with vertical scroll for long lists
+- **AC-18**: Currently highlighted item is visually distinct
+- **AC-19**: Dropdown respects the existing color scheme
+- **AC-20**: After skill insertion, cursor is positioned after the trailing space, ready to continue typing
+
+### Known Limitations (Out of Scope)
+- **Duplicate skill names**: If curated and user skills share a name, both appear (no deduplication)
+- **Long skill names**: No truncation; names may overflow if extremely long
+- **Accessibility**: ARIA roles, active-descendant, screen reader support deferred to future iteration
+- **IME/composition**: Japanese/Korean input edge cases not handled in v1
+- **Server-side caching**: Skills re-enumerated on each request; mtime-based cache could improve performance at scale
+
+## Architecture
+
+### Autocomplete Config Per Agent
+
+Each session gets an autocomplete config loaded at modal open:
+
+```typescript
+type AutocompleteConfig = {
+  trigger: '/' | '$';
+  skills: Array<{ name: string; description: string }>;
+}
+```
+
+| Agent | Trigger | Skill Sources |
+|-------|---------|---------------|
+| Claude | `/` | Enumerate `~/.claude/skills/*/` |
+| Codex | `$` | `~/.codex/vendor_imports/skills-curated-cache.json` + `~/.codex/skills/*/` |
+
+### Server-Side: New Endpoint for Skills
+
+**Endpoint**: `GET /api/skills?agent={claude|codex}`
+
+**Response**:
+```json
+{
+  "trigger": "/",
+  "skills": [
+    { "name": "commit", "description": "Create a git commit with a message" },
+    { "name": "review-pr", "description": "Review a pull request" }
+  ]
+}
+```
+
+**Rationale**: Skills are agent-global, not session-specific. The client already knows `session.agent` from state, so no session_id is needed. Server enumerates skill directories directly.
+
+### Component Structure
+
+```
+SimpleInput.js
+├── Props: sessionId, status, onRespond, agent, autocompleteConfig
+├── State: text, focused, sending, error
+├── State: showAutocomplete, selectedIndex
+├── Derived: triggerMatch (detects trigger at valid position)
+├── Derived: filterText, filteredSkills (alphabetically sorted)
+├── onInput: detect trigger character at pos 0 or after whitespace
+├── onKeyDown: arrow/enter/escape handling for autocomplete
+└── Render: textarea + autocomplete dropdown
+```
+
+### Data Flow
+
+```
+┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
+│   Modal opens   │────▶│ GET /api/skills?agent│────▶│   SimpleInput   │
+│   (session)     │     │   (server)           │     │   (dropdown)    │
+└─────────────────┘     └──────────────────────┘     └─────────────────┘
+```
+
+Skills are agent-global, so the same response can be cached client-side per agent type.
+
+## Implementation Specifications
+
+### IMP-1: Server-side skill enumeration (fulfills AC-12, AC-13, AC-14, AC-15)
+
+**Location**: `amc_server/mixins/skills.py` (new file)
+
+```python
+class SkillsMixin:
+    def _serve_skills(self, agent):
+        """Return autocomplete config for a session."""
+        if agent == "codex":
+            trigger = "$"
+            skills = self._enumerate_codex_skills()
+        else:  # claude
+            trigger = "/"
+            skills = self._enumerate_claude_skills()
+
+        # Sort alphabetically
+        skills.sort(key=lambda s: s["name"].lower())
+
+        self._send_json(200, {"trigger": trigger, "skills": skills})
+
+    def _enumerate_codex_skills(self):
+        """Load Codex skills from cache + user directory."""
+        skills = []
+
+        # Curated skills from cache
+        cache_file = Path.home() / ".codex/vendor_imports/skills-curated-cache.json"
+        if cache_file.exists():
+            try:
+                data = json.loads(cache_file.read_text())
+                for skill in data.get("skills", []):
+                    skills.append({
+                        "name": skill.get("id", skill.get("name", "")),
+                        "description": skill.get("shortDescription", skill.get("description", ""))[:100]
+                    })
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        # User-installed skills
+        user_skills_dir = Path.home() / ".codex/skills"
+        if user_skills_dir.exists():
+            for skill_dir in user_skills_dir.iterdir():
+                if skill_dir.is_dir() and not skill_dir.name.startswith("."):
+                    skill_md = skill_dir / "SKILL.md"
+                    description = ""
+                    if skill_md.exists():
+                        # Parse first non-empty line as description
+                        try:
+                            for line in skill_md.read_text().splitlines():
+                                line = line.strip()
+                                if line and not line.startswith("#"):
+                                    description = line[:100]
+                                    break
+                        except OSError:
+                            pass
+                    skills.append({
+                        "name": skill_dir.name,
+                        "description": description or f"User skill: {skill_dir.name}"
+                    })
+
+        return skills
+
+    def _enumerate_claude_skills(self):
+        """Load Claude skills from user directory.
+
+        Note: Checks SKILL.md first (canonical casing used by Claude Code),
+        then falls back to lowercase variants for compatibility.
+        """
+        skills = []
+        skills_dir = Path.home() / ".claude/skills"
+
+        if skills_dir.exists():
+            for skill_dir in skills_dir.iterdir():
+                if skill_dir.is_dir() and not skill_dir.name.startswith("."):
+                    # Look for SKILL.md (canonical), then fallbacks
+                    description = ""
+                    for md_name in ["SKILL.md", "skill.md", "prompt.md", "README.md"]:
+                        md_file = skill_dir / md_name
+                        if md_file.exists():
+                            try:
+                                content = md_file.read_text()
+                                # Find first meaningful line
+                                for line in content.splitlines():
+                                    line = line.strip()
+                                    if line and not line.startswith("#") and not line.startswith("<!--"):
+                                        description = line[:100]
+                                        break
+                                if description:
+                                    break
+                            except OSError:
+                                pass
+
+                    skills.append({
+                        "name": skill_dir.name,
+                        "description": description or f"Skill: {skill_dir.name}"
+                    })
+
+        return skills
+```
+
+### IMP-2: Add skills endpoint to HttpMixin (fulfills AC-12)
+
+**Location**: `amc_server/mixins/http.py`
+
+```python
+# In HttpMixin.do_GET, add route handling:
+elif path == "/api/skills":
+    agent = query_params.get("agent", ["claude"])[0]
+    self._serve_skills(agent)
+```
+
+**Note**: Route goes in `HttpMixin.do_GET` (where all GET routing lives), not `handler.py`. The handler just composes mixins.
+
+### IMP-3: Client-side API call (fulfills AC-12)
+
+**Location**: `dashboard/utils/api.js`
+
+```javascript
+export const API_SKILLS = '/api/skills';
+
+export async function fetchSkills(agent) {
+  const url = `${API_SKILLS}?agent=${encodeURIComponent(agent)}`;
+  const response = await fetch(url);
+  if (!response.ok) return null;
+  return response.json();
+}
+```
+
+### IMP-4: Autocomplete config loading in Modal (fulfills AC-12)
+
+**Location**: `dashboard/components/Modal.js`
+
+```javascript
+const [autocompleteConfig, setAutocompleteConfig] = useState(null);
+
+// Load skills when agent type changes
+useEffect(() => {
+  if (!session) {
+    setAutocompleteConfig(null);
+    return;
+  }
+
+  const agent = session.agent || 'claude';
+  fetchSkills(agent)
+    .then(config => setAutocompleteConfig(config))
+    .catch(() => setAutocompleteConfig(null));
+}, [session?.agent]);
+
+// Pass to SimpleInput
+<${SimpleInput}
+  ...
+  autocompleteConfig=${autocompleteConfig}
+/>
+```
+
+### IMP-5: Trigger detection logic (fulfills AC-1, AC-2, AC-3)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+```javascript
+// Detect if we should show autocomplete
+const getTriggerInfo = useCallback((value, cursorPos) => {
+  if (!autocompleteConfig) return null;
+
+  const { trigger } = autocompleteConfig;
+
+  // Find the start of the current "word" (after last whitespace before cursor)
+  let wordStart = cursorPos;
+  while (wordStart > 0 && !/\s/.test(value[wordStart - 1])) {
+    wordStart--;
+  }
+
+  // Check if word starts with trigger
+  if (value[wordStart] === trigger) {
+    return {
+      trigger,
+      filterText: value.slice(wordStart + 1, cursorPos).toLowerCase(),
+      replaceStart: wordStart,
+      replaceEnd: cursorPos
+    };
+  }
+
+  return null;
+}, [autocompleteConfig]);
+```
+
+### IMP-6: Filtered and sorted skills (fulfills AC-5, AC-6)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+```javascript
+const filteredSkills = useMemo(() => {
+  if (!autocompleteConfig || !triggerInfo) return [];
+
+  const { skills } = autocompleteConfig;
+  const { filterText } = triggerInfo;
+
+  let filtered = skills;
+  if (filterText) {
+    filtered = skills.filter(s =>
+      s.name.toLowerCase().includes(filterText)
+    );
+  }
+
+  // Already sorted by server, but ensure alphabetical
+  return filtered.sort((a, b) => a.name.localeCompare(b.name));
+}, [autocompleteConfig, triggerInfo]);
+```
+
+### IMP-7: Keyboard navigation (fulfills AC-7, AC-8, AC-9)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+**Note**: Enter with empty filter dismisses dropdown (doesn't submit message). This prevents accidental submissions when user types a partial match that has no results.
+
+```javascript
+onKeyDown=${(e) => {
+  if (showAutocomplete) {
+    // Always handle Escape when dropdown is open
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      setShowAutocomplete(false);
+      return;
+    }
+
+    // Handle Enter/Tab: select if matches exist, otherwise dismiss (don't submit)
+    if (e.key === 'Enter' || e.key === 'Tab') {
+      e.preventDefault();
+      if (filteredSkills.length > 0 && filteredSkills[selectedIndex]) {
+        insertSkill(filteredSkills[selectedIndex]);
+      } else {
+        setShowAutocomplete(false);
+      }
+      return;
+    }
+
+    // Arrow navigation only when there are matches
+    if (filteredSkills.length > 0) {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        setSelectedIndex(i => Math.min(i + 1, filteredSkills.length - 1));
+        return;
+      }
+      if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        setSelectedIndex(i => Math.max(i - 1, 0));
+        return;
+      }
+    }
+  }
+
+  // Existing Enter-to-submit logic (only when dropdown is closed)
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault();
+    handleSubmit(e);
+  }
+}}
+```
+
+### IMP-8: Skill insertion (fulfills AC-8)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+```javascript
+const insertSkill = useCallback((skill) => {
+  if (!triggerInfo || !autocompleteConfig) return;
+
+  const { trigger } = autocompleteConfig;
+  const { replaceStart, replaceEnd } = triggerInfo;
+
+  const before = text.slice(0, replaceStart);
+  const after = text.slice(replaceEnd);
+  const inserted = `${trigger}${skill.name} `;
+
+  setText(before + inserted + after);
+  setShowAutocomplete(false);
+
+  // Move cursor after inserted text
+  const newCursorPos = replaceStart + inserted.length;
+  setTimeout(() => {
+    if (textareaRef.current) {
+      textareaRef.current.selectionStart = newCursorPos;
+      textareaRef.current.selectionEnd = newCursorPos;
+      textareaRef.current.focus();
+    }
+  }, 0);
+}, [text, triggerInfo, autocompleteConfig]);
+```
+
+### IMP-9: Autocomplete dropdown UI (fulfills AC-4, AC-10, AC-15, AC-16, AC-17, AC-18)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+**Note**: Uses index as `key` instead of `skill.name` to handle potential duplicate skill names (curated + user skills with same name).
+
+```javascript
+${showAutocomplete && html`
+  <div
+    ref=${autocompleteRef}
+    class="absolute left-0 bottom-full mb-1 w-full max-h-48 overflow-y-auto rounded-lg border border-selection/75 bg-surface shadow-lg z-50"
+  >
+    ${filteredSkills.length === 0 ? html`
+      <div class="px-3 py-2 text-sm text-dim">No matching skills</div>
+    ` : filteredSkills.map((skill, i) => html`
+      <div
+        key=${i}
+        class="px-3 py-2 cursor-pointer text-sm transition-colors ${
+          i === selectedIndex
+            ? 'bg-selection/50 text-bright'
+            : 'text-fg hover:bg-selection/25'
+        }"
+        onClick=${() => insertSkill(skill)}
+        onMouseEnter=${() => setSelectedIndex(i)}
+      >
+        <div class="font-medium font-mono text-bright">
+          ${autocompleteConfig.trigger}${skill.name}
+        </div>
+        <div class="text-micro text-dim truncate">${skill.description}</div>
+      </div>
+    `)}
+  </div>
+`}
+```
+
+### IMP-10: Click-outside dismissal (fulfills AC-9)
+
+**Location**: `dashboard/components/SimpleInput.js`
+
+```javascript
+useEffect(() => {
+  if (!showAutocomplete) return;
+
+  const handleClickOutside = (e) => {
+    if (autocompleteRef.current && !autocompleteRef.current.contains(e.target) &&
+        textareaRef.current && !textareaRef.current.contains(e.target)) {
+      setShowAutocomplete(false);
+    }
+  };
+
+  document.addEventListener('mousedown', handleClickOutside);
+  return () => document.removeEventListener('mousedown', handleClickOutside);
+}, [showAutocomplete]);
+```
+
+## Testing Considerations
+
+### Manual Testing Checklist
+1. Claude session: Type `/` - dropdown appears with Claude skills
+2. Codex session: Type `$` - dropdown appears with Codex skills
+3. Claude session: Type `$` - nothing happens (wrong trigger)
+4. Type `/com` - list filters to skills containing "com"
+5. Mid-message: Type "please run /commit" - autocomplete triggers on `/`
+6. Arrow keys navigate, Enter selects
+7. Escape dismisses without selection
+8. Click outside dismisses
+9. Selected skill shows as `{trigger}skill-name ` in input
+10. Verify alphabetical ordering
+11. Verify vertical scroll with many skills
+
+### Edge Cases
+- Session without skills (dropdown doesn't appear)
+- Single skill (still shows dropdown)
+- Very long skill descriptions (truncated with ellipsis)
+- Multiple triggers in one message (each can trigger independently)
+- Backspace over trigger (dismisses autocomplete)
+
+## Rollout Slices
+
+### Slice 1: Server-side skill enumeration
+- Add `SkillsMixin` with `_enumerate_codex_skills()` and `_enumerate_claude_skills()`
+- Add `/api/skills?agent=` endpoint in `HttpMixin.do_GET`
+- Test endpoint returns correct data for each agent type
+
+### Slice 2: Client-side skill loading
+- Add `fetchSkills()` API helper
+- Load skills in Modal.js on session open
+- Pass `autocompleteConfig` to SimpleInput
+
+### Slice 3: Basic autocomplete trigger
+- Add trigger detection logic (position 0 + after whitespace)
+- Show/hide dropdown based on trigger
+- Basic filtered list display
+
+### Slice 4: Keyboard navigation + selection
+- Arrow key navigation
+- Enter/Tab selection
+- Escape dismissal
+- Click-outside dismissal
+
+### Slice 5: Polish
+- Mouse hover to select
+- Scroll into view for long lists
+- Cursor positioning after insertion
diff --git a/plans/agent-spawning.md b/plans/agent-spawning.md
new file mode 100644
index 0000000..1c54b79
--- /dev/null
+++ b/plans/agent-spawning.md
@@ -0,0 +1,910 @@
+# AMC Agent Spawning via Zellij
+
+## Summary
+
+Add the ability to spawn new agent sessions (Claude or Codex) from the AMC dashboard. Users click "New Agent" in the page header, select an agent type, and a new Zellij pane opens in a project-named tab. The spawned agent appears in the dashboard alongside existing sessions.
+
+**Why this matters:** Currently, AMC monitors existing sessions but cannot create new ones. Users must manually open terminal panes and run `claude` or `codex`. This feature enables orchestration workflows where the dashboard becomes a control center for multi-agent coordination.
+
+**Core insight from research:** Zellij's CLI (`zellij --session <name> action new-pane ...`) works from external processes without requiring `ZELLIJ` environment variables.
+
+---
+
+## User Workflows
+
+### Workflow 1: Spawn Agent from Project Tab
+
+**Trigger:** User is viewing a specific project tab in the dashboard sidebar, clicks "New Agent" in header.
+
+**Flow:**
+1. User is on "amc" project tab in dashboard sidebar
+2. User clicks "+ New Agent" button in page header
+3. Modal appears with agent type selector: Claude / Codex
+4. User selects "Claude", clicks "Spawn"
+5. Server finds or creates Zellij tab named "amc"
+6. New pane spawns in that tab with `claude --dangerously-skip-permissions`
+7. Dashboard updates: new session card appears (status: "starting")
+
+**Key behavior:** Path is automatically determined from the selected project tab.
+
+### Workflow 2: Spawn Agent from "All Projects" Tab
+
+**Trigger:** User is on "All Projects" tab, clicks "New Agent" in header.
+
+**Flow:**
+1. User is on "All Projects" tab (no specific project selected)
+2. User clicks "+ New Agent" button in page header
+3. Modal appears with:
+   - Project dropdown (lists subdirectories of `~/projects/`)
+   - Agent type selector: Claude / Codex
+4. User selects "mission-control" project, "Codex" agent type, clicks "Spawn"
+5. Server finds or creates Zellij tab named "mission-control"
+6. New pane spawns with `codex --dangerously-bypass-approvals-and-sandbox`
+7. Dashboard updates: new session card appears
+
+**Key behavior:** User must select a project from the dropdown when on "All Projects".
+
+---
+
+## Acceptance Criteria
+
+### Spawn Button Location & Context
+
+- **AC-1:** "New Agent" button is located in the page header, not on session cards
+- **AC-2:** When on a specific project tab, the spawn modal does not show a project picker
+- **AC-3:** When on "All Projects" tab, the spawn modal shows a project dropdown
+
+### Project Selection (All Projects Tab)
+
+- **AC-4:** The project dropdown lists all immediate subdirectories of `~/projects/`
+- **AC-5:** Hidden directories (starting with `.`) are excluded from the dropdown
+- **AC-6:** User must select a project before spawning (no default selection)
+
+### Agent Type Selection
+
+- **AC-7:** User can choose between Claude and Codex agent types
+- **AC-8:** Claude agents spawn with full autonomous permissions enabled
+- **AC-9:** Codex agents spawn with full autonomous permissions enabled
+
+### Zellij Tab Targeting
+
+- **AC-10:** Agents spawn in a Zellij tab named after the project (e.g., "amc" tab for amc project)
+- **AC-11:** If the project-named tab does not exist, it is created before spawning
+- **AC-12:** All spawns target the "infra" Zellij session
+
+### Pane Spawning
+
+- **AC-13:** The spawned pane's cwd is set to the project directory
+- **AC-14:** Spawned panes are named `{agent_type}-{project}` (e.g., "claude-amc")
+- **AC-15:** The spawned agent appears in the dashboard within 5 seconds of spawn
+
+### Session Discovery
+
+- **AC-16:** Spawned agent's session data includes correct `zellij_session` and `zellij_pane`
+- **AC-17:** Dashboard can send responses to spawned agents (existing functionality works)
+
+### Error Handling
+
+- **AC-18:** Spawning fails gracefully if Zellij binary is not found
+- **AC-19:** Spawning fails gracefully if target project directory does not exist
+- **AC-20:** Spawn errors display a toast notification showing the server's error message
+- **AC-21:** Network errors between dashboard and server show retry option
+
+### Security
+
+- **AC-22:** Server validates project path is within `~/projects/` (resolves symlinks)
+- **AC-23:** Server rejects path traversal attempts in project parameter
+- **AC-24:** Server binds to localhost only (127.0.0.1), not exposed to network
+
+### Spawn Request Lifecycle
+
+- **AC-25:** The Spawn button is disabled while a spawn request is in progress
+- **AC-26:** If the target Zellij session does not exist, spawn fails with error "Zellij session 'infra' not found"
+- **AC-27:** Server generates a unique `spawn_id` and passes it to the agent via `AMC_SPAWN_ID` env var
+- **AC-28:** `amc-hook` writes `spawn_id` to session file when present in environment
+- **AC-29:** Spawn request polls for session file containing the specific `spawn_id` (max 5 second wait)
+- **AC-30:** Concurrent spawn requests are serialized via a lock to prevent Zellij race conditions
+
+### Modal Behavior
+
+- **AC-31:** Spawn modal can be dismissed by clicking outside, pressing Escape, or clicking Cancel
+- **AC-32:** While fetching the projects list, the project dropdown displays "Loading..." and is disabled
+
+### Projects List Caching
+
+- **AC-33:** Projects list is loaded on server start and cached in memory
+- **AC-34:** Projects list can be refreshed via `POST /api/projects/refresh`
+
+---
+
+## Architecture
+
+### Component Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Dashboard (Preact)                       │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │ Header                        [+ New Agent]          │   │
+│  └──────────────────────────────────────────────────────┘   │
+│  ┌────────────┐  ┌──────────────────────────────────────┐   │
+│  │ Sidebar    │  │ Main Content                         │   │
+│  │            │  │                                      │   │
+│  │ All Proj.  │  │  ┌─────────┐ ┌─────────┐            │   │
+│  │ > amc      │  │  │ Session │ │ Session │            │   │
+│  │ > gitlore  │  │  │  Card   │ │  Card   │            │   │
+│  │            │  │  └─────────┘ └─────────┘            │   │
+│  └────────────┘  └──────────────────────────────────────┘   │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │ SpawnModal (context-aware)                           │   │
+│  │  - If on project tab: just agent type picker         │   │
+│  │  - If on All Projects: project dropdown + agent type │   │
+│  └──────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────┘
+                           │
+                    POST /api/spawn
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                     AMC Server (Python)                       │
+│  ┌─────────────────────────────────────────────────────────┐ │
+│  │                    SpawnMixin                            │ │
+│  │  - list_projects()        → ~/projects/* dirs           │ │
+│  │  - validate_spawn()       → security checks             │ │
+│  │  - ensure_tab_exists()    → create tab if needed        │ │
+│  │  - spawn_agent_pane()     → zellij action new-pane      │ │
+│  └─────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────┘
+                           │
+            subprocess.run(["zellij", ...])
+                           │
+                           ▼
+┌──────────────────────────────────────────────────────────────┐
+│                Zellij Session: "infra"                        │
+│                                                               │
+│  Tab: "amc"              Tab: "gitlore"       Tab: "work"    │
+│  ┌──────┬──────┐        ┌──────┐             ┌──────┐       │
+│  │claude│claude│        │codex │             │nvim  │       │
+│  │ (1)  │ (2)  │        │      │             │      │       │
+│  └──────┴──────┘        └──────┘             └──────┘       │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Data Flow
+
+1. **Dashboard → Server:** `POST /api/spawn` with project + agent type
+2. **Server:** Acquire spawn lock (serializes concurrent requests)
+3. **Server:** Validate project path is within `~/projects/` (resolve symlinks)
+4. **Server:** Generate unique `spawn_id` (UUID)
+5. **Server:** Check Zellij session exists (fail with SESSION_NOT_FOUND if not)
+6. **Server → Zellij:** `go-to-tab-name --create <project>` (ensures tab exists)
+7. **Server → Zellij:** `new-pane --cwd <path> -- <agent command>` with `AMC_SPAWN_ID` env var
+8. **Zellij:** Pane created, agent process starts
+9. **Agent → Hook:** `amc-hook` fires on `SessionStart`, writes session JSON including `spawn_id` from env
+10. **Server:** Poll for session file containing matching `spawn_id` (up to 5 seconds)
+11. **Server → Dashboard:** Return success only after session file with `spawn_id` detected
+12. **Server:** Release spawn lock
+
+### API Design
+
+**POST /api/spawn**
+
+Request:
+```json
+{
+  "project": "amc",
+  "agent_type": "claude"
+}
+```
+
+Response (success):
+```json
+{
+  "ok": true,
+  "project": "amc",
+  "agent_type": "claude"
+}
+```
+
+Response (error):
+```json
+{
+  "ok": false,
+  "error": "Project directory does not exist: /Users/taylor/projects/foo",
+  "code": "PROJECT_NOT_FOUND"
+}
+```
+
+**GET /api/projects**
+
+Response:
+```json
+{
+  "projects": ["amc", "gitlore", "mission-control", "work-ghost"]
+}
+```
+
+**POST /api/projects/refresh**
+
+Response:
+```json
+{
+  "ok": true,
+  "projects": ["amc", "gitlore", "mission-control", "work-ghost"]
+}
+```
+
+### Why This Architecture
+
+1. **Server-side spawning:** Dashboard runs in browser, cannot execute shell commands.
+
+2. **Tab-per-project organization:** Keeps agents for the same project grouped together in Zellij.
+
+3. **`go-to-tab-name --create`:** Idempotent tab creation - creates if missing, switches if exists.
+
+4. **Polling for discovery:** Spawned agents write their own session files via hooks. Dashboard picks them up on next poll.
+
+### Session Discovery Mechanism
+
+**Claude agents** write session files via the `amc-hook` Claude Code hook:
+- Hook fires on `SessionStart` event
+- Writes JSON to `~/.local/share/amc/sessions/{session_id}.json`
+- Contains: session_id, project, status, zellij_session, zellij_pane, etc.
+- **Spawn correlation:** If `AMC_SPAWN_ID` env var is set, hook includes it in session JSON
+
+**Codex agents** are discovered dynamically by `SessionDiscoveryMixin`:
+- Scans `~/.codex/sessions/` for recently-modified `.jsonl` files
+- Extracts Zellij pane info via process inspection (`pgrep`, `lsof`)
+- Creates/updates session JSON in `~/.local/share/amc/sessions/`
+- **Spawn correlation:** Codex discovery checks for `AMC_SPAWN_ID` in process environment
+
+**Prerequisite:** The `amc-hook` must be installed in Claude Code's hooks configuration. See `~/.claude/hooks/` or Claude Code settings.
+
+**Why spawn_id matters:** Without deterministic correlation, polling "any new session file" could return success for unrelated agent activity. The `spawn_id` ensures the server confirms the *specific* agent it spawned is running.
+
+### Integration with Existing Code
+
+| New Code | Integrates With | How |
+|----------|-----------------|-----|
+| SpawnMixin | HttpMixin | Uses `_send_json()`, `_json_error()` |
+| SpawnModal | Modal.js | Follows same patterns (escape, scroll lock, animations) |
+| SpawnModal | api.js | Uses `fetchWithTimeout`, API constants |
+| Toast calls | Toast.js | Uses existing `showToast(msg, type, duration)` |
+| PROJECTS_DIR | context.py | Added alongside other path constants |
+| Session polling | SESSIONS_DIR | Watches same directory as discovery mixins |
+
+---
+
+## Implementation Specifications
+
+### IMP-0: Add Constants to context.py
+
+**File:** `amc_server/context.py`
+
+Add after existing path constants:
+```python
+# Projects directory for spawning agents
+PROJECTS_DIR = Path.home() / "projects"
+
+# Default Zellij session for spawning
+ZELLIJ_SESSION = "infra"
+
+# Lock for serializing spawn operations (prevents Zellij race conditions)
+_spawn_lock = threading.Lock()
+```
+
+---
+
+### IMP-1: SpawnMixin for Server (fulfills AC-8, AC-9, AC-10, AC-11, AC-12, AC-13, AC-14, AC-18, AC-19, AC-22, AC-23, AC-25, AC-26, AC-29, AC-30)
+
+**File:** `amc_server/mixins/spawn.py`
+
+**Integration notes:**
+- Uses `_send_json()` from HttpMixin (not a new `_json_response`)
+- Uses inline JSON body parsing (same pattern as `control.py:33-47`)
+- PROJECTS_DIR and ZELLIJ_SESSION come from context.py (centralized constants)
+- Session file polling watches SESSIONS_DIR for any new .json by mtime
+
+```python
+import json
+import subprocess
+import time
+
+from amc_server.context import PROJECTS_DIR, SESSIONS_DIR, ZELLIJ_BIN, ZELLIJ_SESSION
+
+# Agent commands (AC-8, AC-9: full autonomous permissions)
+AGENT_COMMANDS = {
+    "claude": ["claude", "--dangerously-skip-permissions"],
+    "codex": ["codex", "--dangerously-bypass-approvals-and-sandbox"],
+}
+
+# Module-level cache for projects list (AC-29)
+_projects_cache: list[str] = []
+
+
+def load_projects_cache():
+    """Scan ~/projects/ and cache the list. Called on server start."""
+    global _projects_cache
+    try:
+        projects = []
+        for entry in PROJECTS_DIR.iterdir():
+            if entry.is_dir() and not entry.name.startswith("."):
+                projects.append(entry.name)
+        projects.sort()
+        _projects_cache = projects
+    except OSError:
+        _projects_cache = []
+
+
+class SpawnMixin:
+    def _handle_spawn(self):
+        """Handle POST /api/spawn"""
+        # Read JSON body (same pattern as control.py)
+        try:
+            content_length = int(self.headers.get("Content-Length", 0))
+            body = json.loads(self.rfile.read(content_length))
+            if not isinstance(body, dict):
+                self._json_error(400, "Invalid JSON body")
+                return
+        except (json.JSONDecodeError, ValueError):
+            self._json_error(400, "Invalid JSON body")
+            return
+
+        project = body.get("project", "").strip()
+        agent_type = body.get("agent_type", "claude").strip()
+
+        # Validation
+        error = self._validate_spawn_params(project, agent_type)
+        if error:
+            self._send_json(400, {"ok": False, "error": error["message"], "code": error["code"]})
+            return
+
+        project_path = PROJECTS_DIR / project
+
+        # Ensure tab exists, then spawn pane, then wait for session file
+        result = self._spawn_agent_in_project_tab(project, project_path, agent_type)
+
+        if result["ok"]:
+            self._send_json(200, {"ok": True, "project": project, "agent_type": agent_type})
+        else:
+            self._send_json(500, {"ok": False, "error": result["error"], "code": result.get("code", "SPAWN_FAILED")})
+
+    def _validate_spawn_params(self, project, agent_type):
+        """Validate spawn parameters. Returns error dict or None."""
+        if not project:
+            return {"message": "project is required", "code": "MISSING_PROJECT"}
+
+        # Security: no path traversal
+        if "/" in project or "\\" in project or ".." in project:
+            return {"message": "Invalid project name", "code": "INVALID_PROJECT"}
+
+        # Project must exist
+        project_path = PROJECTS_DIR / project
+        if not project_path.is_dir():
+            return {"message": f"Project not found: {project}", "code": "PROJECT_NOT_FOUND"}
+
+        # Agent type must be valid
+        if agent_type not in AGENT_COMMANDS:
+            return {"message": f"Invalid agent type: {agent_type}", "code": "INVALID_AGENT_TYPE"}
+
+        return None
+
+    def _check_zellij_session_exists(self):
+        """Check if the target Zellij session exists (AC-25)."""
+        try:
+            result = subprocess.run(
+                [ZELLIJ_BIN, "list-sessions"],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            return ZELLIJ_SESSION in result.stdout
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
+    def _wait_for_session_file(self, timeout=5.0):
+        """Poll for any new session file in SESSIONS_DIR (AC-26).
+
+        Session files are named {session_id}.json. We don't know the session_id
+        in advance, so we watch for any .json file with mtime after spawn started.
+        """
+        start = time.monotonic()
+        # Snapshot existing files to detect new ones
+        existing_files = set()
+        if SESSIONS_DIR.exists():
+            existing_files = {f.name for f in SESSIONS_DIR.glob("*.json")}
+
+        while time.monotonic() - start < timeout:
+            if SESSIONS_DIR.exists():
+                for f in SESSIONS_DIR.glob("*.json"):
+                    # New file that didn't exist before spawn
+                    if f.name not in existing_files:
+                        return True
+                    # Or existing file with very recent mtime (reused session)
+                    if f.stat().st_mtime > start:
+                        return True
+            time.sleep(0.25)
+        return False
+
+    def _spawn_agent_in_project_tab(self, project, project_path, agent_type):
+        """Ensure project tab exists and spawn agent pane."""
+        try:
+            # Step 0: Check session exists (AC-25)
+            if not self._check_zellij_session_exists():
+                return {
+                    "ok": False,
+                    "error": f"Zellij session '{ZELLIJ_SESSION}' not found",
+                    "code": "SESSION_NOT_FOUND"
+                }
+
+            # Step 1: Go to or create the project tab
+            tab_result = subprocess.run(
+                [ZELLIJ_BIN, "--session", ZELLIJ_SESSION, "action", "go-to-tab-name", "--create", project],
+                capture_output=True,
+                text=True,
+                timeout=5
+            )
+            if tab_result.returncode != 0:
+                return {"ok": False, "error": f"Failed to create/switch tab: {tab_result.stderr}", "code": "TAB_ERROR"}
+
+            # Step 2: Spawn new pane with agent command (AC-14: naming scheme)
+            agent_cmd = AGENT_COMMANDS[agent_type]
+            pane_name = f"{agent_type}-{project}"
+
+            spawn_cmd = [
+                ZELLIJ_BIN, "--session", ZELLIJ_SESSION, "action", "new-pane",
+                "--name", pane_name,
+                "--cwd", str(project_path),
+                "--",
+                *agent_cmd
+            ]
+
+            spawn_result = subprocess.run(
+                spawn_cmd,
+                capture_output=True,
+                text=True,
+                timeout=10
+            )
+            if spawn_result.returncode != 0:
+                return {"ok": False, "error": f"Failed to spawn pane: {spawn_result.stderr}", "code": "SPAWN_ERROR"}
+
+            # Step 3: Wait for session file (AC-26)
+            if not self._wait_for_session_file(timeout=5.0):
+                return {
+                    "ok": False,
+                    "error": "Agent spawned but session file not detected within 5 seconds",
+                    "code": "SESSION_FILE_TIMEOUT"
+                }
+
+            return {"ok": True}
+
+        except FileNotFoundError:
+            return {"ok": False, "error": f"zellij not found at {ZELLIJ_BIN}", "code": "ZELLIJ_NOT_FOUND"}
+        except subprocess.TimeoutExpired:
+            return {"ok": False, "error": "zellij command timed out", "code": "TIMEOUT"}
+
+    def _handle_projects(self):
+        """Handle GET /api/projects - return cached projects list (AC-29)."""
+        self._send_json(200, {"projects": _projects_cache})
+
+    def _handle_projects_refresh(self):
+        """Handle POST /api/projects/refresh - refresh cache (AC-30)."""
+        load_projects_cache()
+        self._send_json(200, {"ok": True, "projects": _projects_cache})
+```
+
+### IMP-2: HTTP Routing (fulfills AC-1, AC-3, AC-4, AC-30)
+
+**File:** `amc_server/mixins/http.py`
+
+Add to `do_GET`:
+```python
+elif self.path == "/api/projects":
+    self._handle_projects()
+```
+
+Add to `do_POST`:
+```python
+elif self.path == "/api/spawn":
+    self._handle_spawn()
+elif self.path == "/api/projects/refresh":
+    self._handle_projects_refresh()
+```
+
+Update `do_OPTIONS` for CORS preflight on new endpoints:
+```python
+def do_OPTIONS(self):
+    # CORS preflight for API endpoints
+    self.send_response(204)
+    self.send_header("Access-Control-Allow-Origin", "*")
+    self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+    self.send_header("Access-Control-Allow-Headers", "Content-Type")
+    self.end_headers()
+```
+
+### IMP-2b: Server Startup (fulfills AC-29)
+
+**File:** `amc_server/server.py`
+
+Add to server initialization:
+```python
+from amc_server.mixins.spawn import load_projects_cache
+
+# In server startup, before starting HTTP server:
+load_projects_cache()
+```
+
+### IMP-2c: API Constants (follows existing pattern)
+
+**File:** `dashboard/utils/api.js`
+
+Add to existing exports:
+```javascript
+// Spawn API endpoints
+export const API_SPAWN = '/api/spawn';
+export const API_PROJECTS = '/api/projects';
+export const API_PROJECTS_REFRESH = '/api/projects/refresh';
+```
+
+### IMP-3: Handler Integration (fulfills AC-2, AC-3)
+
+**File:** `amc_server/handler.py`
+
+Add SpawnMixin to handler inheritance chain:
+```python
+from amc_server.mixins.spawn import SpawnMixin
+
+class AMCHandler(
+    HttpMixin,
+    StateMixin,
+    ConversationMixin,
+    SessionControlMixin,
+    SessionDiscoveryMixin,
+    SessionParsingMixin,
+    SpawnMixin,  # Add this
+    BaseHTTPRequestHandler,
+):
+    """HTTP handler composed from focused mixins."""
+```
+
+### IMP-4: SpawnModal Component (fulfills AC-2, AC-3, AC-6, AC-7, AC-20, AC-24, AC-27, AC-28)
+
+**File:** `dashboard/components/SpawnModal.js`
+
+**Integration notes:**
+- Uses `fetchWithTimeout` and API constants from `api.js` (consistent with codebase)
+- Follows `Modal.js` patterns: escape key, click-outside, body scroll lock, animated close
+- Uses `html` tagged template (Preact pattern used throughout dashboard)
+
+```javascript
+import { html, useState, useEffect, useCallback } from '../lib/preact.js';
+import { API_PROJECTS, API_SPAWN, fetchWithTimeout } from '../utils/api.js';
+
+export function SpawnModal({ isOpen, onClose, onSpawn, currentProject }) {
+  const [projects, setProjects] = useState([]);
+  const [selectedProject, setSelectedProject] = useState('');
+  const [agentType, setAgentType] = useState('claude');
+  const [loading, setLoading] = useState(false);
+  const [loadingProjects, setLoadingProjects] = useState(false);
+  const [closing, setClosing] = useState(false);
+  const [error, setError] = useState(null);
+
+  const needsProjectPicker = !currentProject;
+
+  // Animated close handler (matches Modal.js pattern)
+  const handleClose = useCallback(() => {
+    if (loading) return;
+    setClosing(true);
+    setTimeout(() => {
+      setClosing(false);
+      onClose();
+    }, 200);
+  }, [loading, onClose]);
+
+  // Body scroll lock (matches Modal.js pattern)
+  useEffect(() => {
+    if (!isOpen) return;
+    document.body.style.overflow = 'hidden';
+    return () => { document.body.style.overflow = ''; };
+  }, [isOpen]);
+
+  // Escape key to close (matches Modal.js pattern)
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKeyDown = (e) => {
+      if (e.key === 'Escape') handleClose();
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen, handleClose]);
+
+  // Fetch projects when modal opens
+  useEffect(() => {
+    if (isOpen && needsProjectPicker) {
+      setLoadingProjects(true);
+      fetchWithTimeout(API_PROJECTS)
+        .then(r => r.json())
+        .then(data => {
+          setProjects(data.projects || []);
+          setSelectedProject('');
+        })
+        .catch(err => setError(err.message))
+        .finally(() => setLoadingProjects(false));
+    }
+  }, [isOpen, needsProjectPicker]);
+
+  // Reset state when modal opens
+  useEffect(() => {
+    if (isOpen) {
+      setAgentType('claude');
+      setError(null);
+      setLoading(false);
+      setClosing(false);
+    }
+  }, [isOpen]);
+
+  const handleSpawn = async () => {
+    const project = currentProject || selectedProject;
+    if (!project) {
+      setError('Please select a project');
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+
+    try {
+      const response = await fetchWithTimeout(API_SPAWN, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ project, agent_type: agentType })
+      });
+      const data = await response.json();
+
+      if (data.ok) {
+        onSpawn({ success: true, project, agentType });
+        handleClose();
+      } else {
+        setError(data.error || 'Spawn failed');
+        onSpawn({ error: data.error });
+      }
+    } catch (err) {
+      const msg = err.name === 'AbortError' ? 'Request timed out' : err.message;
+      setError(msg);
+      onSpawn({ error: msg });
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  if (!isOpen) return null;
+
+  return html`
+    <div
+      class="fixed inset-0 z-50 flex items-center justify-center bg-[#02050d]/84 p-4 backdrop-blur-sm ${closing ? 'modal-backdrop-out' : 'modal-backdrop-in'}"
+      onClick=${(e) => e.target === e.currentTarget && handleClose()}
+    >
+      <div
+        class="glass-panel w-full max-w-md rounded-2xl p-6 ${closing ? 'modal-panel-out' : 'modal-panel-in'}"
+        onClick=${(e) => e.stopPropagation()}
+      >
+        <h2 class="mb-4 font-display text-lg font-semibold text-bright">New Agent</h2>
+
+        ${needsProjectPicker && html`
+          <label class="mb-4 block">
+            <span class="mb-1 block text-sm text-dim">Project</span>
+            <select
+              class="w-full rounded-lg border border-selection/50 bg-surface px-3 py-2 text-bright"
+              value=${selectedProject}
+              onChange=${(e) => setSelectedProject(e.target.value)}
+              disabled=${loadingProjects}
+            >
+              <option value="">
+                ${loadingProjects ? 'Loading...' : 'Select a project...'}
+              </option>
+              ${projects.map(p => html`
+                <option key=${p} value=${p}>${p}</option>
+              `)}
+            </select>
+          </label>
+        `}
+
+        ${!needsProjectPicker && html`
+          <p class="mb-4 text-sm text-dim">
+            Project: <span class="font-medium text-bright">${currentProject}</span>
+          </p>
+        `}
+
+        <label class="mb-4 block">
+          <span class="mb-2 block text-sm text-dim">Agent Type</span>
+          <div class="flex gap-2">
+            <button
+              type="button"
+              class="flex-1 rounded-lg border px-4 py-2 text-sm font-medium transition-colors ${
+                agentType === 'claude'
+                  ? 'border-active bg-active/20 text-active'
+                  : 'border-selection/50 text-dim hover:border-selection hover:text-bright'
+              }"
+              onClick=${() => setAgentType('claude')}
+            >
+              Claude
+            </button>
+            <button
+              type="button"
+              class="flex-1 rounded-lg border px-4 py-2 text-sm font-medium transition-colors ${
+                agentType === 'codex'
+                  ? 'border-active bg-active/20 text-active'
+                  : 'border-selection/50 text-dim hover:border-selection hover:text-bright'
+              }"
+              onClick=${() => setAgentType('codex')}
+            >
+              Codex
+            </button>
+          </div>
+        </label>
+
+        ${error && html`
+          <p class="mb-4 rounded-lg border border-attention/50 bg-attention/10 px-3 py-2 text-sm text-attention">
+            ${error}
+          </p>
+        `}
+
+        <div class="flex justify-end gap-2">
+          <button
+            type="button"
+            class="rounded-lg border border-selection/50 px-4 py-2 text-sm text-dim transition-colors hover:border-selection hover:text-bright"
+            onClick=${handleClose}
+            disabled=${loading}
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            class="rounded-lg bg-active px-4 py-2 text-sm font-medium text-surface transition-opacity disabled:opacity-50"
+            onClick=${handleSpawn}
+            disabled=${loading || (needsProjectPicker && !selectedProject)}
+          >
+            ${loading ? 'Spawning...' : 'Spawn'}
+          </button>
+        </div>
+      </div>
+    </div>
+  `;
+}
+```
+
+### IMP-5: Header New Agent Button (fulfills AC-1)
+
+**File:** `dashboard/components/App.js`
+
+**Integration points:**
+1. Add import for SpawnModal
+2. Add state for modal visibility
+3. Add button to existing inline header (lines 331-380)
+4. Add SpawnModal component at end of render
+
+```javascript
+// Add import at top
+import { SpawnModal } from './SpawnModal.js';
+
+// Add state in App component (around line 14)
+const [spawnModalOpen, setSpawnModalOpen] = useState(false);
+
+// Add button to existing header section (inside the flex container, around line 341)
+// After the status summary chips div, add:
+<button
+  class="rounded-lg border border-active/40 bg-active/12 px-3 py-2 text-sm font-medium text-active transition-colors hover:bg-active/20"
+  onClick=${() => setSpawnModalOpen(true)}
+>
+  + New Agent
+</button>
+
+// Add modal before closing fragment (after ToastContainer, around line 426)
+<${SpawnModal}
+  isOpen=${spawnModalOpen}
+  onClose=${() => setSpawnModalOpen(false)}
+  onSpawn=${handleSpawnResult}
+  currentProject=${selectedProject}
+/>
+```
+
+### IMP-6: Toast Notifications for Spawn Results (fulfills AC-20, AC-21)
+
+**File:** `dashboard/components/App.js`
+
+**Integration note:** Uses existing `showToast(message, type, duration)` signature from `Toast.js`.
+
+```javascript
+import { showToast } from './Toast.js';  // Already imported in App.js
+
+// Add this callback in App component
+const handleSpawnResult = useCallback((result) => {
+  if (result.success) {
+    // showToast(message, type, duration) - matches Toast.js signature
+    showToast(`${result.agentType} agent spawned for ${result.project}`, 'success');
+  } else if (result.error) {
+    showToast(result.error, 'error');
+  }
+}, []);
+```
+
+---
+
+## Rollout Slices
+
+### Slice 1: Server-Side Spawning (Backend Only)
+
+**Goal:** Spawn agents via curl/API without UI.
+
+**Tasks:**
+1. Create `SpawnMixin` with `_handle_spawn()`, `_validate_spawn_params()`, `_spawn_agent_in_project_tab()`
+2. Create `_handle_projects()` for listing `~/projects/` subdirectories
+3. Add `/api/spawn` (POST) and `/api/projects` (GET) routes to HTTP handler
+4. Add SpawnMixin to handler inheritance chain
+5. Write tests for spawn validation and subprocess calls
+
+**Verification:**
+```bash
+# List projects
+curl http://localhost:7400/api/projects
+
+# Spawn claude agent
+curl -X POST http://localhost:7400/api/spawn \
+  -H "Content-Type: application/json" \
+  -d '{"project":"amc","agent_type":"claude"}'
+
+# Spawn codex agent
+curl -X POST http://localhost:7400/api/spawn \
+  -H "Content-Type: application/json" \
+  -d '{"project":"gitlore","agent_type":"codex"}'
+```
+
+**ACs covered:** AC-4, AC-5, AC-8, AC-9, AC-10, AC-11, AC-12, AC-13, AC-14, AC-18, AC-19, AC-22, AC-23, AC-25, AC-26, AC-29, AC-30
+
+### Slice 2: Spawn Modal UI
+
+**Goal:** Complete UI for spawning agents.
+
+**Tasks:**
+1. Create `SpawnModal` component with context-aware behavior
+2. Add "+ New Agent" button to page header
+3. Pass `currentProject` from sidebar selection to modal
+4. Implement agent type toggle (Claude / Codex)
+5. Wire up project dropdown (only shown on "All Projects")
+6. Add loading and error states
+7. Show toast on spawn result
+8. Implement modal dismiss behavior (Escape, click-outside, Cancel)
+
+**ACs covered:** AC-1, AC-2, AC-3, AC-6, AC-7, AC-20, AC-21, AC-24, AC-27, AC-28
+
+### Slice 3: Polish & Edge Cases
+
+**Goal:** Handle edge cases and improve UX.
+
+**Tasks:**
+1. Handle case where `~/projects/` doesn't exist or is empty
+2. Add visual feedback when agent appears in dashboard after spawn
+3. Test with projects that have special characters in name
+4. Ensure spawned agents' hooks write correct metadata
+
+**ACs covered:** AC-15, AC-16, AC-17
+
+---
+
+## Open Questions
+
+1. **Rate limiting:** Should we limit spawn frequency to prevent accidental spam?
+
+2. **Session cleanup:** When a spawned agent exits, should dashboard offer to close the pane?
+
+3. **Multiple Zellij sessions:** Currently hardcoded to "infra". Future: detect or let user pick?
+
+4. **Agent naming:** Current scheme is `{agent_type}-{project}`. Collision if multiple agents for same project?
+
+5. **Spawn limits:** Should we add spawn limits or warnings for resource management?
+
+6. **Dead code cleanup:** `Header.js` exists but isn't used (App.js has inline header). Remove it?
+
+7. **Hook verification:** Should spawn endpoint verify `amc-hook` is installed before spawning Claude agents?