5-phase-workflow 1.9.1 → 1.9.2

package/README.md

@@ -141,6 +141,7 @@ Claude Code exposes the workflow under the `/5:` namespace. Codex exposes the sa
 | `/5:quick-implement` or `$5-quick-implement` | Fast | Streamlined workflow for small tasks |
 | `/5:eject` or `$5-eject` | Utility | Permanently remove update infrastructure |
 | `/5:unlock` or `$5-unlock` | Utility | Remove planning guard lock |
+| `/5:synchronize-agents` or `$5-synchronize-agents` | Utility | Sync user content between Claude Code and Codex runtimes |
 
 ## Configuration
 
@@ -278,7 +279,8 @@ After installation, your `.claude/` directory will contain:
 │   ├── quick-implement.md
 │   ├── configure.md
 │   ├── eject.md
-│   └── unlock.md
+│   ├── unlock.md
+│   └── synchronize-agents.md
 ├── skills/                   # Atomic operations
 │   ├── build-project/
 │   ├── run-tests/
@@ -398,6 +400,26 @@ This permanently removes the update infrastructure:
 
 All other workflow files remain untouched. **This is irreversible.** To restore update functionality, reinstall with `npx 5-phase-workflow`.
 
+### Synchronizing Runtimes
+
+If you have both Claude Code and Codex installed, user-generated content (project-specific skills, custom commands, rules) only exists in the runtime where it was created. To sync this content bidirectionally:
+
+```bash
+# Claude Code
+/5:synchronize-agents
+
+# Codex
+$5-synchronize-agents
+```
+
+This will:
+- Sync project-specific skills (e.g., `create-controller`, `run-tests`) between `.claude/skills/` and `.codex/skills/` with appropriate format conversion
+- Convert custom Claude commands to Codex skills
+- Append `.claude/rules/` content to `.codex/instructions.md`
+- Sync Codex-only skills back to Claude
+
+Workflow-managed files and shared data (`.5/`) are not affected — those are handled by the installer.
+
 ## Development
 
 ### Running Tests

package/bin/install.js

@@ -847,6 +847,7 @@ function showCommandsHelp(isGlobal) {
     log.info('  $5-reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  $5-eject                     - Eject from update mechanism');
     log.info('  $5-unlock                    - Remove planning guard lock');
+    log.info('  $5-synchronize-agents        - Sync user content between runtimes');
   } else {
     log.info('Available commands:');
     log.info('  /5:plan-feature              - Start feature planning (Phase 1)');
@@ -859,6 +860,7 @@ function showCommandsHelp(isGlobal) {
     log.info('  /5:reconfigure               - Refresh docs/skills (no Q&A)');
     log.info('  /5:eject                     - Eject from update mechanism');
     log.info('  /5:unlock                    - Remove planning guard lock');
+    log.info('  /5:synchronize-agents        - Sync user content between runtimes');
   }
   log.info('');
   log.info(`Config file: ${path.join(getDataPath(isGlobal), 'config.json')}`);

package/bin/sync-agents.js

@@ -0,0 +1,639 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// ANSI colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m'
+};
+
+const log = {
+  info: (msg) => console.log(`${colors.blue}i${colors.reset} ${msg}`),
+  success: (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`),
+  warn: (msg) => console.log(`${colors.yellow}⚠${colors.reset} ${msg}`),
+  error: (msg) => console.log(`${colors.red}✗${colors.reset} ${msg}`),
+  header: (msg) => console.log(`\n${colors.bright}${msg}${colors.reset}\n`),
+  dim: (msg) => console.log(`  ${colors.dim}${msg}${colors.reset}`)
+};
+
+// ── Workflow-managed file lists (must match install.js) ────────────────────
+
+const WORKFLOW_MANAGED_SKILLS = new Set([
+  'configure-docs-index',
+  'configure-project',
+  'configure-skills',
+  'generate-readme'
+]);
+
+const WORKFLOW_MANAGED_AGENTS = new Set([
+  'component-executor.md'
+]);
+
+const RULES_SYNC_START = '<!-- 5-sync:rules-start -->';
+const RULES_SYNC_END = '<!-- 5-sync:rules-end -->';
+const AGENTS_SYNC_START = '<!-- 5-sync:agents-start -->';
+const AGENTS_SYNC_END = '<!-- 5-sync:agents-end -->';
+
+// ── Conversion functions (mirrors install.js logic) ────────────────────────
+
+function extractFrontmatterAndBody(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { frontmatter: null, body: content };
+  return { frontmatter: match[1], body: match[2] };
+}
+
+function extractFrontmatterField(frontmatter, field) {
+  if (!frontmatter) return null;
+  const match = frontmatter.match(new RegExp(`^${field}:\\s*(.+)$`, 'm'));
+  return match ? match[1].trim() : null;
+}
+
+function claudeToCodexContent(content) {
+  return content
+    .replace(/\/5:([a-z0-9-]+)/g, (_, name) => `$5-${name}`)
+    .replace(/\.claude\//g, '.codex/');
+}
+
+function codexToClaudeContent(content) {
+  return content
+    .replace(/\$5-([a-z0-9-]+)/g, (_, name) => `/5:${name}`)
+    .replace(/\.codex\//g, '.claude/')
+    .replace(/<codex_skill_adapter>[\s\S]*?<\/codex_skill_adapter>\n*/g, '');
+}
+
+function getCodexSkillAdapterHeader(skillName) {
+  const invocation = `$${skillName}`;
+  return `<codex_skill_adapter>
+## Skill Invocation
+- This skill is invoked by mentioning \`${invocation}\`.
+- Treat all user text after \`${invocation}\` as the skill argument.
+
+## Tool Mapping (Claude Code → Codex)
+This skill was authored for Claude Code. Map these tool references:
+
+| Claude Code | Codex Equivalent |
+|-------------|------------------|
+| \`AskUserQuestion\` | Ask the user directly in conversation |
+| \`Task(subagent_type="Explore")\` | Research the codebase yourself using available tools |
+| \`Task(prompt="...")\` | \`spawn_agent(message="...")\` |
+| \`Read\` | \`read_file\` |
+| \`Write\` | \`write_file\` |
+| \`Edit\` | \`patch\` |
+| \`Bash\` | \`shell\` |
+| \`Glob\` | \`glob\` / \`list_directory\` |
+| \`Grep\` | \`grep\` / \`search\` |
+| \`TaskCreate/TaskUpdate\` | Track progress internally |
+| \`EnterPlanMode\` | Not available — use structured output instead |
+</codex_skill_adapter>`;
+}
+
+function convertClaudeCommandToCodexSkill(content, skillName) {
+  const converted = claudeToCodexContent(content);
+  const { frontmatter, body } = extractFrontmatterAndBody(converted);
+
+  let description = `Custom command: ${skillName}`;
+  if (frontmatter) {
+    const maybeDesc = extractFrontmatterField(frontmatter, 'description');
+    if (maybeDesc) description = maybeDesc;
+  }
+
+  const shortDesc = description.length > 180 ? `${description.slice(0, 177)}...` : description;
+  const adapter = getCodexSkillAdapterHeader(skillName);
+
+  return `---
+name: ${skillName}
+description: ${description}
+metadata:
+  short-description: ${shortDesc}
+---
+
+${adapter}
+
+${body.trimStart()}`;
+}
+
+function convertClaudeSkillToCodex(content) {
+  return claudeToCodexContent(content);
+}
+
+function convertCodexSkillToClaude(content) {
+  return codexToClaudeContent(content);
+}
+
+// ── File helpers ────────────────────────────────────────────────────────────
+
+function copyDirContents(src, dest, transformMd) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirContents(srcPath, destPath, transformMd);
+    } else if (transformMd && entry.name.endsWith('.md')) {
+      const content = fs.readFileSync(srcPath, 'utf8');
+      fs.writeFileSync(destPath, transformMd(content));
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function dirContentsEqual(dirA, dirB, transformFn) {
+  if (!fs.existsSync(dirA) || !fs.existsSync(dirB)) return false;
+
+  const filesA = fs.readdirSync(dirA).sort();
+  const filesB = fs.readdirSync(dirB).sort();
+  if (filesA.length !== filesB.length) return false;
+
+  for (const file of filesA) {
+    if (!filesB.includes(file)) return false;
+    const pathA = path.join(dirA, file);
+    const pathB = path.join(dirB, file);
+    const statA = fs.statSync(pathA);
+    const statB = fs.statSync(pathB);
+    if (statA.isDirectory() !== statB.isDirectory()) return false;
+    if (statA.isDirectory()) {
+      if (!dirContentsEqual(pathA, pathB, transformFn)) return false;
+    } else {
+      let contentA = fs.readFileSync(pathA, 'utf8');
+      const contentB = fs.readFileSync(pathB, 'utf8');
+      if (file.endsWith('.md') && transformFn) {
+        contentA = transformFn(contentA);
+      }
+      if (contentA !== contentB) return false;
+    }
+  }
+  return true;
+}
+
+// ── Inventory ──────────────────────────────────────────────────────────────
+
+function findProjectRoot() {
+  // Walk up from cwd to find .5/ or .claude/ or .codex/
+  let dir = process.cwd();
+  while (dir !== path.dirname(dir)) {
+    if (fs.existsSync(path.join(dir, '.5')) ||
+        fs.existsSync(path.join(dir, '.claude')) ||
+        fs.existsSync(path.join(dir, '.codex'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+function isClaudeInstalled(root) {
+  return fs.existsSync(path.join(root, '.claude', 'commands', '5', 'plan-feature.md'));
+}
+
+function isCodexInstalled(root) {
+  return fs.existsSync(path.join(root, '.codex', 'skills', '5-plan-feature', 'SKILL.md'));
+}
+
+function getClaudeUserSkills(root) {
+  const skillsDir = path.join(root, '.claude', 'skills');
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(name => !WORKFLOW_MANAGED_SKILLS.has(name));
+}
+
+function getCodexUserSkills(root) {
+  const skillsDir = path.join(root, '.codex', 'skills');
+  if (!fs.existsSync(skillsDir)) return [];
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(name => !name.startsWith('5-') && !WORKFLOW_MANAGED_SKILLS.has(name));
+}
+
+function getClaudeCustomCommands(root) {
+  const commandsDir = path.join(root, '.claude', 'commands');
+  if (!fs.existsSync(commandsDir)) return [];
+  const namespaces = fs.readdirSync(commandsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name !== '5')
+    .map(d => d.name);
+
+  const commands = [];
+  for (const ns of namespaces) {
+    const nsDir = path.join(commandsDir, ns);
+    const files = fs.readdirSync(nsDir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+      commands.push({ namespace: ns, name: file.replace('.md', ''), file });
+    }
+  }
+  return commands;
+}
+
+function getClaudeCustomAgents(root) {
+  const agentsDir = path.join(root, '.claude', 'agents');
+  if (!fs.existsSync(agentsDir)) return [];
+  return fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md') && !WORKFLOW_MANAGED_AGENTS.has(f));
+}
+
+function getClaudeRules(root) {
+  const rulesDir = path.join(root, '.claude', 'rules');
+  if (!fs.existsSync(rulesDir)) return [];
+  return fs.readdirSync(rulesDir).filter(f => f.endsWith('.md'));
+}
+
+// ── Sync action classification ─────────────────────────────────────────────
+
+function classifySkillActions(root) {
+  const claudeSkills = getClaudeUserSkills(root);
+  const codexSkills = getCodexUserSkills(root);
+  const claudeSet = new Set(claudeSkills);
+  const codexSet = new Set(codexSkills);
+
+  const actions = [];
+
+  // Claude → Codex
+  for (const skill of claudeSkills) {
+    const claudeDir = path.join(root, '.claude', 'skills', skill);
+    const codexDir = path.join(root, '.codex', 'skills', skill);
+    if (!codexSet.has(skill)) {
+      actions.push({ type: 'new', direction: 'claude-to-codex', category: 'skill', name: skill });
+    } else if (!dirContentsEqual(claudeDir, codexDir, convertClaudeSkillToCodex)) {
+      actions.push({ type: 'updated', direction: 'claude-to-codex', category: 'skill', name: skill });
+    } else {
+      actions.push({ type: 'in-sync', direction: 'both', category: 'skill', name: skill });
+    }
+  }
+
+  // Codex → Claude
+  for (const skill of codexSkills) {
+    if (claudeSet.has(skill)) continue; // Already handled above
+    const claudeDir = path.join(root, '.claude', 'skills', skill);
+    if (!fs.existsSync(claudeDir)) {
+      actions.push({ type: 'new', direction: 'codex-to-claude', category: 'skill', name: skill });
+    }
+  }
+
+  return actions;
+}
+
+function classifyCommandActions(root) {
+  const commands = getClaudeCustomCommands(root);
+  const actions = [];
+
+  for (const cmd of commands) {
+    const skillName = `${cmd.namespace}-${cmd.name}`;
+    const codexSkillDir = path.join(root, '.codex', 'skills', skillName);
+    if (!fs.existsSync(codexSkillDir)) {
+      actions.push({ type: 'new', direction: 'claude-to-codex', category: 'command', name: `${cmd.namespace}/${cmd.name}`, skillName });
+    } else {
+      // Check if content changed
+      const claudeContent = fs.readFileSync(path.join(root, '.claude', 'commands', cmd.namespace, cmd.file), 'utf8');
+      const converted = convertClaudeCommandToCodexSkill(claudeContent, skillName);
+      const existing = fs.readFileSync(path.join(codexSkillDir, 'SKILL.md'), 'utf8');
+      if (converted !== existing) {
+        actions.push({ type: 'updated', direction: 'claude-to-codex', category: 'command', name: `${cmd.namespace}/${cmd.name}`, skillName });
+      } else {
+        actions.push({ type: 'in-sync', direction: 'both', category: 'command', name: `${cmd.namespace}/${cmd.name}` });
+      }
+    }
+  }
+
+  return actions;
+}
+
+function classifyRulesActions(root) {
+  const rules = getClaudeRules(root);
+  if (rules.length === 0) return [];
+
+  const instructionsPath = path.join(root, '.codex', 'instructions.md');
+  if (!fs.existsSync(instructionsPath)) {
+    return [{ type: 'new', direction: 'claude-to-codex', category: 'rules', name: `${rules.length} rule file(s)` }];
+  }
+
+  const instructions = fs.readFileSync(instructionsPath, 'utf8');
+  const newSection = buildRulesSection(root, rules);
+
+  // Extract existing section
+  const startIdx = instructions.indexOf(RULES_SYNC_START);
+  const endIdx = instructions.indexOf(RULES_SYNC_END);
+  if (startIdx === -1 || endIdx === -1) {
+    return [{ type: 'new', direction: 'claude-to-codex', category: 'rules', name: `${rules.length} rule file(s)` }];
+  }
+
+  const existing = instructions.substring(startIdx, endIdx + RULES_SYNC_END.length);
+  if (existing === newSection) {
+    return [{ type: 'in-sync', direction: 'both', category: 'rules', name: `${rules.length} rule file(s)` }];
+  }
+  return [{ type: 'updated', direction: 'claude-to-codex', category: 'rules', name: `${rules.length} rule file(s)` }];
+}
+
+function classifyAgentActions(root) {
+  const agents = getClaudeCustomAgents(root);
+  if (agents.length === 0) return [];
+
+  const instructionsPath = path.join(root, '.codex', 'instructions.md');
+  if (!fs.existsSync(instructionsPath)) {
+    return [{ type: 'new', direction: 'claude-to-codex', category: 'agents', name: `${agents.length} agent(s)` }];
+  }
+
+  const instructions = fs.readFileSync(instructionsPath, 'utf8');
+  const newSection = buildAgentsSection(root, agents);
+
+  const startIdx = instructions.indexOf(AGENTS_SYNC_START);
+  const endIdx = instructions.indexOf(AGENTS_SYNC_END);
+  if (startIdx === -1 || endIdx === -1) {
+    return [{ type: 'new', direction: 'claude-to-codex', category: 'agents', name: `${agents.length} agent(s)` }];
+  }
+
+  const existing = instructions.substring(startIdx, endIdx + AGENTS_SYNC_END.length);
+  if (existing === newSection) {
+    return [{ type: 'in-sync', direction: 'both', category: 'agents', name: `${agents.length} agent(s)` }];
+  }
+  return [{ type: 'updated', direction: 'claude-to-codex', category: 'agents', name: `${agents.length} agent(s)` }];
+}
+
+// ── Build sync content ─────────────────────────────────────────────────────
+
+function buildRulesSection(root, ruleFiles) {
+  const rulesDir = path.join(root, '.claude', 'rules');
+  let section = `${RULES_SYNC_START}\n## Project Rules\n\n`;
+  section += '> Synced from .claude/rules/ — do not edit this section manually.\n';
+  section += '> Re-run /5:synchronize-agents (or $5-synchronize-agents) to update.\n\n';
+
+  for (const file of ruleFiles) {
+    const content = fs.readFileSync(path.join(rulesDir, file), 'utf8');
+    const { body } = extractFrontmatterAndBody(content);
+    const name = file.replace('.md', '');
+    section += `### ${name}\n\n${body.trim()}\n\n`;
+  }
+
+  section += RULES_SYNC_END;
+  return section;
+}
+
+function buildAgentsSection(root, agentFiles) {
+  const agentsDir = path.join(root, '.claude', 'agents');
+  let section = `${AGENTS_SYNC_START}\n## Custom Agent References\n\n`;
+  section += '> Synced from .claude/agents/ — do not edit this section manually.\n';
+  section += '> In Codex, use `spawn_agent()` with equivalent instructions.\n\n';
+
+  for (const file of agentFiles) {
+    const content = fs.readFileSync(path.join(agentsDir, file), 'utf8');
+    const converted = claudeToCodexContent(content);
+    const name = file.replace('.md', '');
+    section += `### ${name}\n\n${converted.trim()}\n\n`;
+  }
+
+  section += AGENTS_SYNC_END;
+  return section;
+}
+
+function updateInstructionsSection(instructionsContent, startMarker, endMarker, newSection) {
+  const startIdx = instructionsContent.indexOf(startMarker);
+  const endIdx = instructionsContent.indexOf(endMarker);
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    // Replace existing section
+    return instructionsContent.substring(0, startIdx) +
+      newSection +
+      instructionsContent.substring(endIdx + endMarker.length);
+  }
+  // Append
+  return instructionsContent.trimEnd() + '\n\n' + newSection + '\n';
+}
+
+// ── Execute sync ───────────────────────────────────────────────────────────
+
+function executeSync(root, actions) {
+  const counts = { 'claude-to-codex': { new: 0, updated: 0 }, 'codex-to-claude': { new: 0, updated: 0 }, synced: 0 };
+
+  for (const action of actions) {
+    if (action.type === 'in-sync') {
+      counts.synced++;
+      continue;
+    }
+
+    if (action.category === 'skill') {
+      if (action.direction === 'claude-to-codex') {
+        syncSkillClaudeToCodex(root, action.name);
+      } else {
+        syncSkillCodexToClaude(root, action.name);
+      }
+      counts[action.direction][action.type]++;
+    } else if (action.category === 'command') {
+      syncCommandClaudeToCodex(root, action);
+      counts['claude-to-codex'][action.type]++;
+    }
+    // rules and agents are handled separately in batch
+  }
+
+  // Sync rules to instructions.md
+  const ruleActions = actions.filter(a => a.category === 'rules' && a.type !== 'in-sync');
+  if (ruleActions.length > 0) {
+    syncRulesToInstructions(root);
+    for (const a of ruleActions) counts['claude-to-codex'][a.type]++;
+  }
+
+  // Sync agents to instructions.md
+  const agentActions = actions.filter(a => a.category === 'agents' && a.type !== 'in-sync');
+  if (agentActions.length > 0) {
+    syncAgentsToInstructions(root);
+    for (const a of agentActions) counts['claude-to-codex'][a.type]++;
+  }
+
+  return counts;
+}
+
+function syncSkillClaudeToCodex(root, skillName) {
+  const src = path.join(root, '.claude', 'skills', skillName);
+  const dest = path.join(root, '.codex', 'skills', skillName);
+  copyDirContents(src, dest, convertClaudeSkillToCodex);
+  log.dim(`skill: ${skillName} → .codex/skills/${skillName}/`);
+}
+
+function syncSkillCodexToClaude(root, skillName) {
+  const src = path.join(root, '.codex', 'skills', skillName);
+  const dest = path.join(root, '.claude', 'skills', skillName);
+  copyDirContents(src, dest, convertCodexSkillToClaude);
+  log.dim(`skill: ${skillName} → .claude/skills/${skillName}/`);
+}
+
+function syncCommandClaudeToCodex(root, action) {
+  const [ns, name] = action.name.split('/');
+  const srcFile = path.join(root, '.claude', 'commands', ns, `${name}.md`);
+  const content = fs.readFileSync(srcFile, 'utf8');
+  const converted = convertClaudeCommandToCodexSkill(content, action.skillName);
+
+  const destDir = path.join(root, '.codex', 'skills', action.skillName);
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+  fs.writeFileSync(path.join(destDir, 'SKILL.md'), converted);
+  log.dim(`command: ${action.name} → .codex/skills/${action.skillName}/`);
+}
+
+function syncRulesToInstructions(root) {
+  const rules = getClaudeRules(root);
+  const section = buildRulesSection(root, rules);
+  const instructionsPath = path.join(root, '.codex', 'instructions.md');
+  let content = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, 'utf8') : '';
+  content = updateInstructionsSection(content, RULES_SYNC_START, RULES_SYNC_END, section);
+  fs.writeFileSync(instructionsPath, content);
+  log.dim(`rules: ${rules.length} file(s) → .codex/instructions.md`);
+}
+
+function syncAgentsToInstructions(root) {
+  const agents = getClaudeCustomAgents(root);
+  const section = buildAgentsSection(root, agents);
+  const instructionsPath = path.join(root, '.codex', 'instructions.md');
+  let content = fs.existsSync(instructionsPath) ? fs.readFileSync(instructionsPath, 'utf8') : '';
+  content = updateInstructionsSection(content, AGENTS_SYNC_START, AGENTS_SYNC_END, section);
+  fs.writeFileSync(instructionsPath, content);
+  log.dim(`agents: ${agents.length} file(s) → .codex/instructions.md`);
+}
+
+// ── Display ────────────────────────────────────────────────────────────────
+
+function formatActionLabel(type) {
+  if (type === 'new') return `${colors.green}NEW${colors.reset}`;
+  if (type === 'updated') return `${colors.yellow}UPD${colors.reset}`;
+  return `${colors.dim}OK${colors.reset}`;
+}
+
+function printSummary(actions) {
+  const claudeToCodex = actions.filter(a => a.direction === 'claude-to-codex');
+  const codexToClaude = actions.filter(a => a.direction === 'codex-to-claude');
+  const inSync = actions.filter(a => a.type === 'in-sync');
+
+  if (claudeToCodex.length > 0) {
+    console.log('  Claude → Codex:');
+    for (const a of claudeToCodex) {
+      console.log(`    [${formatActionLabel(a.type)}] ${a.category}: ${a.name}`);
+    }
+  }
+
+  if (codexToClaude.length > 0) {
+    console.log('  Codex → Claude:');
+    for (const a of codexToClaude) {
+      console.log(`    [${formatActionLabel(a.type)}] ${a.category}: ${a.name}`);
+    }
+  }
+
+  if (inSync.length > 0) {
+    console.log(`  ${colors.dim}Already in sync: ${inSync.length} item(s)${colors.reset}`);
+  }
+}
+
+function printResults(counts) {
+  const c2c = counts['claude-to-codex'];
+  const c2cl = counts['codex-to-claude'];
+  const total = c2c.new + c2c.updated + c2cl.new + c2cl.updated;
+
+  if (total === 0 && counts.synced > 0) {
+    log.success(`Everything is already in sync (${counts.synced} item(s))`);
+    return;
+  }
+
+  console.log('');
+  if (c2c.new + c2c.updated > 0) {
+    console.log(`  Claude → Codex: ${c2c.new} new, ${c2c.updated} updated`);
+  }
+  if (c2cl.new + c2cl.updated > 0) {
+    console.log(`  Codex → Claude: ${c2cl.new} new, ${c2cl.updated} updated`);
+  }
+  if (counts.synced > 0) {
+    console.log(`  ${colors.dim}Skipped: ${counts.synced} (already in sync)${colors.reset}`);
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const quiet = args.includes('--quiet');
+
+  const root = findProjectRoot();
+
+  if (!quiet) {
+    log.header('Synchronize Agent Runtimes');
+  }
+
+  // Step 1: Detect runtimes
+  const hasClaude = isClaudeInstalled(root);
+  const hasCodex = isCodexInstalled(root);
+
+  if (!hasClaude && !hasCodex) {
+    log.error('No runtime installations found.');
+    log.info('Install Claude Code: npx 5-phase-workflow');
+    log.info('Install Codex: npx 5-phase-workflow --codex');
+    process.exit(1);
+  }
+
+  if (!hasClaude) {
+    log.error('Claude Code runtime not installed.');
+    log.info('Install with: npx 5-phase-workflow');
+    process.exit(1);
+  }
+
+  if (!hasCodex) {
+    log.error('Codex runtime not installed.');
+    log.info('Install with: npx 5-phase-workflow --codex');
+    process.exit(1);
+  }
+
+  if (!quiet) {
+    log.success('Both runtimes detected');
+  }
+
+  // Step 2-3: Inventory and classify
+  const actions = [
+    ...classifySkillActions(root),
+    ...classifyCommandActions(root),
+    ...classifyRulesActions(root),
+    ...classifyAgentActions(root)
+  ];
+
+  if (actions.length === 0) {
+    log.info('No user-generated content found to synchronize.');
+    process.exit(0);
+  }
+
+  const actionable = actions.filter(a => a.type !== 'in-sync');
+
+  if (actionable.length === 0) {
+    log.success(`Everything is already in sync (${actions.length} item(s))`);
+    process.exit(0);
+  }
+
+  // Step 4: Show summary
+  if (!quiet) {
+    console.log('');
+    printSummary(actions);
+    console.log('');
+  }
+
+  if (dryRun) {
+    log.info('Dry run — no changes made.');
+    process.exit(0);
+  }
+
+  // Step 5: Execute
+  const counts = executeSync(root, actions);
+
+  // Step 6: Report
+  if (!quiet) {
+    log.header('Synchronization Complete');
+    printResults(counts);
+  }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "5-phase-workflow",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "A 5-phase feature development workflow for Claude Code",
   "bin": {
     "5-phase-workflow": "bin/install.js"

package/src/commands/5/analyze-feature.md

@@ -0,0 +1,159 @@
+---
+name: 5:analyze-feature
+description: Analyze any feature, dataflow, or domain concept in the codebase and generate comprehensive documentation with mermaid diagrams. Use when you need to understand how a feature works end-to-end, trace a dataflow, or document a domain area.
+allowed-tools: Read, Write, Glob, Grep, Task, AskUserQuestion
+user-invocable: true
+---
+
+<role>
+You are a Codebase Analyst. Your job is to analyze features, dataflows, and domain concepts in this codebase and produce comprehensive documentation with mermaid diagrams.
+You do NOT write code. You do NOT refactor. You only read, analyze, and document.
+</role>
+
+# Analyze Feature
+
+Generate comprehensive documentation for any feature, dataflow, or domain concept by analyzing the codebase.
+
+## Arguments
+
+- `$ARGUMENTS`: Description of what to analyze (e.g., "user authentication flow", "how orders get processed", "payment integration")
+
+## Step 0: Validate Input
+
+If `$ARGUMENTS` is empty, vague, or ambiguous (e.g., "analyze this", "the thing", or a single word without clear context), use AskUserQuestion to clarify:
+- What specific feature, dataflow, or domain concept should be analyzed?
+- Optionally: which modules or layers are most relevant?
+
+Do NOT proceed until you have a clear understanding of what to analyze.
+
+## Step 1: Determine Scope and Output Name
+
+1. Derive a short kebab-case name from the analysis subject (e.g., `user-auth`, `order-processing`, `payment-integration`). This becomes the filename: `{name}-analysis.md`.
+
+2. Identify the relevant modules and layers to analyze. If `.5/index/` exists, read the index files for a quick structural overview. Otherwise, use Glob to understand the project layout.
+
+3. Use Glob and Grep to locate the relevant source files. Search for key classes, interfaces, functions, and types related to the analysis subject.
+
+## Step 2: Analyze the Codebase
+
+Spawn Explore agents (one or more in parallel depending on scope) to thoroughly read all relevant files. Tailor the agents to the analysis subject:
+
+### For Domain/Feature Analysis
+
+Read across the relevant layers following the project's dependency flow (e.g., models -> services -> controllers -> routes, or entities -> repositories -> handlers -> endpoints). Identify the layer structure from the codebase scan.
+
+### For Dataflow Analysis
+
+Trace the data path through all involved components. Follow inputs from entry points (API endpoints, event handlers, CLI commands) through processing layers to outputs (database writes, API responses, events published).
+
+### For Cross-Cutting Analysis
+
+Examine shared concerns as relevant: validation, authentication, error handling, logging, caching, event publishing.
+
+Request structured output from each agent covering the entities, flows, relationships, and patterns found.
+
+## Step 3: Generate Documentation
+
+Using the analysis results, create a comprehensive markdown document.
+
+**The document MUST follow this structure** (omit sections that don't apply to the analysis subject):
+
+```markdown
+# {Analysis Title}
+
+{1-3 sentence summary of what this feature/dataflow does and why it exists}
+
+---
+
+## Table of Contents
+{auto-generated links to sections below}
+
+---
+
+## Overview
+{High-level description of the feature/concept, its purpose, and where it fits in the system}
+{Mention the involved modules and their roles}
+
+---
+
+## Data Flow
+{For each major operation, create a mermaid sequence diagram}
+{Show the path from entry point through processing layers to output}
+{Include relevant function/method names and payload types}
+
+---
+
+## Domain Model
+{mermaid classDiagram or erDiagram showing entities and their relationships}
+{Include: key fields, types, relationships with cardinality}
+{Show: value objects, enums, and aggregate boundaries where relevant}
+
+---
+
+## Operations
+
+### Writes (Commands/Mutations)
+{Table: Operation | Handler/Service | Description | Key Validation}
+
+### Reads (Queries)
+{Table: Query | Handler/Service | Description | Return Type}
+
+---
+
+## API / Entry Points
+{Table: Method | Path/Topic/Command | Handler | Description}
+
+---
+
+## Event Flow
+{If async events are involved (Kafka, RabbitMQ, webhooks, etc.)}
+{mermaid sequence diagram showing event production/consumption}
+{Include: event names, topics, consumer handlers}
+
+---
+
+## Module Dependencies
+{mermaid graph showing which modules depend on which}
+{Use subgraphs to group by domain or layer}
+
+---
+
+## Key Implementation Details
+{Notable patterns, edge cases, business rules worth highlighting}
+{Reference specific classes/functions and file paths}
+```
+
+### Mermaid Diagram Guidelines
+
+- **Sequence diagrams** (`sequenceDiagram`): For request/response flows across layers
+- **Class diagrams** (`classDiagram`): For domain model relationships and aggregate structure
+- **ER diagrams** (`erDiagram`): For persistence model relationships
+- **Flowcharts** (`flowchart TD`): For decision trees, validation flows, state machines
+- **Graph diagrams** (`graph LR` or `graph TD`): For module dependencies, component trees
+- Keep node labels short but descriptive
+- Use subgraphs to group related nodes by module or layer
+- Use dotted lines (`-.->`) for optional/indirect relationships
+
+## Step 4: Write File
+
+1. Write the documentation using the Write tool to `.5/analysis/{name}-analysis.md`.
+
+2. Report to the user:
+   ```
+   Analysis saved to .5/analysis/{name}-analysis.md
+
+   Sections included:
+   - {list of sections that were generated}
+   - {N} mermaid diagrams
+
+   Modules analyzed: {list of modules examined}
+   ```
+
+## Important Notes
+
+- Read ALL relevant files thoroughly before writing -- do not guess or assume
+- Every mermaid diagram must be syntactically valid
+- Reference specific class/function names and file paths so the reader can navigate to the source
+- Focus on the specific feature/dataflow requested, not the entire codebase
+- Follow the data through all layers from entry point to output
+- Document both the happy path and notable error/validation paths

package/src/commands/5/plan-feature.md

@@ -14,20 +14,22 @@ After creating the spec, you are FINISHED. You do not continue. You do not offer
 </role>
 
 <constraints>
-HARD CONSTRAINTS — violations waste tokens and get blocked by plan-guard:
-- NEVER write code, pseudo-code, or implementation snippets in any output
-- NEVER describe HOW something will be implemented (file contents, signatures, class structures)
-- NEVER create an implementation plan, file list, component breakdown, or step-by-step build guide — that is Phase 2's job
-- NEVER suggest "shall I continue with implementation planning?" or "let me create the plan" — you are DONE after feature.md
-- NEVER offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
-- NEVER spawn Task agents with subagent_type other than Explore
-- NEVER write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
-- NEVER call EnterPlanMode — the workflow has its own planning process
-- NEVER use Bash to create, write, or modify files — this bypasses the plan-guard and is a constraint violation
-- NEVER continue past the completion message — when you output "Feature spec created at...", you are FINISHED
-- The feature spec describes WHAT and WHY, never HOW
-- If you feel the urge to plan implementation or write code, STOP — ask a clarifying question instead
-- Your output is a SPECIFICATION, not a design document. No code. No file layouts. No API shapes. No implementation plans.
+HARD CONSTRAINTS:
+- Do NOT write code or pseudo-code — describe behavior and data shapes in natural language or tables
+- Do NOT create implementation plans, file lists, or step-by-step build guides — that is Phase 2's job
+- Do NOT offer to proceed to the next phase — the user will invoke `/5:plan-implementation` themselves
+- Do NOT spawn Task agents with subagent_type other than Explore
+- Do NOT write to any file except .5/.planning-active, .5/features/{name}/codebase-scan.md, and .5/features/{name}/feature.md
+- Do NOT call EnterPlanMode — the workflow has its own planning process
+- Do NOT use Bash to create, write, or modify files — this bypasses the plan-guard
+- Do NOT continue past the completion message — when you output "Feature spec created at...", you are FINISHED
+
+WHAT IS ALLOWED:
+- Name existing classes, modules, services, and patterns
+- Describe entity fields with domain types
+- Reference existing patterns as models
+- Mention affected methods or APIs by name
+- Include data shape tables with field names and types — these are part of the requirement
 </constraints>
 
 <write-rules>
@@ -42,11 +44,10 @@ Any other Write target WILL be blocked by the plan-guard hook. Do not attempt it
 Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 
 **Content rules for feature.md:**
-- Requirements use natural language ("The system shall..."), NOT code
-- Affected Components lists module/domain names, NOT file paths
-- NO code snippets, NO pseudo-code, NO type definitions
-- Entity definitions describe data CONCEPTS, not DB schemas or TypeScript interfaces
-- Acceptance criteria describe observable behavior, NOT test code
+- Write naturally — reference existing classes, modules, and patterns by name for precision
+- Entity definitions include field names and domain types — these define the requirement
+- Acceptance criteria describe observable behavior
+- No code blocks, no pseudo-code, no class hierarchy designs
 </output-format>
 
 <collaboration-strategy>
@@ -193,7 +194,7 @@ Targeted exploration for feature planning.
 
 ### Step 4: Create Feature Specification
 
-> **ROLE CHECK:** You are writing a SPECIFICATION (WHAT/WHY), not a design document (HOW). Zero code, zero file paths to create, zero signatures. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
+> **ROLE CHECK:** You are writing a FEATURE SPECIFICATION. After writing feature.md you are DONE — do NOT proceed to implementation planning or coding.
 
 **Extract ticket ID from git branch:**
 - The Explore agent from Step 2 already ran `git branch --show-current` — find the branch name in its results
@@ -209,25 +210,14 @@ Write to `.5/features/{name}/feature.md` using Write tool, where `{name}` is eit
 
 Use the template structure from `.claude/templates/workflow/FEATURE-SPEC.md`.
 
-Populate all sections:
-- Ticket ID & Summary
-- Problem Statement
-- Visual Overview (optional mermaid diagrams — see below)
-- Requirements (functional and non-functional)
-- Constraints
-- Affected Components (from exploration)
-- Acceptance Criteria
-- Alternatives Considered
-- Decisions (from the conversation) — label each with **[DECIDED]**, **[FLEXIBLE]**, or **[DEFERRED]**
-
-**Visual Overview (optional mermaid diagrams):**
-Include mermaid diagrams in the spec when they add clarity. Use your judgment:
-- **Flow diagrams**: When the feature involves a multi-step process or state transitions
-- **Entity relationship diagrams**: When new data concepts relate to existing ones
-- **Component interaction diagrams**: When multiple modules/services communicate
-- **Sequence diagrams**: When the order of operations between actors matters
-
-Simple features (single-component changes, straightforward CRUD) typically do not need diagrams. Do not add diagrams for the sake of having them. Diagrams describe WHAT happens, not HOW it is implemented. No class diagrams, no file-level architecture diagrams, no code-level sequence diagrams.
+Populate the sections from the template. Key guidance:
+- **Overview**: Write a short narrative (3-5 sentences) merging the problem and the solution
+- **What Changes**: Group by logical concern, not by module layer. Name existing classes and patterns. Use entity tables where new data models are introduced
+- **Existing Patterns to Follow**: Be specific — these are the highest-value pointers for Phase 2
+- **Scope**: Be explicit about what's in and what's out
+- **Decisions**: Label each from the conversation
+- **Diagrams**: Include only when they add clarity. Simple features don't need them
+- **Alternatives**: Only include if genuinely discussed and the reasoning matters. Delete if empty
 
 **Decision labeling rules:**
 - **[DECIDED]**: The user gave a clear, specific answer → Phase 2 planner and Phase 3 agents MUST honor exactly

package/src/commands/5/plan-implementation.md

@@ -110,11 +110,11 @@ This activates (or refreshes) the plan-guard hook which prevents accidental sour
 
 ### Step 1: Load Feature Spec *(skip if live context)*
 
-**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, requirements, acceptance criteria, affected components, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
+**If live context:** You already have the feature spec discussion in your conversation history. Extract ticket ID, what changes (by logical concern), acceptance criteria, existing patterns to follow, scope, and decisions from what was discussed. Output `✓ Step 1 skipped (live context)` and proceed to Step 1b.
 
 **If no live context:** Read `.5/features/{feature-name}/feature.md` (where `{feature-name}` is the argument provided).
 
-Extract: Ticket ID, requirements (functional and non-functional), acceptance criteria, affected components, and **decisions**.
+Extract: Ticket ID, overview, what changes (each logical concern), existing patterns to follow, constraints, scope, acceptance criteria, and **decisions**.
 
 **Decision labels from feature spec:**
 - **[DECIDED]** items are locked — your plan MUST honor them exactly. Do not override or reinterpret.

package/src/commands/5/synchronize-agents.md

@@ -0,0 +1,60 @@
+---
+name: 5:synchronize-agents
+description: Synchronize user-generated skills, rules, and custom content between Claude Code and Codex runtimes
+allowed-tools: Bash, Read, AskUserQuestion
+user-invocable: true
+model: haiku
+context: fork
+---
+
+<role>
+You are a Runtime Synchronizer. You run the sync script and report results.
+You do NOT modify files manually. After reporting, you are DONE.
+</role>
+
+# Synchronize Agent Runtimes
+
+Synchronizes user-generated content (skills, commands, agents, rules) between the Claude Code (`.claude/`) and Codex (`.codex/`) runtimes.
+
+## Step 1: Locate the Sync Script
+
+The script is `bin/sync-agents.js` in the workflow package. Find it by checking these paths in order:
+
+1. `./bin/sync-agents.js` (development checkout / project root)
+2. `./node_modules/5-phase-workflow/bin/sync-agents.js` (local npm install)
+
+Read `.5/version.json` if available — its location confirms the project root.
+
+Store the resolved path for the following steps.
+
+If the script cannot be found, tell the user: "Sync script not found. Update the workflow first: `npx 5-phase-workflow --upgrade`" and **stop**.
+
+## Step 2: Dry Run
+
+Run the script in dry-run mode to preview what will be synced:
+
+```bash
+node {script-path} --dry-run
+```
+
+If the script exits with a non-zero code (missing runtime, no content), show the output and **stop**.
+
+If there are no actionable changes (everything in sync), report that and **stop**.
+
+## Step 3: Confirm with User
+
+Show the dry-run output. Ask: "Proceed with synchronization?"
+
+If the user declines, stop.
+
+## Step 4: Execute Sync
+
+```bash
+node {script-path}
+```
+
+## Step 5: Report
+
+Show the script output. Summarize what was synced.
+
+Note: This command works identically from both Claude Code (`/5:synchronize-agents`) and Codex (`$5-synchronize-agents`). The script auto-detects the project root.

package/src/templates/workflow/FEATURE-SPEC.md

@@ -1,135 +1,100 @@
 <!-- TEMPLATE RULES:
-- Requirements use natural language, not code
-- Affected Components lists module/domain names, not file paths
-- Entity definitions describe data concepts, not schemas or interfaces
-- Acceptance criteria describe observable behavior, not test assertions
-- NO code, pseudo-code, or implementation details anywhere in this document
-- Visual Overview section is OPTIONAL — delete it if the feature doesn't benefit from diagrams
-- Mermaid diagrams describe WHAT happens, not HOW it is implemented
+- Write naturally
+- Reference existing classes, modules, and patterns by name for precision
+- Entity definitions include field names and domain types
+- Acceptance criteria describe observable behavior
+- No code blocks, no pseudo-code, no class hierarchy designs
+- Delete any OPTIONAL section that doesn't add value for this feature
 -->
 
 # Feature: {TICKET-ID} - {Title}
 
-## Ticket ID
-{TICKET-ID}
+**Ticket:** {TICKET-ID}
 
-## Summary
-{1-2 sentence overview: what capability is being added and who benefits}
+## Overview
 
-## Problem Statement
-{Describe the current pain point or gap. Who experiences it and what is the impact?}
+{What is the problem or gap, and what capability is being added? Write this as a short narrative
+that covers who is affected, why the change matters, and what the end result looks like.}
 
-## Visual Overview
-<!-- OPTIONAL: Include mermaid diagrams only when they add clarity to the feature.
-     Delete this entire section if the feature is simple enough to understand without diagrams.
-     Use whichever diagram types are relevant — you don't need all of them. -->
+<!-- OPTIONAL: Include mermaid diagrams only when they add clarity.
+     Delete this section for simple features. Use whichever diagram type fits. -->
 
-<!-- Process Flow — use when the feature involves a multi-step process or state transitions -->
 ```mermaid
 flowchart TD
-    A[Start state] --> B[Step 1]
-    B --> C{Decision point}
-    C -->|Yes| D[Outcome 1]
-    C -->|No| E[Outcome 2]
+    A[Current state] --> B[Change]
+    B --> C[New capability]
 ```
 
-<!-- Entity Relationships — use when new data concepts relate to existing ones -->
-```mermaid
-erDiagram
-    ENTITY-A ||--o{ ENTITY-B : "relationship"
-    ENTITY-B }|--|| ENTITY-C : "relationship"
-```
+## What Changes
 
-<!-- Component Interactions — use when multiple modules or services communicate -->
-```mermaid
-sequenceDiagram
-    actor User
-    participant ComponentA
-    participant ComponentB
-    User->>ComponentA: action
-    ComponentA->>ComponentB: interaction
-    ComponentB-->>User: result
-```
+{Describe what the feature does in natural, flowing prose. Name existing classes, modules, and patterns
+where relevant. Group by logical concern, not by module layer. Each subsection should tell the reader
+what happens and which parts of the codebase are involved.}
 
-## Requirements
+### {Logical concern 1, e.g., "New data model"}
 
-### Functional Requirements
-- {The system shall... [describe observable behavior]}
-- ...
+{Describe the change. Name affected modules and classes. If a new entity is introduced, describe its
+fields and types in a table:}
 
-### Non-Functional Requirements
-- {Performance, reliability, scalability, or compatibility expectations}
-- ...
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| ... | ... | ... | ... |
 
-## Constraints
-- {Business rules that limit the solution space}
-- {Technical boundaries from existing architecture}
-- {Timeline or resource limitations}
+### {Logical concern 2, e.g., "CRUD operations"}
 
-## Affected Components
-- **{component/module-1}** - {What changes here}
-- **{component/module-2}** - {What changes here}
-- **{component/module-3}** - {What changes here}
-- ...
+{Describe the behavior. Reference existing patterns to follow, e.g.,
+"Follow the same approach as the UserService update flow."}
 
-## Entity/Component Definitions
+### {Logical concern 3, e.g., "API exposure"}
 
-### {EntityName} (if applicable)
-<!-- Describe the data CONCEPT, not the implementation. No TypeScript, no SQL. -->
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| id | {Entity}Id | Yes | Unique identifier |
-| name | String | Yes | Entity name |
-| ... | ... | ... | ... |
+{Describe what gets exposed and how.}
 
 ### Business Rules
+
 - {Rule 1}
 - {Rule 2}
-- ...
 
-## Acceptance Criteria
-- [ ] {Observable behavior that proves this requirement is met}
-- [ ] {Observable behavior that proves this requirement is met}
-- [ ] {Observable behavior that proves this requirement is met}
+## Existing Patterns to Follow
+
+{List concrete patterns from the codebase that the implementation should mirror.
+These are high-value pointers for Phase 2 -- be specific.}
+
+- **{Pattern name}** -- {where it lives and what to reuse from it}
 - ...
 
-## Alternatives Considered
+## Constraints
+
+- {Business rules that limit the solution space}
+- {Technical boundaries from existing architecture}
+
+## Scope
+
+**In scope:**
+- {What is included}
 
-### Option 1: {Alternative approach}
-**Pros:** {Benefits}
-**Cons:** {Drawbacks}
-**Decision:** Rejected because {reason}
+**Out of scope:**
+- {What is explicitly excluded and why}
 
-### Option 2: {Another alternative}
-**Pros:** {Benefits}
-**Cons:** {Drawbacks}
-**Decision:** Rejected because {reason}
+## Acceptance Criteria
 
-### Chosen Approach: {Selected approach}
-**Rationale:** {Why this approach was chosen}
+- [ ] {Observable behavior that proves a requirement is met}
+- [ ] ...
 
 ## Decisions
 
-<!-- Record key decisions from the spec discussion.
-     Tag each with exactly one of: [DECIDED], [FLEXIBLE], [DEFERRED]
-     - [DECIDED]: Locked — Phase 2 planner and Phase 3 agents MUST honor exactly
-     - [FLEXIBLE]: Claude's discretion — planner chooses the best approach
-     - [DEFERRED]: Out of scope — planner MUST NOT include in the plan
--->
+<!-- Tag each: [DECIDED] = locked, [FLEXIBLE] = planner chooses, [DEFERRED] = not in this iteration -->
 
-### {Topic: brief description of what was decided}
-**Context:** {Why this decision came up}
-**Decision:** {What was decided} **[DECIDED]**
+- **{Topic}:** {What was decided and why} **[DECIDED]**
+- **{Topic}:** {General direction, planner chooses specifics} **[FLEXIBLE]**
+- **{Topic}:** {Not addressing now -- reason} **[DEFERRED]**
 
-### {Topic: area left to implementer's discretion}
-**Context:** {What was discussed}
-**Decision:** {General direction, implementer chooses specifics} **[FLEXIBLE]**
+<!-- OPTIONAL: Only include if alternatives were genuinely discussed and the reasoning matters -->
+## Alternatives Considered
 
-### {Topic: explicitly deferred item}
-**Context:** {Why it was raised}
-**Decision:** {Not addressing now — reason} **[DEFERRED]**
+- **{Alternative}:** Rejected because {reason}
+- **{Chosen approach}:** Selected because {reason}
 
 ## Next Steps
-After approval:
-1. Run `/clear` to reset context
+
+1. Run `/clear` to reset context (optional)
 2. Run `/5:plan-implementation {TICKET-ID}-{description}`