pgserve 2.1.2 → 2.2.0

package/.genie/spells/session-state-updater.md

@@ -1,220 +0,0 @@
----
-name: session-state-updater
-type: workflow
-genie:
-  executor: CLAUDE_CODE
-  background: false
----
-
-# Session State Updater Workflow
-
-**Purpose:** Systematically update SESSION-STATE.md, MASTER-PLAN.md, and USERCONTEXT.md from any agent or workflow.
-
-**Called by:** ANY agent/workflow via `!`npx automagik-genie run session-state-updater "..."`
-
-**Foreground mode:** No `--background` flag = blocks execution until complete
-
----
-
-## Discovery Phase
-
-### Input Parameters
-
-This workflow accepts a prompt string with the following parameters (space-separated or key=value):
-
-```
-action=<started|in_progress|completed|waiting|paused>
-agent=<agent-name>
-session_id=<uuid>
-purpose="<description>"
-context="<optional-rich-data>"
-parent_session="<optional-parent-uuid>"
-branch="<optional-branch-name>"
-```
-
-**Examples:**
-```
-action=started agent=implementor session_id=abc123 purpose="Implement feature X" branch=feat/x
-
-action=in_progress agent=implementor session_id=abc123 context="files_modified:[src/x.ts,src/y.ts]"
-
-action=completed agent=implementor session_id=abc123 context="files_modified:[src/x.ts] tests_pass:true"
-```
-
-### Parse & Validate
-
-- Extract all key=value pairs from prompt
-- Validate `action` is one of: started, in_progress, completed, waiting, paused
-- Validate `session_id` is non-empty UUID format
-- Validate `agent` is recognized (implementor, tests, git, genie, learn, release, roadmap)
-- Parse `context` as structured data if provided
-
----
-
-## Implementation Phase
-
-### Step 1: Read Current State
-
-Read `.genie/SESSION-STATE.md` fully.
-
-Parse:
-- Active sessions section
-- Session history section
-- Any existing entry for this `session_id`
-
-### Step 2: Update or Create Entry
-
-**If session already exists:**
-- Update status field
-- Update timestamp (Last Updated)
-- Append context data
-- Preserve created timestamp
-
-**If session is new:**
-- Create entry in "Active Sessions" section
-- Set:
-  ```
-  ### <Agent Name> - <Purpose>
-  **Session ID:** `<session_id>`
-  **Started:** <ISO timestamp>
-  **Status:** <action>
-  **Agent:** <agent-name>
-  **Purpose:** <purpose>
-  **Context:** <context>
-  **Next:** [to be filled]
-  ```
-
-### Step 3: Handle State Transitions
-
-**started → active:**
-- Add to "Active Sessions"
-- Record start timestamp
-
-**in_progress → active:**
-- Update status
-- Keep in "Active Sessions"
-
-**completed → history:**
-- Move from "Active Sessions" to "Session History (Recent)"
-- Add completion timestamp
-- Preserve all context
-
-**waiting → paused:**
-- Keep in "Active Sessions"
-- Mark waiting status
-- Document reason in context
-
-### Step 4: Update Parent/Child Relationships
-
-If `parent_session` provided:
-- Find parent entry
-- Add this session to parent's "Children:" list (if not already present)
-- Mark this entry with "Parent:" reference
-
-### Step 5: Write Back
-
-1. Format updated SESSION-STATE.md
-2. Write to `.genie/SESSION-STATE.md`
-3. Git add the file
-4. Return success + summary
-
----
-
-## Verification Phase
-
-### Validation
-
-- [ ] SESSION-STATE.md is valid markdown
-- [ ] Session entry created/updated correctly
-- [ ] Parent-child relationships are bidirectional
-- [ ] Timestamps are ISO format (YYYY-MM-DD HH:MM UTC)
-- [ ] No duplicate session IDs
-- [ ] Entry matches requested action
-
-### Output
-
-Return JSON response:
-```json
-{
-  "status": "success",
-  "action": "started|updated|completed",
-  "session_id": "<uuid>",
-  "agent": "<agent-name>",
-  "updated_files": ["SESSION-STATE.md"],
-  "timestamp": "<ISO timestamp>",
-  "message": "Session state updated successfully"
-}
-```
-
-On failure:
-```json
-{
-  "status": "failed",
-  "error": "<error message>",
-  "details": "<debug info>"
-}
-```
-
----
-
-## Usage Pattern in Agents
-
-### At Agent Start
-
-```markdown
-# Implementor Agent
-
-!`npx automagik-genie run session-state-updater "action=started agent=implementor session_id=$SESSION_ID purpose=Implement\ Feature\ X branch=feat/x"`
-
-## Work happens here...
-```
-
-### Mid-work Update
-
-```markdown
-!`npx automagik-genie run session-state-updater "action=in_progress agent=implementor session_id=$SESSION_ID context=\"files_modified:[src/core.ts,src/utils.ts] tests_pass:false\""`
-```
-
-### On Completion
-
-```markdown
-## Results
-
-!`npx automagik-genie run session-state-updater "action=completed agent=implementor session_id=$SESSION_ID context=\"files_modified:[src/core.ts,src/utils.ts,test/core.test.ts] tests_pass:true done_report:.genie/wishes/feat-x/reports/done-implementor.md\""`
-```
-
----
-
-## Benefits
-
-**Eliminates:**
-- Manual SESSION-STATE.md updates
-- Stale session tracking
-- role-clarity-protocol guardrails (state always current)
-- Documentation bloat (knowledge transferred here)
-
-**Enables:**
-- Automatic state synchronization
-- Rich context capture at runtime
-- Parent-child workflow tracking
-- Complete session history
-- Foreground blocking (forces discipline)
-
----
-
-## Technical Notes
-
-- **Foreground mode:** No `--background` flag ensures execution waits
-- **Markdown integration:** Called via `!` syntax from any agent/workflow
-- **Idempotent:** Safe to call multiple times (updates same entry)
-- **Transactional:** Entire state file updated atomically
-- **Git-aware:** Auto-stages updated file
-
----
-
-## Future Extensions
-
-- Auto-cleanup old completed sessions (archive to history)
-- Webhook notifications on state changes
-- Analytics on session duration/completion rates
-- Integration with GitHub via issues/PRs

package/.genie/spells/track-long-running-tasks.md

@@ -1,133 +0,0 @@
----
-name: Persistent Tracking Protocol
-description: Track all active agent sessions in SESSION-STATE.md for continuity
----
-
-# Persistent Tracking Protocol
-
-**Purpose:** SESSION-STATE.md enables collective intelligence with memory across restarts.
-
-**Requirements for SESSION-STATE.md:**
-
-1. **Track all active agents:**
-```markdown
-### Git Agent - Feature Implementation
-**Session ID:** `abc123...`
-**Started:** 2025-10-17 16:00 UTC
-**Status:** active
-**Children:** issue workflow (def456), pr workflow (ghi789)
-**Purpose:** Create GitHub issues for feature XYZ
-**Context:** Branch feat/xyz, files modified: [list]
-**Next:** Create PR after issues created
-```
-
-2. **Parent-child relationships:**
-   - Agent entry lists child workflow sessions
-   - Clear which workflows belong to which agent
-   - Prevents "orphaned children" after context reset
-
-3. **Resume protocol:**
-   - Base Genie reads SESSION-STATE.md on restart
-   - Identifies active agents, presents status to user
-   - User can resume any agent with `mcp__genie__resume`
-   - Children resume automatically when parent resumes
-
-4. **Completion tracking:**
-   - Agents mark "completed" when work done
-   - Children marked completed when parent completes
-   - Completed sessions move to history section
-   - Evidence preserved (Done Reports linked)
-
-**Session entry template (agent with workflows):**
-```markdown
-### [Agent Name] - [Context Description]
-**Session ID:** `abc123...`
-**Started:** YYYY-MM-DD HH:MM UTC
-**Status:** active | paused | completed
-**Children:** [workflow-name] (session-id), [workflow-name] (session-id)
-**Purpose:** [What this agent is working on]
-**Context:** [Key files, decisions, state]
-**Next:** [Next action when resumed]
-```
-
-**Session entry template (workflow - child):**
-```markdown
-### [Workflow Name] (child of [Parent Agent])
-**Session ID:** `def456...`
-**Parent:** [Parent Agent] (abc123)
-**Started:** YYYY-MM-DD HH:MM UTC
-**Status:** active | completed
-**Purpose:** [Specific workflow task]
-**Context:** [Key operations, files]
-```
-
-**Coordination rules:**
-
-**Before starting agent:**
-1. Check SESSION-STATE.md for conflicts (same files, different agents)
-2. Create session entry with "starting" status
-3. Launch agent, capture session ID
-4. Update entry with actual session ID and "active" status
-
-**When agent delegates to workflow:**
-1. Launch workflow, capture session ID
-2. Add workflow entry with parent reference
-3. Update parent agent entry with child list
-
-**When work completes:**
-1. Mark session "completed" in SESSION-STATE.md
-2. Document outcomes, Done Report location
-3. Move to history section
-4. Children auto-complete when parent completes
-
-**No lost children rule:**
-- Every workflow session MUST have parent reference
-- SESSION-STATE.md cleaned regularly (move completed to history)
-- Never delete entries without documenting outcomes
-
-**Validation:**
-```bash
-# Check SESSION-STATE.md structure
-grep -E "^### |^\*\*Session ID:|^\*\*Parent:" .genie/SESSION-STATE.md
-
-# Verify all children have parents
-# (manual check: every workflow entry has Parent: line)
-
-# Verify no orphans (workflows without active parents)
-# (manual check: compare child Parent: with active agent sessions)
-```
-
-**Example: Git agent with workflows**
-```markdown
-## Active Sessions
-
-### Git Agent - Feature XYZ Implementation
-**Session ID:** `git-xyz-abc123`
-**Started:** 2025-10-17 16:00 UTC
-**Status:** active
-**Children:**
-- issue workflow (issue-xyz-def456)
-- pr workflow (pr-xyz-ghi789)
-**Purpose:** Create GitHub issues and PR for feature XYZ
-**Context:**
-- Branch: feat/xyz
-- Files: src/feature.ts, tests/feature.test.ts
-- Issues created: #90, #91
-**Next:** Create PR after final issue created
-
-### Issue Workflow (child of Git Agent)
-**Session ID:** `issue-xyz-def456`
-**Parent:** Git Agent (git-xyz-abc123)
-**Started:** 2025-10-17 16:05 UTC
-**Status:** completed
-**Purpose:** Create GitHub issue #90
-**Context:** Used bug-report template, populated all fields
-
-### PR Workflow (child of Git Agent)
-**Session ID:** `pr-xyz-ghi789`
-**Parent:** Git Agent (git-xyz-abc123)
-**Started:** 2025-10-17 16:10 UTC
-**Status:** active
-**Purpose:** Create PR for feat/xyz
-**Context:** Collecting commit history, drafting description
-```

package/.genie/spells/troubleshoot-infrastructure.md

@@ -1,176 +0,0 @@
----
-name: Troubleshoot Infrastructure (When Delegation Monitoring Fails)
-description: Protocol for diagnosing infrastructure issues vs actual agent failures. Check infrastructure first, never assume failure.
----
-
-# Troubleshoot Infrastructure - When Delegation Monitoring Fails
-
-## Core Principle
-
-**Backend unreachable ≠ Agent stalled. Infrastructure issue ≠ Agent failure.**
-
-When delegation monitoring fails (can't view session, Forge unreachable, worktree inaccessible), diagnose infrastructure FIRST before assuming agent failed.
-
-## The Anti-Pattern
-
-❌ **Wrong Response:**
-1. Forge MCP returns "backend unreachable"
-2. Assume agent stalled or failed
-3. Start implementing work yourself
-4. Violate "Once Delegated, Never Duplicated"
-
-✅ **Correct Response:**
-1. Forge MCP returns error
-2. Diagnose infrastructure systematically
-3. Check if agent actually working (worktree check)
-4. Report bug if infrastructure issue
-5. Resume/restart if needed, NEVER duplicate
-
-## Diagnostic Protocol
-
-### Step 1: Check Forge Health
-
-**Test if Forge backend is responsive:**
-```javascript
-mcp__forge__list_projects()
-```
-
-**If this fails:**
-- Forge backend may be down
-- MCP connection issue
-- Network/Docker problem
-
-**Action:** Report infrastructure issue, don't assume agent failed
-
-### Step 2: Check Task Status Directly
-
-**Even if view fails, try direct task query:**
-```javascript
-mcp__forge__get_task(task_id="...")
-mcp__forge__get_task_attempt(attempt_id="...")
-```
-
-**If this succeeds:**
-- Backend is working
-- View endpoint may have specific issue
-- Agent may be progressing fine
-
-**Action:** Use task status, not view, for monitoring
-
-### Step 3: Check Worktree for Activity
-
-**Agent works in isolated worktree - check it directly:**
-```bash
-# List all worktrees
-ls /var/tmp/automagik-forge/worktrees/
-
-# Navigate to specific worktree
-cd /var/tmp/automagik-forge/worktrees/<task-id-prefix>*
-
-# Check if agent has been committing
-git log --oneline -5
-
-# Check working directory status
-git status
-
-# Check recent activity
-ls -lt | head -10
-```
-
-**If commits exist:**
-- Agent is working successfully!
-- Monitoring failed, but agent didn't
-- Infrastructure issue, not agent issue
-
-**Action:** Trust the worktree, report monitoring bug
-
-### Step 4: Report Infrastructure Bugs
-
-**Don't silently work around infrastructure issues:**
-```bash
-# Create GitHub issue for infrastructure problem
-gh issue create --title "Forge MCP view endpoint unreachable" \
-  --body "Attempted to monitor task <id>, got error <msg>. Task status shows agent working, but can't view progress." \
-  --label "bug,infrastructure"
-```
-
-**Why:** Infrastructure bugs must be tracked and fixed, not silently tolerated
-
-### Step 5: Resume or Restart (Never Duplicate)
-
-**If agent actually stalled (no worktree commits, task stuck):**
-```javascript
-// Try resuming with follow-up
-mcp__genie__resume(sessionId="...", prompt="Status check - are you still working?")
-
-// Or restart task if truly stuck
-// But NEVER implement yourself in main workspace
-```
-
-## Real-World Example
-
-**Scenario:** Monitoring task b51db539 (update process fix)
-
-**What Happened:**
-1. Master Genie delegates to fix agent via Forge
-2. `mcp__genie__view(sessionId)` returns "backend unreachable"
-3. Master Genie gets anxious about progress visibility
-4. **VIOLATION:** Master Genie starts editing genie-cli.ts, init.ts
-5. Meanwhile: fix agent already completed work in worktree
-6. Result: Duplicate work, wasted 40 minutes, Amendment #4 violated
-
-**What Should Have Happened:**
-1. Master Genie delegates to fix agent
-2. `mcp__genie__view()` fails with "backend unreachable"
-3. **Step 1:** Try `mcp__forge__list_projects()` → Works! Backend is fine
-4. **Step 2:** Try `mcp__forge__get_task()` → Shows task in progress
-5. **Step 3:** Check worktree:
-   ```bash
-   cd /var/tmp/automagik-forge/worktrees/b51d*
-   git log --oneline -3
-   # Shows: b8913b23 fix: Use workspace package version for update detection
-   ```
-6. **Discovery:** Agent completed work successfully! Monitoring failed, agent didn't.
-7. **Step 4:** Report bug: "Genie MCP view endpoint unreachable while task running"
-8. **Step 5:** No restart needed, agent succeeded. Merge worktree to main.
-
-**Time Saved:** 40 minutes of duplicate work avoided
-
-## Checklist Before Assuming Agent Failed
-
-When delegation monitoring fails, check:
-
-- [ ] Did I try `list_projects()` to test Forge health?
-- [ ] Did I try `get_task()` instead of `view()`?
-- [ ] Did I check the worktree for commits?
-- [ ] Did I verify agent actually stalled vs monitoring failed?
-- [ ] Did I report infrastructure bug?
-- [ ] Am I about to violate "Once Delegated, Never Duplicated"?
-
-## Why This Matters
-
-**Master Genie anxiety about progress visibility MUST NOT trigger implementation work.**
-
-Master Genie's role:
-- ✅ Monitor progress (when monitoring works)
-- ✅ Diagnose infrastructure issues
-- ✅ Report bugs
-- ✅ Coordinate next steps
-- ❌ Implement when anxious about visibility
-- ❌ Assume agent failed when infrastructure failed
-- ❌ Duplicate agent's work
-
-**Separation:** Infrastructure issues ≠ Agent failures. Diagnose correctly.
-
-## Evidence
-
-**Learning #7 Origin:** `learn.md` lines 152-164
-**Learning #9 Origin:** `learn.md` lines 180-196
-**Real violation:** Bug #168, task b51db539, 2025-10-21
-**Analysis:** `/tmp/session-ultrathink-analysis.md` lines 108-126, 177-198, 294-312
-
-## Related
-
-- `@.genie/spells/orchestration-boundary-protocol.md` - Once delegated, never duplicated
-- `@.genie/spells/orchestrator-not-implementor.md` - Role boundaries
-- `AGENTS.md` Amendment #4 - Orchestration boundary protocol