pgserve 2.1.3 → 2.2.1

package/.genie/code/spells/emoji-naming-convention.md

@@ -1,303 +0,0 @@
-# 🎨 Emoji Naming Convention
-**Version:** 1.0.0
-**Status:** ACTIVE
-**Approved By:** Felipe (2025-10-21)
-
----
-
-## 🎯 Mission
-
-**Universal visual language across all systems:**
-- GitHub issues = same emoji as Forge tasks = same emoji as Agent sessions
-- Instant recognition without reading title
-- Same language everywhere: Genie ↔ Forge ↔ GitHub
-
----
-
-## 📋 Standard Format
-
-```
-[<emoji>] <Type>: <Title> (#GitHubIssue)
-```
-
-**Brackets provide:**
-- Structure for extraction/parsing
-- Visual framing that makes emojis pop
-- Clear boundaries between emoji and text
-
-**Examples:**
-```
-[🐛] Bug: Forge executor hardcodes base_branch (#154)
-[💭] Wish: MCP Server Authentication (#152)
-[📚] Learn: Task Naming Convention Standardization (#157)
-[⚙️] Forge: Drop-in replacement executor (#143)
-[🤖] implementor: background
-```
-
----
-
-## 🎨 Work Type Emojis
-
-### Core Work Types
-
-| Emoji | Type | When To Use |
-|-------|------|-------------|
-| 🐛 | Bug | Something broken, needs fixing |
-| 💭 | Wish | Discovery/planning for new features |
-| 📚 | Learn | Research, investigation, knowledge capture |
-| ⚙️ | Forge | Implementation of approved work |
-| ✅ | Review | Quality assurance, validation |
-| 🔨 | Refactor | Code improvement without new features |
-| 📖 | Docs | Writing/updating documentation |
-| 🧹 | Chore | Maintenance, dependencies, housekeeping |
-
----
-
-## 🧞 Agent Emojis
-
-### Core Orchestrators
-
-| Emoji | Agent | Usage |
-|-------|-------|-------|
-| 🧞 | Genie | Main orchestrator |
-| 💭 | Wish | Wish dance orchestrator |
-| ⚙️ | Forge | Task breakdown |
-| ✅ | Review | Quality validation |
-
-### Specialist Agents
-
-| Emoji | Agent | Usage |
-|-------|-------|-------|
-| 🤖 | Implementor | Code implementation (robot) |
-| 🤖 | Tests | Test writing (robot) |
-| 🤖 | Polish | Code polishing (robot) |
-| 🤖 | Refactor | Code refactoring (robot) |
-| 🚀 | Release | Release management |
-| ✍️ | Prompt | Instruction writing |
-| 🔧 | Git | GitHub operations |
-| 📝 | Commit | Commit crafting |
-| 🔍 | Debug | Debugging |
-| 🏗️ | Install | Installation |
-
-**Note:** 🤖 Robot emoji for all execution agents (they do the work)
-
-### Thinking Modes
-
-| Emoji | Agent | Usage |
-|-------|-------|-------|
-| 🧠 | Analyze | Deep analysis |
-| 🎯 | Plan | Strategic planning |
-| 🤔 | Socratic | Questioning/learning |
-| 🔬 | Deep-Dive | Detailed investigation |
-| 🎓 | Explore | Codebase exploration |
-
----
-
-## 🎯 Usage Guidelines
-
-### When Creating Forge Tasks
-
-**Format:**
-```typescript
-await mcp__automagik_forge__create_task({
-  project_id: projectId,
-  title: "[🐛] Bug: Clear description of the bug (#GitHubIssueNumber)",
-  description: "Full context here..."
-});
-```
-
-**Rules:**
-1. **Choose ONE emoji** from work type table
-2. **Wrap in brackets:** `[🐛]` not `🐛`
-3. **Match work type:** Bug=🐛, Wish=💭, Learn=📚, Forge=⚙️, etc.
-4. **Include GitHub issue:** `(#NNN)` at end of title
-5. **Keep title ≤ 80 characters** including emoji and brackets
-
-### When Creating GitHub Issues
-
-**Format:**
-```bash
-gh issue create \
-  --title "[🐛] Bug: Clear description of the bug" \
-  --body "Full description..." \
-  --label "type:bug,area:forge"
-```
-
-**After creation, update Forge task to include issue number:**
-```typescript
-await mcp__automagik_forge__update_task({
-  task_id: taskId,
-  title: "[🐛] Bug: Clear description (#157)"  // Add issue number
-});
-```
-
-### When Starting Agent Sessions
-
-**Format:**
-```typescript
-await mcp__genie__run({
-  agent: "implementor",
-  name: "[🤖] implementor: fix-forge-base-branch",
-  prompt: "Fix base branch hardcoding..."
-});
-```
-
-**Pattern:** `[<emoji>] <Agent>: <brief-description>`
-
-**Note:** Agent session names are auto-generated by forge-executor.ts with correct emoji
-
----
-
-## 📋 Decision Tree
-
-**"Which emoji should I use?"**
-
-### For Tasks
-1. **Is it broken?** → [🐛] Bug
-2. **New feature (planning)?** → [💭] Wish
-3. **New feature (implementing)?** → [⚙️] Forge
-4. **Research/investigation?** → [📚] Learn
-5. **Quality check?** → [✅] Review
-6. **Clean up code?** → [🔨] Refactor
-7. **Write docs?** → [📖] Docs
-8. **Maintenance?** → [🧹] Chore
-
-### For Agent Sessions
-1. **Which agent am I starting?**
-2. **Find agent in emoji table**
-3. **Use that emoji in brackets**
-
-Example: Starting implementor → [🤖] implementor
-
----
-
-## ✅ Examples by Scenario
-
-### Bug Fix Workflow
-```
-GitHub: [🐛] Bug: Forge executor hardcodes base_branch
-Forge:  [🐛] Bug: Forge executor hardcodes base_branch (#154)
-Agent:  [🤖] implementor: fix-forge-base-branch-hardcoding
-```
-
-### Wish Workflow
-```
-GitHub: [💭] Wish: MCP Server Authentication
-Forge:  [💭] Wish: MCP Server Authentication (#152)
-Agent:  [💭] wish: mcp-auth-discovery
-        [⚙️] forge: mcp-auth-execution-plan
-        [🤖] implementor: mcp-auth-endpoints
-        [✅] review: mcp-auth-validation
-```
-
-### Learn Task
-```
-GitHub: [📚] Learn: Task Naming Convention Standardization
-Forge:  [📚] Learn: Task Naming Convention Standardization (#157)
-Forge:  [🧹] Chore: Unified Emoji Naming Convention (updated from Learn to Chore per Felipe)
-```
-
----
-
-## 🚫 Common Mistakes
-
-### ❌ Wrong Format
-```
-Bad:  Task 1: Forge Project Auto-Sync
-Bad:  🧹 Chore: Missing brackets
-Good: [🧹] Chore: Forge Project Auto-Sync on MCP Startup
-```
-
-### ❌ Missing Issue Reference
-```
-Bad:  [🐛] Bug: Forge executor hardcodes base_branch
-Good: [🐛] Bug: Forge executor hardcodes base_branch (#154)
-```
-
-### ❌ Wrong Emoji
-```
-Bad:  [🐛] Bug: Add new authentication feature  (not a bug!)
-Good: [💭] Wish: MCP Server Authentication
-```
-
-### ❌ Multiple Emojis
-```
-Bad:  [🐛💭] Bug Wish: Something confusing
-Good: [🐛] Bug: Clear single-purpose title
-```
-
----
-
-## 🎨 Emoji Quick Reference (Copy-Paste)
-
-```
-Work Types:
-[🐛] Bug          [💭] Wish         [📚] Learn        [⚙️] Forge
-[✅] Review       [🔨] Refactor     [📖] Docs         [🧹] Chore
-
-Execution Agents (Robots):
-[🤖] implementor  [🤖] tests        [🤖] polish       [🤖] refactor
-
-Core Agents:
-[🧞] genie        [🔧] git          [🚀] release      [📝] commit
-[✍️] prompt       [🔍] debug        [🏗️] install
-
-Thinking:
-[🧠] analyze      [🎯] plan         [🤔] socratic     [🔬] deep-dive
-[🎓] explore
-```
-
----
-
-## 📚 Implementation Checklist
-
-**When creating Forge tasks:**
-- [ ] Choose emoji from work type table
-- [ ] Format: `[<emoji>] <Type>: <Title> (#Issue)`
-- [ ] Wrap emoji in brackets: `[🐛]` not `🐛`
-- [ ] Verify title ≤ 80 characters (including brackets)
-- [ ] Include GitHub issue number
-- [ ] Same emoji across all systems
-
-**When creating GitHub issues:**
-- [ ] Choose emoji from work type table
-- [ ] Format: `[<emoji>] <Type>: <Title>`
-- [ ] Wrap emoji in brackets
-- [ ] Add appropriate labels
-- [ ] Update Forge task with issue number after creation
-
-**When starting agent sessions:**
-- [ ] Choose emoji from agent table
-- [ ] Format: `[<emoji>] <agent>: <description>`
-- [ ] Use robot emoji [🤖] for execution agents
-- [ ] Keep description brief and clear
-- [ ] Auto-generated by forge-executor.ts
-
----
-
-## 🔗 Related Documentation
-
-- **Full Spec:** `.genie/reports/emoji-naming-standard.md` - Complete taxonomy
-- **Proposals:** `.genie/reports/task-naming-5-proposals.md` - How we chose emoji format
-- **Mapping:** `.genie/reports/task-rename-mapping.md` - Before/after examples
-
----
-
-## ✨ Benefits
-
-**Why emojis?**
-1. ⚡ **60,000x faster** visual recognition than text
-2. 🎨 **Universal** - works across all platforms (GitHub, Forge, CLI)
-3. 🔍 **Scannable** - find tasks by visual shape, not reading
-4. 🌍 **Language-agnostic** - same meaning globally
-5. 🎯 **Consistent** - one language everywhere
-
-**Impact:**
-- Faster kanban scanning
-- Instant task type recognition
-- Unified developer experience
-- Reduced cognitive load
-
----
-
-**Remember:** Same emoji = same meaning = same language everywhere 🎯

package/.genie/code/spells/evidence-storage.md

@@ -1,26 +0,0 @@
----
-name: Evidence & Storage Conventions
-description: Declare artifact locations and maintain evidence checklists
-genie:
-  executor: [CLAUDE_CODE, CODEX, OPENCODE]
-forge:
-  CLAUDE_CODE:
-    model: sonnet
-  CODEX: {}
-  OPENCODE: {}
----
-
-# Evidence & Storage Conventions
-
-## Evidence Requirements
-
-- Wishes must declare where artefacts live; there is no default `qa/` directory. Capture metrics inline in the wish (e.g., tables under a **Metrics** section) or in clearly named companion files.
-- Every wish must complete the **Evidence Checklist** block before implementation begins, spelling out validation commands, artefact locations, and approval checkpoints.
-- External tracker IDs live in the wish markdown (for example a **Tracking** section with `Forge task: FORGE-123`).
-- Background agent outputs are summarised in the wish context ledger; raw logs can be viewed with `mcp__genie__view` with sessionId parameter.
-
-## Testing & Evaluation
-
-- Evaluation tooling is optional. If a project adds its own evaluator agent, the review or plan workflow can reference it; otherwise, evaluation steps default to manual validation.
-- Typical metrics: `{{METRICS}}` such as latency or quality. Domain-specific metrics should be added per project in the wish/forge plan.
-- Validation hooks should be captured in wishes/forge plans (e.g., `pnpm test`, `cargo test`, metrics scripts).

package/.genie/code/spells/file-naming-rules.md

@@ -1,35 +0,0 @@
----
-name: File and Naming Rules
-description: Centralize planning and evidence under .genie/, avoid doc sprawl
-genie:
-  executor: [CLAUDE_CODE, CODEX, OPENCODE]
-forge:
-  CLAUDE_CODE:
-    model: sonnet
-  CODEX: {}
-  OPENCODE: {}
----
-
-# File and Naming Rules
-
-**Purpose:** Maintain tidy workspace; centralize planning and evidence under `.genie/`.
-
-## Success Criteria
-
-✅ No doc sprawl; update existing files instead of duplicating.
-✅ Purpose-driven names; avoid hyperbole.
-✅ Wishes/evidence paths normalized.
-
-## Forbidden Actions
-
-❌ Create documentation outside `.genie/` without instruction.
-❌ Use forbidden naming patterns (fixed, improved, updated, better, new, v2, _fix, _v, enhanced, comprehensive).
-
-## Path Conventions
-
-- Wishes: `.genie/wishes/<slug>/<slug>-wish.md`.
-- Evidence: declared by each wish (pick a clear folder or append directly in-document).
-- Forge plans: recorded in CLI output—mirror essentials back into the wish.
-- Blockers: logged inside the wish under a **Blockers** or status section.
-- Reports: `.genie/wishes/<slug>/reports/` (wish-specific Done Reports) or `.genie/reports/` (framework-level reports).
-- State: `.genie/state/` is ONLY for session tracking data (agents/sessions.json, logs); NEVER for reports.

package/.genie/code/spells/forge-code-blueprints.md

@@ -1,195 +0,0 @@
----
-name: Forge Blueprints
-description: Templates for groups, plans, task files, and error handling
-genie:
-  executor: [CLAUDE_CODE, CODEX, OPENCODE]
-forge:
-  CLAUDE_CODE:
-    model: sonnet
-  CODEX: {}
-  OPENCODE: {}
----
-
-# Forge Blueprints
-
-## Group Blueprint
-```
-### Group {Letter} – {descriptive-slug}
-- **Scope:** Clear boundaries of what this group accomplishes
-- **Inputs:** `@file.rs`, `@doc.md`, `@.genie/wishes/<slug>/<slug>-wish.md`
-- **Deliverables:**
-  - Code changes: specific files/modules
-  - Tests: unit/integration coverage
-  - Documentation: updates needed
-- **Evidence:**
-  - Location: `.genie/wishes/<slug>/qa/group-{letter}/`
-  - Contents: test results, metrics, logs, screenshots (per wish/custom guidance)
-- **Evaluation Matrix Impact:**
-  - Discovery checkpoints this group addresses (ref: wish evaluation matrix)
-  - Implementation checkpoints this group targets
-  - Verification evidence this group must produce
-- **Branch strategy:**
-  - Default: `feat/<wish-slug>`
-  - Alternative: Use existing `<branch>` (justify: already has related changes)
-  - Micro-task: No branch, direct to main (justify: trivial, low-risk)
-- **Tracker:**
-  - External: `JIRA-123` or `LINEAR-456`
-  - Placeholder: `placeholder-group-{letter}` (create actual ID before execution)
-  - Task file: `.genie/wishes/<slug>/task-{letter}.md`
-- **Suggested personas:**
-  - Primary: implementor (implementation)
-  - Support: tests (test coverage), polish (linting)
-- **Dependencies:**
-  - Prior groups: ["group-a"] (must complete first)
-  - External: API deployment, database migration
-  - Approvals: Security review, design sign-off
-- **Genie Gates (optional):**
-  - Pre-execution: `planning` mode for architecture review
-  - Mid-execution: `consensus` for trade-off decisions
-  - Post-execution: `deep-dive` for performance analysis
-- **Validation Hooks:**
-  - Commands/scripts: reference `@.genie/code/agents/tests.md`, `@.genie/code/agents/implementor.md`, or wish-specific instructions
-  - Success criteria: All tests green, no regressions
-  - Matrix scoring: Targets X/100 points (specify which checkpoints)
-```
-
-## Plan Blueprint
-```
-# Forge Plan – {Wish Slug}
-**Generated:** 2024-..Z | **Wish:** @.genie/wishes/{slug}/{slug}-wish.md
-**Task Files:** `.genie/wishes/<slug>/task-*.md`
-
-## Summary
-- Objectives from spec_contract
-- Key risks and dependencies
-- Branch strategy: `feat/<wish-slug>` (or alternative with justification)
-
-## Spec Contract (from wish)
-[Extracted <spec_contract> content]
-
-## Proposed Groups
-### Group A – {slug}
-- **Scope:** …
-- **Inputs:** `@file`, `@doc`
-- **Deliverables:** …
-- **Evidence:** Store in `.genie/wishes/<slug>/qa/group-a/`
-- **Branch:** `feat/<wish-slug>` or existing
-- **Tracker:** JIRA-123 (or placeholder)
-- **Suggested personas:** implementor, tests
-- **Dependencies:** …
-
-## Validation Hooks
-- Commands or scripts to run per group
-- Evidence storage paths:
-  - Group A: `.genie/wishes/<slug>/qa/group-a/`
-  - Group B: `.genie/wishes/<slug>/qa/group-b/`
-  - Logs: `.genie/wishes/<slug>/qa/validation.log`
-
-## Task File Blueprint
-# Task A - <descriptive-name>
-**Wish:** @.genie/wishes/<slug>/<slug>-wish.md
-**Group:** A
-**Persona:** implementor
-**Tracker:** JIRA-123 (or placeholder)
-**Status:** pending
-
-## Scope
-[What this task accomplishes]
-
-## Inputs
-- `@file.rs`
-- @doc.md
-
-## Validation
-- Commands: reference `@.genie/code/agents/tests.md`
-- Evidence: wish `qa/` + `reports/` folders
-
-## Approval Log
-- [timestamp] Pending approval by …
-
-## Follow-up
-- Checklist of human actions before/during execution
-- MCP commands for background personas: `mcp__genie__run` with agent and prompt parameters
-- PR template referencing wish slug and this forge plan
-```
-
-## Task File Blueprint (Standalone)
-```markdown
-# Task: <group-name>
-
-## Context
-**Wish:** @.genie/wishes/<slug>/<slug>-wish.md
-**Group:** A - <descriptive-name>
-**Tracker:** JIRA-123 (or placeholder)
-**Persona:** implementor
-**Branch:** feat/<wish-slug>
-
-## Scope
-[What this group accomplishes]
-
-## Inputs
-- `@file1.rs`
-- `@file2.md`
-
-## Deliverables
-- Code changes
-- Tests
-- Documentation
-
-## Validation
-- Commands/scripts: see `@.genie/code/agents/tests.md` and wish-specific instructions
-
-## Dependencies
-- None (or list prior groups)
-
-## Evidence
-- Store results in the wish `qa/` + `reports/` folders
-```
-
-## Error Handling
-
-### Common Issues & Solutions
-| Issue | Detection | Solution |
-|-------|-----------|----------|
-| No spec_contract | Missing `<spec_contract>` tags | Request wish update with spec |
-| Circular dependencies | Group A needs B, B needs A | Restructure groups or merge |
-| Missing personas | Referenced agent doesn't exist | Use available agents |
-| Invalid branch name | Over 48 chars or special chars | Truncate and sanitize |
-| Task file exists | Previous task not complete | Archive or update existing |
-
-### Graceful Degradation
-- If task file creation fails, generate forge plan anyway with warning
-- If evidence paths can't be created, document in plan for manual creation
-- If external tracker unreachable, use placeholder IDs
-
-## Blocker Protocol
-
-When forge planning encounters issues:
-
-1. **Create Blocker Report:**
-   ```markdown
-   # Blocker Report: forge-<slug>-<timestamp>
-   Location: .genie/wishes/<slug>/reports/blocker-forge-<slug>-<YYYYMMDDHHmm>.md
-
-   ## Issue
-   - Missing spec_contract in wish
-   - Conflicting dependencies between groups
-   - Unable to determine branch strategy
-
-   ## Investigation
-   [What was checked, commands run]
-
-   ## Recommendations
-   - Update wish with spec_contract
-   - Reorder groups to resolve dependencies
-   - Specify branch in wish metadata
-   ```
-
-2. **Update Status:**
-   - Mark wish status as "BLOCKED" in wish status log
-   - Note blocker in wish status log
-
-3. **Notify & Halt:**
-   - Return blocker report reference to human
-   - Do not proceed with forge plan generation
-   - Wait for wish updates or guidance