feat: add agent template rendering workflow

.codex/INSTALL.md

@@ -1,3 +1,4 @@
+<!-- GENERATED: do not edit directly. Source: templates/.codex/INSTALL.md -->
 # Installing Superpowers for Codex
 
 Quick setup to enable superpowers skills in Codex.
@@ -32,4 +33,4 @@ Test the installation:
 ~/.codex/superpowers/.codex/superpowers-codex bootstrap
 ```
 
-You should see skill listings and bootstrap instructions. The system is now ready for use.
+You should see skill listings and bootstrap instructions. The system is now ready for use.

.opencode/INSTALL.md

@@ -1,8 +1,9 @@
+<!-- GENERATED: do not edit directly. Source: templates/.opencode/INSTALL.md -->
 # Installing Superpowers for OpenCode
 
 ## Prerequisites
 
-- [OpenCode.ai](https://opencode.ai) installed
+- [OpenCode](https://opencode.ai) installed
 - Git installed
 
 ## Installation Steps

README.md

@@ -1,3 +1,4 @@
+<!-- GENERATED: do not edit directly. Source: templates/README.md -->
 # Superpowers
 
 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.
@@ -10,7 +11,7 @@ Once it's teased a spec out of the conversation, it shows it to you in chunks sh
 
 After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. 
 
-Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
+Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for your agent to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.
 
 There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.
 
@@ -141,6 +142,22 @@ Skills live directly in this repository. To contribute:
 
 See `skills/writing-skills/SKILL.md` for the complete guide.
 
+## Templates & Rendering
+
+Source files live in `templates/`. Regenerate agent-specific outputs with:
+
+```bash
+node scripts/render-agent.js --agent codex --write
+node scripts/render-agent.js --agent claude --write
+node scripts/render-agent.js --agent opencode --write
+```
+
+Validate all templates:
+
+```bash
+bash tests/render-templates.sh
+```
+
 ## Updating
 
 Skills update automatically when you update the plugin:

agents/claude.json

@@ -0,0 +1,13 @@
+{
+  "AGENT_ID": "claude",
+  "AGENT_NAME": "Claude Code",
+  "AGENTS_MD": "CLAUDE.md",
+  "CLI_NAME": "claude",
+  "CLI_CMD": "claude",
+  "AGENT_HOME": "~/.claude",
+  "AGENT_HOME_ENV": "$HOME/.claude",
+  "SKILLS_DIR": "~/.claude/skills",
+  "CONFIG_DIR": "~/.claude",
+  "PLUGIN_DIR": "~/.claude/plugins",
+  "SUPERPOWERS_DIR": "~/.claude/superpowers"
+}

agents/codex.json

@@ -0,0 +1,13 @@
+{
+  "AGENT_ID": "codex",
+  "AGENT_NAME": "Codex",
+  "AGENTS_MD": "AGENTS.md",
+  "CLI_NAME": "codex",
+  "CLI_CMD": "codex",
+  "AGENT_HOME": "~/.codex",
+  "AGENT_HOME_ENV": "$HOME/.codex",
+  "SKILLS_DIR": "~/.codex/skills",
+  "CONFIG_DIR": "~/.codex",
+  "PLUGIN_DIR": "",
+  "SUPERPOWERS_DIR": "~/.codex/superpowers"
+}

agents/opencode.json

@@ -0,0 +1,13 @@
+{
+  "AGENT_ID": "opencode",
+  "AGENT_NAME": "OpenCode",
+  "AGENTS_MD": "AGENTS.md",
+  "CLI_NAME": "opencode",
+  "CLI_CMD": "opencode",
+  "AGENT_HOME": "~/.config/opencode",
+  "AGENT_HOME_ENV": "$HOME/.config/opencode",
+  "SKILLS_DIR": "~/.config/opencode/skills",
+  "CONFIG_DIR": "~/.config/opencode",
+  "PLUGIN_DIR": "~/.config/opencode/plugins",
+  "SUPERPOWERS_DIR": "~/.config/opencode/superpowers"
+}

docs/README.codex.md

@@ -1,6 +1,7 @@
+<!-- GENERATED: do not edit directly. Source: templates/docs/README.codex.md -->
 # Superpowers for Codex
 
-Complete guide for using Superpowers with OpenAI Codex.
+Complete guide for using Superpowers with Codex.
 
 ## Quick Install
 
@@ -14,7 +15,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 
 ### Prerequisites
 
-- OpenAI Codex access
+- Access to Codex
 - Shell access to install files
 
 ### Installation Steps
@@ -111,6 +112,20 @@ Skills written for Claude Code are adapted for Codex with these mappings:
 - `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill`
 - File operations → Native Codex tools
 
+## Templates & Rendering
+
+Source files live in `templates/`. Regenerate agent-specific outputs with:
+
+```bash
+node scripts/render-agent.js --agent codex --write
+```
+
+Validate all templates:
+
+```bash
+bash tests/render-templates.sh
+```
+
 ## Updating
 
 ```bash

docs/README.opencode.md

@@ -1,13 +1,14 @@
+<!-- GENERATED: do not edit directly. Source: templates/docs/README.opencode.md -->
 # Superpowers for OpenCode
 
-Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
+Complete guide for using Superpowers with [OpenCode](https://opencode.ai).
 
 ## Quick Install
 
 Tell OpenCode:
 
 ```
-Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart opencode.
+Clone https://github.com/obra/superpowers to ~/.config/opencode/superpowers, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/superpowers/.opencode/plugins/superpowers.js to ~/.config/opencode/plugins/superpowers.js, then symlink ~/.config/opencode/superpowers/skills to ~/.config/opencode/skills/superpowers, then restart OpenCode.
 ```
 
 ## Manual Installation
@@ -270,6 +271,20 @@ Skills written for Claude Code are automatically adapted for OpenCode. The boots
 
 Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter.
 
+## Templates & Rendering
+
+Source files live in `templates/`. Regenerate agent-specific outputs with:
+
+```bash
+node scripts/render-agent.js --agent opencode --write
+```
+
+Validate all templates:
+
+```bash
+bash tests/render-templates.sh
+```
+
 ## Updating
 
 ```bash

docs/plans/2026-01-24-agent-templates-design.md

@@ -0,0 +1,99 @@
+# Agent Template Rendering Design
+
+**Date:** 2026-01-24  
+**Author:** Codex & User  
+**Status:** Design Complete, Awaiting Implementation
+
+## Overview
+
+Unify all agent-specific documentation, installation guides, tests, and examples under a template + render workflow so references like `CLAUDE.md` vs `AGENTS.md` and “for claude” vs “for codex” are never hand-edited. Templates become the single source of truth, and a renderer generates correct, agent-specific outputs for Claude Code, Codex, and OpenCode.
+
+## Goals
+
+- Eliminate hardcoded agent references from shared files.
+- Keep a single canonical source for docs/tests/examples.
+- Generate agent-specific outputs deterministically.
+- Preserve public endpoints/paths (e.g., `.codex/INSTALL.md`).
+- Make adding a new agent a configuration change, not a rewrite.
+
+## Non-Goals
+
+- Changing skill content or workflow semantics.
+- Replacing the existing plugin/CLI implementations.
+- Introducing a full localization/i18n system.
+
+## Architecture
+
+### Core Components
+
+1. **Templates** (`templates/`)
+   - Mirrors real repo paths (e.g., `templates/docs/README.codex.md`).
+   - Uses placeholders like `{{AGENT_NAME}}`, `{{AGENTS_MD}}`, `{{SKILLS_DIR}}`, `{{CLI_CMD}}`.
+
+2. **Agent Configs** (`agents/*.json`)
+   - One JSON per agent (`claude`, `codex`, `opencode`).
+   - Defines names, file paths, CLI commands, and OS-specific values.
+
+3. **Targets Map** (`templates/targets.json`)
+   - Maps template paths → output paths.
+   - Drives full-regeneration for a given agent.
+
+4. **Renderer Script** (`scripts/render-agent.js`)
+   - Resolves placeholders + partials.
+   - Validates missing placeholders.
+   - Writes to a destination directory (`--out`) or repo paths (`--write`).
+
+### Partial Includes
+
+Templates support `{{> partial-name}}`. The renderer resolves in this order:
+
+1. `templates/_partials/partial-name.<agent>.<ext>`
+2. `templates/_partials/partial-name.<ext>`
+
+This allows small agent-specific overrides without duplicating full files.
+
+## Data Flow
+
+1. Choose agent (`--agent codex`).
+2. Load `agents/codex.json`.
+3. Expand templates using `targets.json`.
+4. Resolve partials.
+5. Validate that no `{{...}}` remains.
+6. Write outputs to `--out` or in-place with `--write`.
+
+## Error Handling
+
+- **Unknown agent:** fail with a list of valid agents.
+- **Missing placeholder:** fail with file + placeholder name.
+- **Missing partial:** fail with template + missing partial path.
+- **Unresolved placeholders after render:** fail with file list.
+
+## Testing & Validation
+
+- **Render check:** ensure all agents render without unresolved placeholders.
+- **Agent-specific assertions:** confirm key strings per agent (e.g., `AGENTS.md` vs `CLAUDE.md`).
+- **Template lint:** prevent hardcoded agent names in shared templates (allow in agent-specific partials).
+
+These checks can run in CI or a local script (e.g., `npm run render:check`).
+
+## Migration Plan
+
+1. Create `templates/`, `agents/`, and `scripts/render-agent.js`.
+2. Copy current files into templates and replace agent-specific strings with placeholders.
+3. Render outputs for each agent to regenerate:
+   - `README.md`
+   - `docs/README.*.md`
+   - `.codex/INSTALL.md`
+   - `.opencode/INSTALL.md`
+   - tests/examples/scripts referencing a specific agent
+4. Add a “generated file” header where safe (`<!-- GENERATED -->` or `# GENERATED`).
+5. Document the render workflow in the main README.
+
+Public install URLs remain unchanged, but their content is now generated from templates.
+
+## Open Questions
+
+- Should generated outputs remain committed for all paths, or only for public endpoints?
+- What is the minimal banner format for generated files in non-markdown formats?
+- Should the renderer support OS-specific variants beyond Windows snippets?
+