An agentic skills framework & software development methodology that works.
Polish docs from 5-agent review
Drew Ritterbcccc692717f
diff --git a/.codex/INSTALL.md b/.codex/INSTALL.mdindex 354ad6553..af335ad9a 100644--- a/.codex/INSTALL.md+++ b/.codex/INSTALL.md@@ -1,6 +1,11 @@# Installing Superpowers for Codex-Quick setup to enable superpowers skills in Codex via native skill discovery.+Quick setup to enable superpowers skills in Codex. The installer links your skills into Codex's native discovery path so they load automatically.++## Prerequisites++- [Node.js](https://nodejs.org/) (v16+)+- Git## Installation@@ -14,21 +19,31 @@ Quick setup to enable superpowers skills in Codex via native skill discovery.node ~/.codex/superpowers/.codex/install-codex.mjs```-3. **Restart Codex** to discover the skills.+3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.++**Windows:** The installer creates a junction (`mklink /J`), which works without Developer Mode.## What the installer does-- Creates a symlink: `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills`-- Adds a small gatekeeper block to `~/.codex/AGENTS.md`+- Links `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills` (symlink on macOS/Linux, junction on Windows)+- Adds a gatekeeper block to `~/.codex/AGENTS.md` that tells Codex to use superpowers skills- If you had the old bootstrap setup, it removes it automatically+## Verify++```bash+ls -la ~/.agents/skills/superpowers+```++You should see a symlink (or junction) pointing to your superpowers skills directory.+## Updating```bashcd ~/.codex/superpowers && git pull```-Skills update instantly through the symlink.+Skills update instantly through the link.## Uninstalling@@ -36,4 +51,4 @@ Skills update instantly through the symlink.rm ~/.agents/skills/superpowers```-Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`.+Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`. Optionally delete the clone: `rm -rf ~/.codex/superpowers`.diff --git a/.codex/install-codex.mjs b/.codex/install-codex.mjsindex d878b0a2b..5db43e333 100644--- a/.codex/install-codex.mjs+++ b/.codex/install-codex.mjs@@ -64,19 +64,21 @@ function createSymlink() {}}- // Create the symlink (or junction on Windows)+ // Create the link (symlink on macOS/Linux, junction on Windows)+ const linkType = isWindows ? 'junction' : 'dir';+ const linkLabel = isWindows ? 'junction' : 'symlink';try {- symlinkSync(repoSkillsDir, symlinkPath, 'junction');- console.log(`✓ Created symlink: ${symlinkPath} → ${repoSkillsDir}`);+ symlinkSync(repoSkillsDir, symlinkPath, linkType);+ console.log(`✓ Created ${linkLabel}: ${symlinkPath} → ${repoSkillsDir}`);} catch (err) {if (isWindows) {- // Symlink failed on Windows — try junction via mklink /J+ // Node API failed on Windows — try junction via cmd.exetry {execSync(`cmd /c mklink /J "${symlinkPath}" "${repoSkillsDir}"`, { stdio: 'pipe' });console.log(`✓ Created junction: ${symlinkPath} → ${repoSkillsDir}`);} catch (junctionErr) {- console.error(`✗ Failed to create symlink or junction: ${junctionErr.message}`);- console.error(` On Windows, enable Developer Mode or run as administrator.`);+ console.error(`✗ Failed to create junction: ${junctionErr.message}`);+ console.error(` Try running PowerShell as administrator.`);process.exit(1);}} else {diff --git a/docs/README.codex.md b/docs/README.codex.mdindex a88bd3db5..b230de10f 100644--- a/docs/README.codex.md+++ b/docs/README.codex.md@@ -31,11 +31,11 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp3. Restart Codex.-The installer creates a symlink from `~/.agents/skills/superpowers` to the repo's `skills/` directory and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.+The installer links `~/.agents/skills/superpowers` to the repo's `skills/` directory (symlink on macOS/Linux, junction on Windows) and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.### Windows-The installer tries symlinks first, then falls back to junctions (`mklink /J`) if symlinks require Developer Mode. Both work for Codex skill discovery.+The installer creates a junction (`mklink /J`) on Windows, which works without Developer Mode. On macOS/Linux it creates a standard symlink. Both work for Codex skill discovery.## How It Works@@ -88,6 +88,8 @@ description: Use when [condition] - [what it does][Your skill content here]```+The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.+## Updating```bash@@ -112,9 +114,9 @@ Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers2. Check skills exist: `ls ~/.codex/superpowers/skills`3. Restart Codex — skills are discovered at startup-### Windows symlink issues+### Windows junction issues-If the installer reports symlink failure, ensure Developer Mode is enabled or run as administrator. The installer will attempt a junction fallback automatically.+The installer creates junctions on Windows, which normally work without special permissions. If junction creation fails, try running PowerShell as administrator.### Node.js not found