fix(subagents): improve reliability by requiring persistence checks and style matching

.gitattributes

@@ -1,5 +1,6 @@
 # Ensure shell scripts always have LF line endings
 *.sh text eol=lf
+hooks/session-start text eol=lf
 
 # Ensure the polyglot wrapper keeps LF (it's parsed by both cmd and bash)
 *.cmd text eol=lf

.gitignore

@@ -1,3 +1,6 @@
 .worktrees/
 .private-journal/
 .claude/
+node_modules/
+inspo
+triage/

.opencode/plugins/superpowers.js

@@ -9,6 +9,9 @@ import path from 'path';
 import fs from 'fs';
 import os from 'os';
 import { fileURLToPath } from 'url';
+import { getState } from '../../lib/git-notes-state.js';
+import { indexSkills } from '../../lib/index-skills.js';
+import { stripFrontmatter } from '../../lib/skills-core.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -61,15 +64,38 @@ export const SuperpowersPlugin = async ({ client, directory }) => {
     const fullContent = fs.readFileSync(skillPath, 'utf8');
     const { content } = extractAndStripFrontmatter(fullContent);
 
+    // Generate Skill Index for static injection
+    const allSkills = [
+      ...indexSkills(superpowersSkillsDir, 'superpowers'),
+      ...indexSkills(path.join(configDir, 'skills/amplifier'), 'amplifier'),
+      ...indexSkills(path.join(configDir, 'skills/claude-tools'), 'claude-tools')
+    ];
+    const skillIndex = allSkills.map(s => {
+      const tags = s.semantic_tags ? ` [Tags: ${s.semantic_tags.join(', ')}]` : '';
+      return `- **${s.sourceType}:${s.name}**: ${s.description}${tags}`;
+    }).join('\n');
+
     const toolMapping = `**Tool Mapping for OpenCode:**
 When skills reference tools you don't have, substitute OpenCode equivalents:
 - \`TodoWrite\` → \`update_plan\`
 - \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
 - \`Skill\` tool → OpenCode's native \`skill\` tool
 - \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
+- 💡 **Memory:** Use \`recall\` to access long-term project knowledge (decisions, patterns).
+- 📡 **UI Signals:** The user can trigger skills via the Portal's Ctrl+P palette. These appear as files in \`.opencode/signals/\`. If you see a new signal, acknowledge it and initiate the skill context.
+
+**Available Skills:**
+${skillIndex}
+
+**🚀 Model Selection Recommendations:**
+- **Planning/Architecture:** Use **Gemini 3 Pro** (\`/model google/gemini-3-pro-preview\`).
+- **Implementation/TDD:** Use **Gemini 3 Flash** (\`/model google/gemini-3-flash-preview\`).
+- **Subagents:** Orchestrator should always dispatch subagents using **Flash** to save TPM.
+
+**IMPORTANT:** The above is just an index. To use a skill, you MUST load it using the \`skill\` tool (e.g., \`use skill tool to load amplifier/zen-architect\`).
 
 **Skills location:**
-Superpowers skills are in \`${configDir}/skills/superpowers/\`
+Skills are in \`${configDir}/skills/{namespace}/\`
 Use OpenCode's native \`skill\` tool to list and load skills.`;
 
     return `<EXTREMELY_IMPORTANT>

AMPLIFIER-AGENTS.md

@@ -0,0 +1,72 @@
+# Amplifier Agent Mapping
+
+Reference for superpowers skills. Consult this to select the right Amplifier agent for each task.
+
+## Core Development Agents
+
+| Task Type | Agent | Trigger Keywords |
+|-----------|-------|-----------------|
+| Architecture/Design | `zen-architect` | plan, design, architect, structure, module spec, system design |
+| Implementation | `modular-builder` | implement, build, create, add, write code |
+| Testing | `test-coverage` | test, coverage, verify, validate, assertion |
+| Debugging | `bug-hunter` | fix, debug, error, failure, broken, regression |
+| Security Review | `security-guardian` | security, auth, secrets, OWASP, vulnerability, permission |
+| Integration | `integration-specialist` | API, MCP, external, dependency, connection, integration |
+| Performance | `performance-optimizer` | performance, slow, optimize, bottleneck, latency |
+| Cleanup | `post-task-cleanup` | cleanup, hygiene, lint, format, unused, dead code |
+| API Design | `api-contract-designer` | endpoint, contract, REST, GraphQL, schema, route |
+| Database | `database-architect` | schema, migration, query, index, table, database |
+| Specifications | `contract-spec-author` | spec, contract, interface, protocol, requirements doc |
+
+## Design Agents
+
+| Task Type | Agent | Trigger Keywords |
+|-----------|-------|-----------------|
+| UI/Component | `component-designer` | component, UI, frontend, visual, widget |
+| Aesthetic Direction | `art-director` | aesthetic, brand, visual identity, mood, style guide |
+| Animation/Motion | `animation-choreographer` | animation, transition, motion, easing, keyframe |
+| Layout | `layout-architect` | layout, grid, page structure, sidebar, navigation |
+| Responsive | `responsive-strategist` | responsive, breakpoint, mobile, tablet, viewport |
+| Design System | `design-system-architect` | design tokens, theme, design system, foundation |
+| UX Writing | `voice-strategist` | copy, microcopy, tone, error message, UX writing |
+
+## Knowledge & Analysis Agents
+
+| Task Type | Agent | Trigger Keywords |
+|-----------|-------|-----------------|
+| Research | `content-researcher` | research, investigate, compare, survey, evaluate |
+| Analysis | `analysis-engine` | analyze, assess, audit, measure, report |
+| Concept Extraction | `concept-extractor` | extract, summarize, distill, key ideas, themes |
+| Synthesis | `insight-synthesizer` | synthesize, combine, cross-reference, connect |
+| Code Archaeology | `knowledge-archaeologist` | history, evolution, legacy, why was this, original intent |
+| Pattern Discovery | `pattern-emergence` | pattern, recurring, commonality, trend, structural |
+| Visualization | `visualization-architect` | diagram, chart, graph, visualize, data viz |
+| Knowledge Graph | `graph-builder` | graph, relationship, entity, connection, network |
+
+## Meta Agents
+
+| Task Type | Agent | Trigger Keywords |
+|-----------|-------|-----------------|
+| Module Design | `module-intent-architect` | module boundary, brick, stud, interface, contract |
+| Agent Creation | `subagent-architect` | new agent, specialized agent, create agent |
+| CLI Tool Design | `amplifier-cli-architect` | CLI tool, command, scenario, amplifier tool |
+| Ambiguity Detection | `ambiguity-guardian` | ambiguous, unclear, vague, conflicting, assumption |
+
+## Review Agent Mapping
+
+| Review Type | Agent | When |
+|-------------|-------|------|
+| Spec Compliance | `test-coverage` | After every implementation task |
+| Code Quality | `zen-architect` (REVIEW mode) | After spec compliance passes |
+| Security | `security-guardian` | Security-sensitive tasks or final review |
+| Post-completion | `post-task-cleanup` | After all tasks pass, before finishing branch |
+
+## Selection Rules
+
+1. Match task description keywords against the Trigger Keywords column
+2. If multiple agents match, pick the one whose Task Type best describes the primary goal
+3. Implementation tasks default to `modular-builder` unless a more specific agent fits
+4. Review tasks always use the Review Agent Mapping above
+5. When unsure, `modular-builder` for building and `bug-hunter` for fixing
+6. Design agents are for UI/frontend work — use only when the task is primarily visual/design
+7. Knowledge agents are for research/analysis — use when gathering or synthesizing information

MEMORY-WORKFLOW.md

@@ -0,0 +1,107 @@
+# Memory Workflow
+
+Three memory systems serve different roles. Use the right one at the right time.
+
+## The Three Systems
+
+| System | Role | Storage | Scope |
+|--------|------|---------|-------|
+| **Auto-memory** (MEMORY.md) | Working memory | `~/.claude/projects/*/memory/` | Cross-session, always loaded |
+| **Git-notes** (knowledge_base) | Project memory | `refs/notes/superpowers` per repo | Per-repo, accumulated decisions/patterns |
+| **Episodic Memory** | Recall memory | Conversation archive | Cross-session, searchable transcripts |
+
+## When to READ
+
+| Trigger | System | Command |
+|---------|--------|---------|
+| Every session start | Auto-memory | Automatic (loaded into system prompt) |
+| Starting brainstorming | Episodic Memory | `episodic-memory:search-conversations` for related past work |
+| Before design decisions | Git-notes | `node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.decisions` |
+| Before implementation | Git-notes | `node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.patterns` |
+| "Did we discuss X?" | Episodic Memory | Semantic search through archive |
+| Unfamiliar domain term | Git-notes | `node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.glossary` |
+
+## When to WRITE
+
+| Trigger | System | Command |
+|---------|--------|---------|
+| Architecture decision made | Git-notes | `memorize knowledge_base.decisions --value '{"id":"ADR-NNN", ...}'` |
+| Pattern discovered | Git-notes | `memorize knowledge_base.patterns --value '{"title":"...", ...}'` |
+| Domain term clarified | Git-notes | `memorize knowledge_base.glossary --value '{"term":"definition"}'` |
+| Infrastructure change (IPs, creds) | Auto-memory | Edit MEMORY.md directly |
+| Session ends | Auto-memory | `sync-memory.sh` hook (automatic) |
+| Human-readable export needed | Git-notes | `node ${SUPERPOWERS_DIR}/commands/snapshot-memory.js` |
+
+## Decision Record Format (ADR)
+
+```json
+{
+  "id": "ADR-NNN",
+  "title": "Short descriptive title",
+  "status": "accepted|superseded|deprecated",
+  "context": "What situation prompted this decision",
+  "decision": "What we decided and why",
+  "consequences": "What follows from this decision"
+}
+```
+
+## Pattern Format
+
+```json
+{
+  "title": "Pattern name",
+  "description": "When and why to use this pattern",
+  "code": "Example code or command",
+  "language": "python|javascript|bash|etc"
+}
+```
+
+## Glossary Format
+
+Pass as object — keys are terms, values are definitions:
+
+```json
+{"TermName": "Definition of the term in project context"}
+```
+
+## What Goes Where
+
+**Auto-memory (MEMORY.md)** — information needed EVERY session regardless of task:
+- Network topology, server IPs, credentials
+- Deployment commands and paths
+- API endpoints and keys
+- IIS sites, database connection strings
+
+**Git-notes (knowledge_base)** — project-specific knowledge that accumulates:
+- `decisions`: Why we chose approach X over Y (ADRs)
+- `patterns`: Established code patterns with examples
+- `glossary`: Domain terms and their meaning in this project
+
+**Episodic Memory** — never written to manually:
+- Passive archival of all conversations
+- Used for "what did we discuss about X?" queries
+- Provides evidence for decisions when context is lost
+
+## Command Reference
+
+All commands run from any repo directory. `${SUPERPOWERS_DIR}` = path to superpowers installation.
+
+```bash
+# Recall specific section
+node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.decisions
+node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.patterns
+node ${SUPERPOWERS_DIR}/commands/recall.js knowledge_base.glossary
+
+# Store a decision
+node ${SUPERPOWERS_DIR}/commands/memorize.js knowledge_base.decisions --value '{"id":"ADR-001","title":"...","status":"accepted","context":"...","decision":"...","consequences":"..."}'
+
+# Store a pattern
+node ${SUPERPOWERS_DIR}/commands/memorize.js knowledge_base.patterns --value '{"title":"...","description":"...","code":"...","language":"bash"}'
+
+# Store glossary terms
+node ${SUPERPOWERS_DIR}/commands/memorize.js knowledge_base.glossary --value '{"Term":"Definition"}'
+
+# Export human-readable snapshot
+node ${SUPERPOWERS_DIR}/commands/snapshot-memory.js
+# Writes to docs/memory/SNAPSHOT.md in current repo
+```

MODEL-PROVIDERS.md

@@ -0,0 +1,68 @@
+# Model Provider Mapping
+
+Superpowers skills are provider-agnostic. This document maps model tiers to specific providers so skills work across Claude Code, OpenCode/Gemini, and future environments.
+
+## Tier Mapping
+
+| Tier | Intent | Claude Code (`model` param) | OpenCode/Gemini (`/model` cmd) |
+|------|--------|-----------------------------|-------------------------------|
+| **Fast** | Mechanical tasks, clear spec, 1-2 files | `haiku` | `google/gemini-3-flash-preview` |
+| **Balanced** | Multi-file, debugging, reasoning | `sonnet` | `google/gemini-3-pro-preview` |
+| **Deep** | Architecture, security, broad judgment | `opus` | `google/gemini-3-pro-preview` |
+
+## How Each Environment Consumes This
+
+### Claude Code
+
+The Task tool's `model` parameter accepts: `haiku`, `sonnet`, `opus`.
+
+```
+Task(subagent_type="bug-hunter", model="sonnet", description="...", prompt="...")
+```
+
+Skills reference Claude model names in dispatch examples and Model Selection tables. The `recommended_model` YAML field is not consumed by Claude Code.
+
+### OpenCode / Gemini
+
+OpenCode uses `/model` commands and `@mention` for subagents:
+
+```
+/model google/gemini-3-flash-preview
+```
+
+The `recommended_model` YAML field in skill headers (`flash`, `pro`) maps to Gemini models. The OpenCode plugin injects model recommendations via system prompt transform.
+
+### YAML `recommended_model` Field
+
+| YAML Value | Provider | Tier |
+|------------|----------|------|
+| `flash` | Gemini | Fast |
+| `pro` | Gemini | Balanced |
+
+This field is consumed by OpenCode only. Claude Code ignores it and uses its own Model Selection tables within each skill.
+
+## Agent-to-Tier Mapping
+
+| Agent | Tier | Claude | Gemini | Rationale |
+|-------|------|--------|--------|-----------|
+| `modular-builder` (simple) | Fast | `haiku` | Flash | Mechanical with clear spec |
+| `modular-builder` (multi-file) | Balanced | `sonnet` | Pro | Integration reasoning needed |
+| `bug-hunter` | Balanced | `sonnet` | Pro | Root cause analysis |
+| `database-architect` | Balanced | `sonnet` | Pro | Schema design judgment |
+| `test-coverage` (spec review) | Fast | `haiku` | Flash | Checklist comparison |
+| `zen-architect` (quality review) | Balanced | `sonnet` | Pro | Architecture judgment |
+| `security-guardian` | Deep | `opus` | Pro | Deepest analysis needed |
+| `post-task-cleanup` | Fast | `haiku` | Flash | Mechanical cleanup |
+| `integration-specialist` | Balanced | `sonnet` | Pro | External system expertise |
+| `performance-optimizer` | Balanced | `sonnet` | Pro | Measure-first approach |
+| `component-designer` | Balanced | `sonnet` | Pro | Visual consistency judgment |
+| `api-contract-designer` | Balanced | `sonnet` | Pro | Contract validation |
+
+## Adding a New Provider
+
+To add support for a new provider (e.g., OpenAI):
+
+1. Add a column to the Tier Mapping table above
+2. Map each tier to the provider's model names
+3. Create the environment-specific dispatch mechanism (plugin, hook, etc.)
+4. Skills remain unchanged — they reference tiers through the existing Model Selection tables

README.md

@@ -2,6 +2,13 @@
 
 Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them.
 
+## Documentation
+
+- **[COMPREHENSIVE-SYSTEM-DOCS.md](docs/COMPREHENSIVE-SYSTEM-DOCS.md)** - Comprehensive overview of the Superpowers framework, Amplifier integration, and Git-based memory approach.
+- **[AMPLIFIER-AGENTS.md](AMPLIFIER-AGENTS.md)** - Full reference for Amplifier specialized agents and their mapping to task types.
+- **[docs/README.codex.md](docs/README.codex.md)** - Documentation for Codex users.
+- **[docs/README.opencode.md](docs/README.opencode.md)** - Documentation for OpenCode users.
+
 ## How it works
 
 It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. 

RELEASE-NOTES.md

@@ -1,5 +1,40 @@
 # Superpowers Release Notes
 
+## Unreleased (Fork: psklarkins/superpowers)
+
+### Amplifier Integration
+
+**Brainstorming skill enhanced with Amplifier agent awareness**
+
+- Context scout dispatches to gather project state, decisions, and available agents
+- Agent Allocation section required in all designs
+- Workflow routing considers Amplifier agent capabilities
+
+**Writing-plans skill uses Amplifier agents**
+
+- Each task gets Agent: field for Amplifier agent dispatch
+- Auto-assignment by task type (implementation, test, debug, security, etc.)
+- Review tasks use dedicated agents (test-coverage, zen-architect, security-guardian)
+- Context-efficient plan generation delegates to subagent for 5+ task plans
+
+**Skills customized for integrated workflow**
+
+- Subagent-driven development dispatches Amplifier agents as specialists
+- Dispatching-parallel-agents selects Amplifier specialists per domain
+- Memory workflow integrated with git-notes state manager
+
+### Previous Fork Changes
+
+- Specs/plans directory restructured (`docs/superpowers/specs/` and `docs/superpowers/plans/`)
+- Brainstorming → writing-plans transition enforced
+- Subagent-driven development mandatory on capable harnesses
+- OpenCode native skills support
+- Visual companion for brainstorming (opt-in, browser-based)
+- Instruction priority hierarchy in using-superpowers
+- Windows hook fixes (run-hook.cmd wrapper, escape_for_json performance)
+- Output discipline for implementer and reviewer prompts
+- Context gathering delegated to scout subagents
+
 ## v4.3.0 (2026-02-12)
 
 This fix should dramatically improve superpowers skills compliance and should reduce the chances of Claude entering its native plan mode unintentionally.