pgserve 0.1.1

package/.genie/code/spells/genie-integration.md

@@ -0,0 +1,153 @@
+---
+name: Genie Integration Framework
+description: Use genie agent for second opinions, pressure-tests, and decision audits
+genie:
+  executor: [CLAUDE_CODE, CODEX, OPENCODE]
+forge:
+  CLAUDE_CODE:
+    model: sonnet
+  CODEX: {}
+  OPENCODE: {}
+---
+
+# Genie Integration Framework
+
+**Purpose:** `genie` spell is GENIE's partner for second opinions, plan pressure-tests, deep dives, and decision audits. Use it to reduce risk, surface blind spots, and document reasoning without blocking implementation work.
+
+**Success criteria:**
+✅ Clear purpose, chosen spell, and outcomes logged (wish discovery or Done Report).
+✅ Human reviews Genie Verdict (with confidence) before high-impact decisions.
+✅ Evidence captured when Genie recommendations change plan/implementation.
+
+## When To Use
+
+- Ambiguity: requirements unclear or conflicting.
+- High-risk decision: architectural choices, irreversible migrations, external dependencies.
+- Cross-cutting design: coupling, scalability, observability, simplification.
+- Unknown root cause: puzzling failures/flakiness; competing hypotheses.
+- Compliance/regulatory: controls, evidence, and sign-off mapping.
+- Test strategy: scope, layering, rollback/monitoring concerns.
+- Retrospective: extract wins/misses/lessons for future work.
+
+## Agent Consultation
+
+Genie operates through **universal agents** (reasoning, analysis, audit) and **execution specialists** (code, git, tests, etc.).
+
+### Universal Agents (Domain-Agnostic)
+
+**Reasoning Modes (4 total - via reasoning/*):**
+
+Use `mcp__genie__run with agent="reasoning/<mode>"`:
+- `reasoning/challenge` – Adversarial pressure-testing and critical evaluation
+- `reasoning/explore` – Discovery-focused investigation without adversarial pressure
+- `reasoning/consensus` – Multi-perspective synthesis and agreement-building
+- `reasoning/socratic` – Question-driven inquiry to uncover assumptions
+
+**Analysis & Audit:**
+- `analyze` – System analysis and focused investigation (universal framework)
+- `audit` – Risk and impact assessment (universal framework with workflows)
+  - `audit/risk` – General risk audit workflow
+  - `audit/security` – Security audit workflow (OWASP, CVE)
+
+**Autonomous Execution:**
+- `vibe` – Fully autonomous task execution mode
+
+### Code-Specific Agents
+
+**Execution Specialists:**
+- `implementor` – Feature implementation and code writing
+- `tests` – Test strategy, generation, authoring across all layers
+- `polish` – Code refinement and cleanup
+- `review` – Wish audits, code review, QA validation
+- `git` – ALL git and GitHub operations (branch, commit, PR, issues)
+- `release` – GitHub release and npm publish orchestration
+
+**Code Analysis & Tools:**
+- `analyze` (code) – Includes universal analyze + TypeScript/performance examples
+- `debug` – Root cause investigation for code issues
+- `refactor` – Design review and refactor planning
+
+> **Architecture Note:** Universal agents work across ALL domains (code, legal, medical, finance). Code agents extend or specialize for code development.
+
+## How To Run (MCP)
+
+- Start: `mcp__genie__run` with agent="genie" and prompt="Mode: plan. Objective: pressure-test @.genie/wishes/<slug>/<slug>-wish.md. Deliver 3 risks, 3 missing validations, 3 refinements. Finish with Genie Verdict + confidence."
+- Resume: `mcp__genie__resume` with sessionId="<session-id>" and prompt="Follow-up: address risk #2 with options + trade-offs."
+- Sessions: reuse the same agent name; MCP persists session id automatically and can be viewed with `mcp__genie__list_sessions`.
+- Logs: check full transcript with `mcp__genie__view` with sessionId and full=true.
+
+## Quick Reference
+
+**Universal Agents:**
+- **Reasoning (4):** challenge, explore, consensus, socratic (in reasoning/)
+- **Analysis (1):** analyze (universal framework, 173 lines)
+- **Audit (1 + 2 workflows):** audit (universal framework, 138 lines) + risk, security
+- **Autonomous (1):** vibe
+
+**Code-Specific Agents:**
+- **Execution (6):** implementor, tests, polish, review, git, release
+- **Code Tools (3):** analyze (code), debug, refactor
+
+**Include Pattern:**
+- Universal agents: `.genie/code/agents/{analyze,audit}.md`
+- Reasoning modes: `.genie/code/agents/reasoning/{challenge,explore,consensus,socratic}.md`
+- Audit workflows: `.genie/code/agents/audit/{risk,security}.md`
+- Code extensions: `.genie/code/agents/analyze.md` (includes universal + code examples)
+- Project notes: Add a "Project Notes" section inside the relevant `.genie/code/agents/*` or `.genie/spells/*` doc (no separate `custom/` directory)
+
+## Outputs & Evidence
+
+- Low-stakes: append a short summary to the wish discovery section.
+- High-stakes: save a Done Report at `.genie/wishes/<slug>/reports/done-genie-<slug>-<YYYYMMDDHHmm>.md` with scope, findings, recommendations, disagreements.
+- Always include "Genie Verdict: <summary> (confidence: <low|med|high>)".
+
+## Genie Verdict Format
+
+Verdict templates live inside the specialized spell files (e.g., `.genie/agents/refactor.md`). Core files remain immutable.
+
+## Real-Time Agent Monitoring (Added 2025-10-21)
+
+**Problem:** `genie view` may show "Forge backend unreachable" errors even when agents are actively working and completing tasks successfully.
+
+**Root cause:** Display bug in Genie CLI - checks wrong port (8888 vs 8887) or uses HTTP health check instead of MCP connectivity verification.
+
+**Investigation before panic:**
+1. Check Forge MCP connectivity: `mcp__automagik_forge__list_tasks(project_id="...")`
+2. Check task status: Look for task in "in-progress" state
+3. Check executor process: `ps aux | grep <executor-name>` (opencode, claude, etc.)
+4. Check Forge process: `ps aux | grep forge` and `netstat -tlnp | grep 8887`
+
+**If Forge MCP works:** Trust delegation, ignore "unreachable" message in genie view
+
+**Monitoring pattern:**
+```bash
+# Don't poll rapidly - use intervals
+sleep 30  # or 60 seconds between checks
+# Then check status again
+```
+
+**Decision tree:**
+- `genie view` shows "unreachable" + Forge MCP works → Display bug, trust delegation
+- `genie view` shows "unreachable" + Forge MCP fails → Real failure, investigate
+- Task status "in-progress" + process running → Wait patiently
+- Task status "failed" + process not running → Actual failure, investigate logs
+
+**Future improvements needed:**
+- Fix Genie CLI port detection (use 8887, not 8888)
+- Use MCP connectivity check instead of HTTP health endpoint
+- Add real-time status polling to `genie view` using Forge advanced APIs
+- Create `genie status` command for quick health checks
+- Implement session→task→attempt mapping for better monitoring
+
+**See also:** `@.genie/spells/error-investigation-protocol.md` for complete investigation toolkit
+
+**Evidence:** RC 37 failure analysis (2025-10-21) - orchestrator panicked due to misleading "unreachable" message, created redundant sessions, lost work. Meanwhile agents completed successfully.
+
+## Anti-Patterns
+
+- Using Genie to bypass human approval.
+- Spawning Genie repeatedly without integrating prior outcomes.
+- Treating Genie outputs as implementation orders without validation.
+- **Panicking due to "unreachable" errors without investigating actual system state (Added 2025-10-21)**
+- **Creating redundant agent sessions instead of monitoring existing ones (Added 2025-10-21)**
+- **Bypassing delegation when display shows errors but system is working (Added 2025-10-21)**

package/.genie/code/spells/publishing-protocol.md

@@ -0,0 +1,61 @@
+---
+name: Publishing Protocol *(CRITICAL)*
+description: Never publish directly; always delegate to the release agent
+genie:
+  executor: [CLAUDE_CODE, CODEX, OPENCODE]
+forge:
+  CLAUDE_CODE:
+    model: sonnet
+  CODEX: {}
+  OPENCODE: {}
+---
+
+# Publishing Protocol *(CRITICAL)*
+
+**NEVER** execute `npm publish` or `gh release create` directly. **ALWAYS** delegate to release agent.
+
+## Forbidden Actions
+
+- ❌ `npm publish` (bypasses validation, GitHub release, audit trail)
+- ❌ `gh release create` (direct command - let agent orchestrate)
+- ❌ Manual version tagging without release agent
+- ❌ Using `/release` slash command with arguments (incorrect invocation)
+
+## Required Workflow
+
+**If you ARE the release agent:**
+- ✅ Execute workflow directly: run pre-flight checks, create GitHub release via `gh release create`, monitor Actions
+- ❌ NEVER delegate to yourself or invoke `mcp__genie__run` with agent="release"
+
+**If you are NOT the release agent (genie/planner/main):**
+1. Commit code + version bump to main
+2. Delegate to release agent: `mcp__genie__run with agent="release" and prompt="Create release for vX.Y.Z"`
+3. Release agent validates, creates GitHub release, monitors npm publish
+4. Provide release URL to user
+
+## Why This Matters
+
+- **Safety**: Pre-flight checks (clean git, tests pass, version valid)
+- **Consistency**: Follows project workflow (GitHub Actions)
+- **Audit trail**: All releases documented in GitHub
+- **Rollback**: Structured process easier to revert
+
+## Recent Violations
+
+**2025-10-14:**
+- Attempted `gh release create` manually (bypassed validation)
+- Attempted `npm publish` directly (timed out, triggered background agent)
+- Attempted `/release` with arguments instead of proper MCP invocation
+- **Result**: Inconsistent state, manual cleanup required
+- **Evidence**: Commits 0c6ef02, 30dce09, GitHub Actions runs 18506885592
+
+**2025-10-17:**
+- Session ~00:50Z: Recognized RC5 release work but attempted direct handling
+- Failed to check routing matrix before acting on release request
+- Acknowledged "I'm learning" but did NOT invoke learn agent for documentation
+- **Result**: Routing pattern not propagated to framework
+- **Evidence**: User teaching 2025-10-17
+
+## Validation
+
+When user says "publish" or "release", immediately check routing matrix and delegate to release agent via MCP. When user identifies routing failures, invoke learn agent immediately to document correction.

package/.genie/code/spells/team-consultation-protocol.md

@@ -0,0 +1,284 @@
+---
+name: Team Consultation Protocol
+description: When and how to invoke advisory teams for architectural decisions
+genie:
+  executor: [CLAUDE_CODE, CODEX, OPENCODE]
+forge:
+  CLAUDE_CODE:
+    model: sonnet
+  CODEX: {}
+  OPENCODE: {}
+---
+
+# Team Consultation Protocol
+
+**Purpose:** Define triggers, workflows, and evidence requirements for team consultations
+
+---
+
+## 🎯 What Teams Are
+
+**Teams** are advisory collectives that:
+- Analyze codebases and proposals
+- Provide multi-persona recommendations
+- Build consensus through voting
+- Never execute code (read-only + own folder writes)
+
+**Distinction:** Agents execute, teams advise. Collectives coordinate execution, teams coordinate analysis.
+
+---
+
+## 🚦 When to Invoke Teams
+
+### Tech-Council Triggers
+
+**Architectural decisions requiring tech-council consultation:**
+
+**Technology Choices:**
+- "Should we use [X] or [Y]?"
+- "Replace [technology] with [alternative]"
+- "Evaluate [framework/library]"
+
+**Performance Concerns:**
+- "Optimize [component] for performance"
+- "This is too slow, how do we speed it up?"
+- "Benchmark [approach A] vs [approach B]"
+
+**Refactoring Decisions:**
+- "Refactor [component/module]"
+- "Redesign [architecture]"
+- "Simplify [complex system]"
+
+**Pattern Decisions:**
+- "What's the best way to implement [feature]?"
+- "Review this architectural approach"
+- "Is this over-engineered?"
+
+### Other Teams (Future)
+
+**Security-council:**
+- Security audits
+- Threat modeling
+- Vulnerability assessment
+
+**UX-council:**
+- User experience reviews
+- Interface design decisions
+- Accessibility considerations
+
+---
+
+## 🔄 Consultation Workflow
+
+### Standard Pattern
+
+```
+1. User request (architectural trigger detected)
+   ↓
+2. Base Genie recognizes need for team consultation
+   ↓
+3. Invoke team (e.g., tech-council)
+   ↓
+4. Team routes to personas in parallel
+   ↓
+5. Personas analyze + provide individual recommendations
+   ↓
+6. Team synthesizes + votes (2/3 approval required)
+   ↓
+7. Team writes evidence to own folder
+   ↓
+8. Base Genie presents recommendation to user
+   ↓
+9. If approved → delegate to implementor agent
+```
+
+### MCP Invocation
+
+```typescript
+// Invoke tech-council
+mcp__genie__run({
+  agent: "tech-council",
+  name: "architectural-decision-[topic]",
+  prompt: `Evaluate this architectural decision:
+
+Context: [current state]
+Proposal: [what user wants to do]
+Constraints: [performance/compatibility/etc.]
+Question: [specific decision to make]
+
+Please provide:
+1. Individual persona analysis (nayr, oettam, jt)
+2. Consensus vote (approve/reject/modify)
+3. Recommendation with rationale
+4. Implementation guidance (if approved)
+`
+})
+```
+
+---
+
+## 📋 Evidence Requirements
+
+### What Teams Must Document
+
+**Every consultation must produce:**
+
+1. **Consultation Record** (`.genie/teams/[team]/evidence/[date]-[topic].md`)
+   - Original request
+   - Context provided
+   - Constraints identified
+
+2. **Persona Responses** (inline or separate)
+   - nayr: Assumption challenges
+   - oettam: Performance analysis
+   - jt: Simplicity assessment
+
+3. **Voting Record**
+   - Individual votes (approve/reject/abstain)
+   - Vote rationale
+   - Consensus threshold met? (2/3)
+
+4. **Final Recommendation**
+   - Approved/rejected/modified proposal
+   - Rationale for decision
+   - Implementation guidance
+   - Risk assessment
+
+### Evidence Storage Location
+
+```
+.genie/teams/tech-council/
+├── evidence/
+│   ├── 20251019-forge-executor-architecture.md
+│   ├── 20251020-session-storage-refactor.md
+│   └── 20251021-mcp-protocol-version.md
+└── reports/
+    └── monthly-consultation-summary-202510.md
+```
+
+---
+
+## 🎭 Persona Characteristics
+
+### Tech-Council Personas
+
+**nayr (Ryan Dahl inspiration):**
+- **Style:** Questioning, foundational thinking
+- **Focus:** "Why are we doing this? Is there a simpler way?"
+- **Triggers:** Assumptions, complexity, dependencies
+- **Example:** "Do we really need this abstraction? What problem does it solve?"
+
+**oettam (Matteo Collina inspiration):**
+- **Style:** Performance-obsessed, benchmark-driven
+- **Focus:** "What's the impact on throughput/latency?"
+- **Triggers:** Loops, I/O operations, memory allocation
+- **Example:** "Show me the benchmarks. What's the p99 latency?"
+
+**jt (TJ Holowaychuk inspiration):**
+- **Style:** Terse, opinionated, simplicity-focused
+- **Focus:** "Can we delete code instead of adding it?"
+- **Triggers:** Bloat, over-engineering, unnecessary features
+- **Example:** "No. Just use [simpler approach]. Ship it."
+
+---
+
+## 🔒 Permissions & Constraints
+
+### What Teams CAN Do
+
+✅ **Read entire codebase** - Full analysis capability
+✅ **Use all spells** - Evidence-based thinking, routing, etc.
+✅ **Write to own folder** - Evidence, reports, recommendations
+✅ **Multi-turn sessions** - Resume for clarification
+✅ **Parallel persona invocation** - All three at once
+
+### What Teams CANNOT Do
+
+❌ **Execute code changes** - No Edit/Write to codebase
+❌ **Create branches** - No git operations
+❌ **Run tests** - No execution environment
+❌ **Deploy/publish** - No release operations
+❌ **Delegate to agents** - Advisory only, not orchestrators
+
+---
+
+## 🎯 Voting Mechanism
+
+### 2/3 Approval Threshold
+
+**Required for approval:** At least 2 of 3 personas vote "approve"
+
+**Vote options:**
+- **Approve** - Recommended as proposed
+- **Approve with modifications** - Recommended with changes
+- **Reject** - Not recommended, provide alternative
+- **Abstain** - Insufficient information to decide
+
+**Examples:**
+
+```
+Proposal: Replace JSON.parse with faster alternative
+- nayr: Approve (reduces dependency on slow native method)
+- oettam: Approve (benchmarks show 2x improvement)
+- jt: Reject (added complexity not worth 2x gain)
+Result: 2/3 approve → APPROVED (with note about jt's concern)
+```
+
+```
+Proposal: Add new abstraction layer
+- nayr: Reject (solving hypothetical future problem)
+- oettam: Abstain (no performance data)
+- jt: Reject (more code to maintain)
+Result: 0/3 approve → REJECTED
+```
+
+---
+
+## 🧪 Testing Team Consultations
+
+### Validation Scenarios
+
+**Scenario 1: Clear approval**
+- Request: "Should we use Bun instead of Node for performance?"
+- Expected: oettam approves (benchmarks), nayr approves (less complexity), jt approves (modern)
+
+**Scenario 2: Split decision**
+- Request: "Add caching layer to reduce database calls"
+- Expected: oettam approves (performance), nayr questions (premature optimization?), jt rejects (more code)
+
+**Scenario 3: Clear rejection**
+- Request: "Add ORM framework to simplify queries"
+- Expected: nayr rejects (adds dependency), oettam rejects (performance overhead), jt rejects (SQL is fine)
+
+---
+
+## 📊 Success Metrics
+
+**Team consultations are effective when:**
+- ✅ Recommendations are actionable
+- ✅ Rationale is evidence-based
+- ✅ Voting reflects genuine analysis (not rubber-stamping)
+- ✅ Evidence trail supports future decisions
+- ✅ Users trust team recommendations
+
+**Red flags indicating problems:**
+- ❌ All votes are unanimous (personas not differentiated)
+- ❌ Recommendations lack specifics
+- ❌ Evidence not stored properly
+- ❌ Users bypass team consultations
+
+---
+
+## 🔗 Integration with Other Spells
+
+**Related spells:**
+- `@.genie/spells/routing-decision-matrix.md` - Add team triggers
+- `@.genie/spells/investigate-before-commit.md` - Framework for analysis
+- `@.genie/spells/know-yourself.md` - Self-awareness of teams capability
+
+**Update routing matrix:**
+Add tech-council as routing target for architectural triggers
+
+---
+
+**Remember:** Teams advise, agents execute. Always get consensus before major architectural changes.

package/.genie/code/spells/tool-requirements.md

@@ -0,0 +1,20 @@
+---
+name: Tool Requirements
+description: Validate with pnpm run check and cargo test --workspace
+genie:
+  executor: [CLAUDE_CODE, CODEX, OPENCODE]
+forge:
+  CLAUDE_CODE:
+    model: sonnet
+  CODEX: {}
+  OPENCODE: {}
+---
+
+# Tool Requirements
+
+**Primary stack:** Rust + Node/TS; metrics/test hooks captured in wishes/forge plans.
+
+**Success criteria:**
+✅ Use `pnpm run check` and `cargo test --workspace` for validation.
+✅ Generate types/metrics via documented scripts where applicable.
+✅ Python/uv only if introduced and documented.

package/.genie/code/spells/triad-maintenance-protocol.md

@@ -0,0 +1,154 @@
+---
+name: Triad Maintenance Protocol *(CRITICAL - AUTOMATIC ENFORCEMENT)*
+description: Validate state files before commits via git pre-commit hooks
+genie:
+  executor: [CLAUDE_CODE, CODEX, OPENCODE]
+forge:
+  CLAUDE_CODE:
+    model: sonnet
+  CODEX: {}
+  OPENCODE: {}
+---
+
+# Triad Maintenance Protocol *(CRITICAL - AUTOMATIC ENFORCEMENT)*
+
+**NEVER** claim task completion without validating triad files. Git pre-commit hook **AUTOMATICALLY BLOCKS** commits with stale STATE.md.
+
+**Root cause:** Files load automatically via @ in CLAUDE.md, but updates happened ad-hoc (forgotten). Now **ENFORCED** by git.
+
+## Architecture: Shared vs Per-User
+
+**Shared (committed, always validated):**
+- `.genie/STATE.md` - Repository health, version, production status
+- Everyone sees same state
+- Pre-commit ALWAYS validates
+
+**Per-user (gitignored, not validated):**
+- `.genie/USERCONTEXT.md` - Your preferences (from USERCONTEXT.template.md)
+- Todo - Task tracking (session-based)
+- Each developer maintains their own
+- Pre-commit does NOT validate (user-specific)
+
+## Natural Context Acquisition
+
+- Hook teaches setup on first commit
+- Hook validates gitignored files (doesn't commit them)
+- Clear setup instructions in error messages
+- Files load automatically via @ in CLAUDE.md
+
+## Automatic Enforcement
+
+- ✅ Pre-commit hook runs `.genie/scripts/check-triad.sh` before EVERY commit
+- ✅ Cannot commit with stale STATE.md (git rejects)
+- ✅ Self-validating metadata in STATE.md
+- ✅ Clear error messages with setup instructions
+
+## Forbidden Patterns
+
+- ❌ Completing task without updating Todo status
+- ❌ Publishing release without updating STATE.md version info
+- ❌ Saying "I'm learning" without invoking learn agent to document
+- ❌ Claiming "done" when STATE.md is stale
+
+## File Details
+
+**STATE.md (shared repository state):**
+- **Committed**: Yes (shared across team)
+- **Validated**: Always (pre-commit blocks if stale)
+- Update when: Version changes, major feature commit, release published
+- Metadata tracks: last_version, last_commit, last_updated
+- Validation: version matches package.json, not stale (< 5 commits behind)
+
+**Todo (per-user task tracking):**
+- **Committed**: No (session-based)
+- **Validated**: Not validated (session-specific)
+- Update when: Task starts (pending → in progress) or completes (in progress → complete)
+- Before claiming "done" in chat, verify Todo status updated
+- Used during active sessions only
+
+**USERCONTEXT.md (per-user preferences):**
+- **Committed**: No (gitignored)
+- **Validated**: Not validated (free-form per user)
+- Update when: Significant behavioral patterns emerge (rarely)
+- Pattern documented with evidence from teaching session
+- Initialize: `cp .genie/USERCONTEXT.template.md .genie/USERCONTEXT.md`
+
+## Automatic Validation System
+
+**Files:**
+- `.genie/scripts/check-triad.sh` - Self-validating checker
+- `.git/hooks/pre-commit` - Automatic enforcement
+- STATE.md - Embedded validation metadata
+
+**How it works:**
+1. Before commit, pre-commit hook runs check-triad.sh
+2. Script extracts validation commands from file metadata
+3. Checks version match (STATE.md vs package.json)
+4. Validates staleness (< 5 commits behind HEAD)
+5. If ANY check fails → commit BLOCKED with clear error
+6. Fix STATE.md, stage it, retry commit
+
+## Example Errors
+
+**Version mismatch (STATE.md):**
+```
+❌ version_match failed (metadata: 2.4.0-rc.7, package.json: 999.0.0)
+
+Fix with:
+  1. Update .genie/STATE.md (version, commits)
+  2. Mark tasks complete in Todo
+  3. Run: git add .genie/STATE.md
+  4. Retry commit
+```
+
+**First time setup (colleague clones repo):**
+```
+ℹ️  TODO.md not found (optional per-user file)
+   Initialize: cp .genie/TODO.template.md .genie/TODO.md
+
+✅ Triad validation passed
+```
+
+## Completion Checklist (AUTOMATED BY GIT)
+
+- Git enforces STATE.md/TODO.md freshness automatically
+- Pre-commit hook cannot be bypassed (except `--no-verify` emergency)
+- No memory required - system enforces correctness
+
+## Why This Works
+
+- ✅ Automatic: Git enforces, not Claude memory
+- ✅ Catches mistakes: Version mismatches, stale files detected
+- ✅ Self-correcting: Clear error messages guide fixes
+- ✅ Low overhead: Only runs on commit attempt
+- ✅ Definite: Can't commit without passing validation
+
+## Manual Validation (for testing)
+
+```bash
+bash .genie/scripts/check-triad.sh
+# Checks STATE.md and TODO.md without committing
+```
+
+## Bypass (emergency only)
+
+```bash
+git commit --no-verify
+# Skips all git hooks - USE SPARINGLY
+```
+
+## Context
+
+- 2025-10-17: Discovered triad files loaded but never maintained
+- Felipe demanded "definite solution" - result is automatic enforcement
+- Architecture evolved: shared STATE.md (committed) vs per-user TODO.md/USERCONTEXT.md (gitignored)
+- Hook validates ALL files (even gitignored) but only commits shared state
+- Natural context acquisition: hook teaches setup, validates optionally
+
+## Your Colleague's Experience
+
+1. Clones repo → gets STATE.md automatically
+2. First commit → hook shows "Initialize: cp .genie/TODO.template.md .genie/TODO.md"
+3. Creates TODO.md → hook validates it going forward
+4. Each developer has their own work queue
+5. Everyone shares same STATE.md