pantheon-opencode 1.0.0 → 1.0.6

package/src/skills/codemap/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: codemap
+description: Generates hierarchical repository maps so agents understand codebase structure without re-reading every file
+---
+
+# Codemap
+
+Generate a hierarchical map of the codebase to understand its structure, key modules, and entry points.
+
+## When to Use
+
+- Starting work on an unfamiliar codebase
+- Before planning a cross-cutting change
+- After significant refactoring
+- When you need to understand module boundaries
+
+## How to Generate
+
+1. **Top-level structure**: List directories, entry points, config files
+2. **Module boundaries**: Identify public APIs, internal modules, shared utilities
+3. **Data flow**: Trace how data moves between layers
+4. **Output**: Structured markdown with hierarchy, purpose, and key files per module
+
+## Format
+
+```markdown
+# Codemap: <project-name>
+
+## Structure
+<top-level tree>
+
+## Modules
+| Module | Purpose | Key Files | Entry Points |
+|--------|---------|-----------|--------------|
+
+## Data Flow
+<description of how data moves through the system>
+
+## Dependencies
+| External | Purpose | Version |
+|----------|---------|---------|
+```
+
+## Rules
+- Focus on structure, not implementation details
+- Max 3 levels deep unless a module is critical
+- Return to agent: "Codemap generated. Send to @athena for planning."

package/src/skills/loop-engineering/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: loop-engineering
+description: Iterative refinement pattern for complex problems — solve, review, improve, repeat in controlled cycles
+---
+
+# Loop Engineering
+
+Controlled iterative refinement for complex problems. Each loop tightens the solution without expanding scope.
+
+## When to Use
+
+- Algorithm design with multiple valid approaches
+- Performance optimization (measure → change → measure)
+- API design that needs ergonomic feedback
+- Complex business logic with edge cases
+- UI/UX refinement cycles
+
+## Loop Structure
+
+```
+Loop 1: Baseline → Implement simplest working version
+   ↓ review
+Loop 2: Improve → Optimize for <metric>
+   ↓ review  
+Loop 3: Polish → Edge cases, error handling, DX
+   ↓ review
+Done
+```
+
+## Per-Loop Rules
+
+| Phase | Max Duration | Focus | Skip If |
+|-------|-------------|-------|---------|
+| Baseline | 3 turns | Working solution | Problem is well-understood |
+| Improve | 5 turns | Performance/quality | Baseline meets requirements |
+| Polish | 3 turns | Edge cases, DX | Change is internal/non-user-facing |
+
+## Termination Conditions
+
+Stop looping when:
+- Acceptance criteria are met
+- 3 loops completed
+- Diminishing returns: last loop improved < 10%
+- @themis blocks and recommends a different approach
+
+## Rules
+- Max 3 loops per task (hard limit)
+- Each loop must have a clear success/fail gate
+- After loop 3: stop and deliver regardless of perfection
+- Escalate to @zeus if task needs more than 3 loops
+- Document what was learned in each loop for @mnemosyne

package/src/skills/reflect/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: reflect
+description: Turns repeated workflow friction into reusable skills, agents, or configuration improvements
+---
+
+# Reflect
+
+After completing a task, reflect on what could be improved in the workflow itself. Turn recurring patterns into reusable assets.
+
+## When to Use
+
+- After completing a complex feature
+- When you notice the same manual steps repeating
+- After debugging something that should have been automated
+- At the end of a work session
+
+## Reflection Checklist
+
+| Question | If Yes → |
+|----------|----------|
+| Did I repeat the same search 3+ times? | → Create a command or skill |
+| Did I follow the same steps manually? | → Create a recipe/checklist |
+| Did I debug something preventable? | → Add a lint rule or test |
+| Did I context-switch between tools? | → Create an automation script |
+| Did I need info I didn't have? | → Add to memory-bank or instructions |
+
+## Output
+
+```markdown
+## Reflection
+
+### What went well
+- ...
+
+### What was friction
+- ... (3+ repeats = automation opportunity)
+
+### Action Items
+- [ ] Create skill: <name>
+- [ ] Add instruction: <topic>
+- [ ] Update agent: <agent-name>
+- [ ] Add test: <scenario>
+```
+
+## Rules
+- Be specific: "Searched for auth patterns 4x" not "too much searching"
+- One action item per friction point
+- Escalate to @mnemosyne for memory-bank updates
+- At end: "Reflection complete. Action items created."

package/src/skills/simplify/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: simplify
+description: Behavior-preserving code simplification for readability, maintainability, and reduced complexity
+---
+
+# Simplify
+
+Simplify code while preserving its exact behavior. Focus on reducing complexity without changing semantics.
+
+## When to Use
+
+- Functions with high cyclomatic complexity
+- Deeply nested conditionals
+- Overly abstracted code (YAGNI violations)
+- Duplicated logic that can be consolidated
+- Over-engineered solutions
+
+## Simplification Patterns
+
+| Pattern | Before | After |
+|---------|--------|-------|
+| Extract method | Large function | Focused functions |
+| Consolidate conditionals | Nested ifs | Guard clauses |
+| Remove dead code | Unused params/vars | Clean signatures |
+| Inline abstraction | 1-use wrappers | Direct calls |
+| Simplify state | Mutable state | Pure functions |
+
+## Verification
+
+After each simplification:
+1. Run tests (`pytest`, `npm test`)
+2. Verify no behavior change
+3. If no tests exist: add minimal characterization tests first
+
+## Rules
+- Never change public API signatures without explicit approval
+- One simplification pass per function, then verify
+- If tests fail: revert and try a different approach
+- Escalate to @themis if simplification touches 5+ files

package/src/skills/verification-planning/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: verification-planning
+description: Plans an evidence path before non-trivial changes, ensuring changes are testable and verifiable
+---
+
+# Verification Planning
+
+Before making non-trivial changes, plan how you'll verify correctness. Define the evidence needed to confirm the change works.
+
+## When to Use
+
+- Before any change that touches 3+ files
+- Before database migrations or schema changes
+- Before API contract changes
+- Before dependency upgrades
+- Before refactoring critical paths
+
+## Plan Structure
+
+```markdown
+## Verification Plan
+
+### Change Scope
+- Files to modify: <list>
+- Risk level: <low|medium|high>
+
+### Verification Strategy
+| What to verify | How to verify | Tool/Command | Expected Outcome |
+|----------------|---------------|-------------|------------------|
+
+### Rollback Plan
+- <how to revert if something goes wrong>
+
+### Acceptance Criteria
+- [ ] All existing tests pass
+- [ ] New tests cover changed paths
+- [ ] No regression in <critical metric>
+- [ ] Rollback tested
+```
+
+## Risk Levels
+
+| Level | Triggers | Verification Required |
+|-------|----------|----------------------|
+| Low | 1-2 files, bounded scope | Existing tests pass |
+| Medium | 3-5 files, shared logic | New tests for changed paths |
+| High | 5+ files, schema/API changes | Full plan + rollback test |
+
+## Rules
+- Verification plan must be approved by @themis before implementation
+- Low risk: inline verification (1-2 lines in the task description)
+- Escalate to @athena if verification plan reveals unknown scope

package/src/skills/worktrees/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: worktrees
+description: Git worktrees as safe, isolated coding lanes for risky or parallel work without affecting the main workspace
+---
+
+# Worktrees
+
+Use git worktrees to create isolated working directories for parallel or experimental changes.
+
+## When to Use
+
+- Working on 2+ features simultaneously
+- Risky refactoring that shouldn't affect the main workspace
+- Reviewing a PR while keeping current work intact
+- Running long-lived experiments
+
+## Setup
+
+```bash
+# Create a worktree
+git worktree add ../project-feature-x feature-x
+
+# List worktrees
+git worktree list
+
+# Remove a worktree
+git worktree remove ../project-feature-x
+```
+
+## Workflow
+
+1. Create worktree: `git worktree add ../<name> <branch>`
+2. Work in the worktree directory
+3. Commit and push from within the worktree
+4. Clean up: `git worktree remove ../<name>`
+5. Delete branch if no longer needed
+
+## Rules
+- Never create worktrees inside the main project directory
+- Name worktrees descriptively: `../project-auth-refactor`
+- Remove worktrees when done (they consume disk space)
+- Worktrees share the same git history — pushing from a worktree is the same as pushing from main
+- Escalate to @iris for branch management if unsure

package/commands/pantheon-bg.md

@@ -1,10 +0,0 @@
----
-description: "List background tasks and their status"
-agent: zeus
----
-
-List all active background subagent tasks:
-
-1. Query `task_status()` for any running task IDs
-2. Show task_id, agent type, timestamp, and state
-3. Keep the user informed of progress

package/commands/pantheon-consolidate.md

@@ -1,11 +0,0 @@
----
-description: "Merge and consolidate memory entries"
-agent: zeus
----
-
-Merge related memory entries and consolidate duplicates:
-
-1. Search for related memories via memory_search
-2. Merge overlapping entries
-3. Remove duplicates via memory_forget
-4. Store consolidated entry via memory_store

package/commands/pantheon-doc.md

@@ -1,10 +0,0 @@
----
-description: "Generate or update project documentation"
-agent: zeus
----
-
-Generate or update project documentation:
-
-1. Check ADRs in `.pantheon/memory-bank/`
-2. Update INSTALLATION.md, README.md, CHANGELOG.md
-3. Use @mnemosyne for memory bank documentation

package/commands/pantheon-hash.md

@@ -1,11 +0,0 @@
----
-description: "Track file changes via content hashing"
-agent: zeus
----
-
-Track file modifications using SHA-256 hashes:
-
-1. Hash all files before edits: kv_store("hash:<path>", sha256(content))
-2. After edits, compare: kv_get("hash:<path>") vs new hash
-3. Report which files changed and by how much
-4. Useful for audit trail and change detection

package/commands/pantheon-todo.md

@@ -1,11 +0,0 @@
----
-description: "Enforce TODO tracking across agents and sessions"
-agent: zeus
----
-
-Track and enforce TODO items:
-
-1. Read current todos via session.todo()
-2. Cross-reference with kv_store("todo:..." entries
-3. Flag stale or overdue items
-4. Suggest next actions for each TODO

package/docs/AGENT-MCP.md

@@ -1,194 +0,0 @@
-# Per-Agent MCP Reference
-
-How each Pantheon agent uses the 3 built-in MCP servers (pantheon-resources,
-pantheon-code-mode, pantheon-memory) plus the optional third-party servers.
-
----
-
-## Overview Matrix
-
-| Agent | Resources | Code-Mode | Memory | context7 | playwright |
-|-------|-----------|-----------|--------|----------|------------|
-| **zeus** | ✅ routing, deepwork | ✅ orchestration | ✅ recall | — | — |
-| **athena** | ✅ agents, routing | ✅ research | ✅ recall | ✅ | — |
-| **apollo** | ✅ agents, skills | ✅ — | ✅ search | ✅ | — |
-| **hermes** | ✅ agents, skills | ✅ build/test | ✅ store, recall | ✅ | ✅ |
-| **aphrodite** | ✅ memory-bank | ✅ build | ✅ store, recall | ✅ | ✅ |
-| **demeter** | ✅ agents, routing | ✅ — | ✅ store, recall | ✅ | — |
-| **themis** | ✅ agents | ✅ lint checks | ✅ search | ✅ | ✅ |
-| **prometheus** | ✅ agents, routing | ✅ deploy scripts | ✅ store, recall | ✅ | — |
-| **hephaestus** | ✅ agents, skills | ✅ — | ✅ search, link | ✅ | — |
-| **nyx** | ✅ routing | ✅ — | ✅ sessions | ✅ | — |
-| **gaia** | ✅ agents | — | minimal | ✅ | — |
-| **iris** | ✅ agents | — | minimal | — | — |
-| **mnemosyne** | ✅ memory-bank | ✅ — | ✅ full (store, recall, export) | — | — |
-| **talos** | ✅ agents, skills | ✅ hotfix scripts | ✅ recall | ✅ | — |
-
----
-
-## pantheon-resources Usage by Agent
-
-| Agent | Resources Used | When | Purpose |
-|-------|---------------|------|---------|
-| **zeus** | `pantheon://routing`, `pantheon://deepwork/{slug}`, `pantheon://agents` | Orchestration | Read routing rules, check deepwork plan/status |
-| **athena** | `pantheon://routing`, `pantheon://agents`, `pantheon://skills/{name}` | Planning | Understand delegation rules, load agent roles |
-| **apollo** | `pantheon://agents`, `pantheon://skills` | Discovery | Identify agents to search for, load domain skills |
-| **hermes** | `pantheon://agents`, `pantheon://skills` | Implementation | Read backend skill instructions |
-| **aphrodite** | `pantheon://memory-bank/{path}` | Frontend work | Read memory bank for architecture context |
-| **demeter** | `pantheon://agents`, `pantheon://routing` | Database work | Understand delegation flow for handoffs |
-| **themis** | `pantheon://agents` | Review | Verify agent capabilities match reviewed code |
-| **prometheus** | `pantheon://agents`, `pantheon://routing` | Infrastructure | Check deployment routing constraints |
-| **hephaestus** | `pantheon://agents`, `pantheon://skills` | AI pipelines | Load RAG pipeline skill instructions |
-| **nyx** | `pantheon://routing` | Monitoring | Read routing rules for anomaly detection |
-| **gaia** | `pantheon://agents` | Remote sensing | Verify agent capabilities |
-| **iris** | `pantheon://agents` | GitHub ops | Reference agent names for PR/issue |
-| **mnemosyne** | `pantheon://memory-bank/{path}` | Documentation | Read and write memory bank files |
-| **talos** | `pantheon://agents`, `pantheon://skills` | Hotfixes | Quick reference to agent files |
-
----
-
-## pantheon-code-mode Usage by Agent
-
-| Agent | Use Case | When |
-|-------|----------|------|
-| **zeus** | Run orchestration sequences — build, test, deploy automation | Multi-phase orchestration |
-| **athena** | Run research automation scripts | During planning phase |
-| **apollo** | Execute automated codebase scanners | Discovery phase |
-| **hermes** | Run `pytest`, `ruff check`, `ruff format` | After implementation, before handoff to Themis |
-| **aphrodite** | Run `npm test`, `biome check` | After implementation, before handoff |
-| **demeter** | Run `pytest` on migration tests | After migration implementation |
-| **themis** | Run lint/quality check scripts during review | Code review phase |
-| **prometheus** | Deploy scripts, Docker builds, CI triggers | Infrastructure phase |
-| **hephaestus** | Run evaluation scripts for AI pipelines | Post-implementation |
-| **talos** | Automated hotfix sequences, batch fixes | Rapid repair |
-
-Agents not listed (**gaia**, **iris**, **nyx**, **mnemosyne**) typically do not
-need script execution for their core workflows.
-
----
-
-## pantheon-memory Usage by Agent
-
-| Agent | Key Tools | When | Why |
-|-------|-----------|------|-----|
-| **zeus** | `memory_recall` | Session start | Recall context about active sprint and decisions |
-| **athena** | `memory_recall` | Planning | Recall past architecture decisions and plans |
-| **apollo** | `memory_search` | Discovery | Search for existing patterns and related files |
-| **hermes** | `memory_store`, `memory_recall`, `memory_search` | Throughout | Store implementation decisions, recall backend patterns |
-| **aphrodite** | `memory_store`, `memory_recall`, `memory_search` | Throughout | Store UI decisions, recall component patterns |
-| **demeter** | `memory_store`, `memory_recall` | Throughout | Store schema decisions, recall migration patterns |
-| **themis** | `memory_search` | Review | Search for past review findings |
-| **prometheus** | `memory_store`, `memory_recall` | Throughout | Store infra decisions, recall deployment patterns |
-| **hephaestus** | `memory_search`, `memory_link` | Throughout | Search for relevant RAG patterns, link AI pipeline decisions |
-| **nyx** | `memory_sessions` | Monitoring | List sessions for observability analysis |
-| **gaia** | `memory_recall` | Session start | Recall analysis context from previous sessions |
-| **iris** | `memory_recall` | Session start | Recall PR/release context |
-| **mnemosyne** | All 14 tools | Documentation | Full memory management — store, recall, export, consolidate |
-| **talos** | `memory_recall` | Session start | Recall hotfix context for rapid fixes |
-
-### Recommended Tool Sequences by Agent
-
-**Zeus** (orchestration):
-```
-memory_recall(context="current sprint context") → start orchestration
-memory_recall(context="planning user auth feature") → delegate to Athena
-```
-
-**Hermes** (backend implementation):
-```
-memory_recall(context="implementing JWT authentication") → recall prior decisions
-...implement...
-memory_store(content="JWT uses refresh token rotation", category="decision", importance=0.9)
-```
-
-**Mnemosyne** (memory steward — deepest integration):
-```
-memory_recall(context="documenting sprint close") → check active context
-memory_export(session_id="sprint-17") → export for archival
-memory_consolidate() → deduplicate before close
-memory_compress(session_id="sprint-17") → compress old entries
-```
-
----
-
-## Third-Party MCP Usage
-
-### context7 (Library Documentation)
-
-Used by **11 agents** for up-to-date library docs:
-
-| Agent | Libraries |
-|-------|-----------|
-| **hermes** | FastAPI, Pydantic, SQLAlchemy |
-| **aphrodite** | React, Next.js, Tailwind |
-| **demeter** | SQLAlchemy, Alembic |
-| **hephaestus** | LangChain, LangGraph |
-| **themis** | Pydantic, FastAPI (security review context) |
-| **athena** | General (any framework during planning) |
-| **prometheus** | Docker, Docker Compose |
-| **gaia** | Scientific Python (rasterio, xarray, numpy) |
-| **nyx** | OpenTelemetry |
-| **apollo** | General (any library during discovery) |
-| **zeus** | General (any library during orchestration) |
-
-> **Note:** Exa MCP was removed in v3.15.0. Use the built-in `websearch` tool instead.
-
-### playwright (Browser Automation)
-
-Used by **3 agents**:
-
-| Agent | Use Case |
-|-------|----------|
-| **aphrodite** | Visual review pipeline — screenshots, accessibility snapshots |
-| **themis** | Visual regression checking during review |
-| **hermes** | API response verification via browser (edge cases) |
-
----
-
-## MCP Config in Agent Frontmatter
-
-Each agent template (`agents/*.agent.md`) declares its MCP bindings in YAML
-frontmatter:
-
-```yaml
----
-mcpServers:
-  - name: pantheon-resources
-    tools:
-      - read_mcp_resource
-    when: "reading agent/skills/routing info"
-  - name: pantheon-memory
-    tools:
-      - memory_recall
-      - memory_store
-      - memory_search
-    when: "persistent memory access"
-  - name: context7
-    tools:
-      - context7_resolve-library-id
-      - context7_query-docs
-    when: "resolving library documentation"
----
-```
-
-### Rules
-
-- Maximum 5 MCPs per agent
-- `tools` lists the specific MCP tools the agent can access
-- `when` describes the activation condition
-- Third-party MCPs require explicit `env` config with `${VAR}` interpolation
-
----
-
-## Security Notes
-
-| Server | Risk Level | Notes |
-|--------|-----------|-------|
-| **pantheon-resources** | Low | Read-only. Same trust boundary as repository |
-| **pantheon-code-mode** | Medium | Executes scripts. Permission: `ask` (user confirms each execution) |
-| **pantheon-memory** | Low | Read/write within agent sandbox. No system access |
-| **context7** | Low | Read-only library documentation. No auth needed |
-| ~~exa~~ | *Removed in v3.15.0* | Use `websearch` tool instead |
-| **playwright** | Medium | Runs headless Chromium. Permission: `ask` recommended |
-
-See `skill: mcp-security` for complete MCP security rules.