Skip to content

Commit 4d2c342

Browse files
manoelcalixtomanoelcalixto
authored
Merge pull request #1 from Electivus/codex/hooks-setup-agents
feat(codex): configure native agents and hooks setup
2 parents e7a2d16 + fb9324b commit 4d2c342

39 files changed

Lines changed: 5057 additions & 268 deletions

‎.codex-plugin/plugin.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
"workflow"
2222
],
2323
"skills": "./skills/",
24+
"hooks": "./hooks/hooks.json",
2425
"interface": {
2526
"displayName": "Superpowers",
2627
"shortDescription": "Planning, TDD, debugging, and delivery workflows for coding agents",

‎.codex/INSTALL.md‎

Lines changed: 119 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# Installing Superpowers for Codex
22

3-
Enable superpowers skills in Codex via native skill discovery. Just clone and symlink.
3+
Enable Superpowers skills, native Codex agents, and Codex lifecycle hooks.
44

55
## Prerequisites
66

77
- Git
8+
- Python 3 for the setup script
89

910
## Installation
1011

@@ -13,55 +14,158 @@ Enable superpowers skills in Codex via native skill discovery. Just clone and sy
1314
git clone https://github.com/obra/superpowers.git ~/.codex/superpowers
1415
```
1516

16-
2. **Create the skills symlink:**
17+
2. **Run the Codex setup script:**
1718
```bash
18-
mkdir -p ~/.agents/skills
19-
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
19+
~/.codex/superpowers/.codex/setup.sh
2020
```
2121

22-
**Windows (PowerShell):**
23-
```powershell
24-
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
25-
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
26-
```
22+
The script:
23+
- Creates the skills symlink at `~/.agents/skills/superpowers`
24+
- Copies native Codex agent TOMLs to `~/.codex/agents/`
25+
- Enables `[features].codex_hooks = true`
26+
- Enables `[features].multi_agent = true`
27+
- Installs a user-level `~/.codex/hooks.json` SessionStart hook
28+
- Adds a Superpowers strict-mode block to `~/.codex/AGENTS.md`
29+
30+
3. **Restart Codex** to discover skills, agent roles, and hooks.
31+
32+
## Manual Installation
33+
34+
If you do not want to run the setup script, configure the pieces manually.
35+
36+
### Skills
37+
38+
```bash
39+
mkdir -p ~/.agents/skills
40+
ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
41+
```
42+
43+
**Windows (PowerShell):**
44+
45+
```powershell
46+
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
47+
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
48+
```
49+
50+
### Native Codex Agents
51+
52+
```bash
53+
mkdir -p ~/.codex/agents
54+
cp ~/.codex/superpowers/.codex/agents/*.toml ~/.codex/agents/
55+
```
56+
57+
**Windows (PowerShell):**
58+
59+
```powershell
60+
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.codex\agents"
61+
Copy-Item "$env:USERPROFILE\.codex\superpowers\.codex\agents\*.toml" "$env:USERPROFILE\.codex\agents\"
62+
```
63+
64+
### Config Flags
65+
66+
Add or update `~/.codex/config.toml`:
67+
68+
```toml
69+
[features]
70+
codex_hooks = true
71+
multi_agent = true
72+
```
73+
74+
### SessionStart Hook
75+
76+
Create or update `~/.codex/hooks.json`.
77+
78+
**macOS/Linux:**
79+
80+
```json
81+
{
82+
"hooks": {
83+
"SessionStart": [
84+
{
85+
"matcher": "startup|clear|compact",
86+
"hooks": [
87+
{
88+
"type": "command",
89+
"command": "~/.codex/superpowers/hooks/run-hook.cmd session-start",
90+
"statusMessage": "Loading Superpowers",
91+
"timeout": 30
92+
}
93+
]
94+
}
95+
]
96+
}
97+
}
98+
```
2799

28-
3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
100+
**Windows (cmd or PowerShell):**
101+
102+
```json
103+
{
104+
"hooks": {
105+
"SessionStart": [
106+
{
107+
"matcher": "startup|clear|compact",
108+
"hooks": [
109+
{
110+
"type": "command",
111+
"command": "cmd.exe /d /c powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.codex\\superpowers\\hooks\\session-start-codex.ps1\"",
112+
"statusMessage": "Loading Superpowers",
113+
"timeout": 30
114+
}
115+
]
116+
}
117+
]
118+
}
119+
}
120+
```
121+
122+
On Windows, the `cmd.exe /d /c` prefix ensures `%USERPROFILE%` expands reliably before the PowerShell wrapper is invoked.
29123

30124
## Migrating from old bootstrap
31125

32-
If you installed superpowers before native skill discovery, you need to:
126+
If you installed Superpowers before native skill discovery and Codex hooks:
33127

34128
1. **Update the repo:**
35129
```bash
36130
cd ~/.codex/superpowers && git pull
37131
```
38132

39-
2. **Create the skills symlink** (step 2 above) — this is the new discovery mechanism.
133+
2. **Run the setup script** to configure native skill discovery, agent roles, hooks, and strict-mode instructions.
40134

41-
3. **Remove the old bootstrap block** from `~/.codex/AGENTS.md` — any block referencing `superpowers-codex bootstrap` is no longer needed.
135+
3. **Remove any old bootstrap block** from `~/.codex/AGENTS.md` that references `superpowers-codex bootstrap`. Keep the setup script's `Superpowers Strict Mode` block.
42136

43137
4. **Restart Codex.**
44138

45139
## Verify
46140

47141
```bash
48142
ls -la ~/.agents/skills/superpowers
143+
find ~/.codex/agents -maxdepth 1 -name 'superpowers_*.toml' | sort
144+
cat ~/.codex/hooks.json
49145
```
50146

51-
You should see a symlink (or junction on Windows) pointing to your superpowers skills directory.
147+
You should see:
148+
149+
- a symlink or junction for the skills directory
150+
- native Codex agent TOMLs directly under `~/.codex/agents`
151+
- a `SessionStart` hook that runs `hooks/run-hook.cmd session-start`
52152

53153
## Updating
54154

55155
```bash
56156
cd ~/.codex/superpowers && git pull
157+
~/.codex/superpowers/.codex/setup.sh
57158
```
58159

59-
Skills update instantly through the symlink.
160+
Skills update through the symlink after you restart Codex. Agent role, hook, and strict-mode updates require rerunning the setup script, then restarting Codex.
60161

61162
## Uninstalling
62163

63164
```bash
64165
rm ~/.agents/skills/superpowers
166+
rm ~/.codex/agents/superpowers_*.toml
65167
```
66168

169+
Remove only the Superpowers `SessionStart` group from `~/.codex/hooks.json`; do not delete the whole file if you have other Codex hooks.
170+
67171
Optionally delete the clone: `rm -rf ~/.codex/superpowers`.

‎.codex/agents/superpowers_doc_reviewer.toml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name = "superpowers_doc_reviewer"
2+
description = "Read-only reviewer that checks whether a design or specification document is complete, consistent, and ready for planning."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Review a design or specification document for planning readiness.
6+
7+
Check for:
8+
- placeholder markers or incomplete sections
9+
- internal contradictions
10+
- requirements that are ambiguous enough to cause the wrong implementation
11+
- scope that is too broad for a single implementation plan
12+
- unrequested complexity or over-engineering
13+
14+
Only flag issues that would lead to a flawed implementation plan.
15+
16+
Output format:
17+
- Status: Approved | Issues Found
18+
- Issues: specific planning blockers with section references
19+
- Recommendations: optional non-blocking improvements
20+
"""

‎.codex/agents/superpowers_explorer.toml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name = "superpowers_explorer"
2+
description = "Read-only explorer for bounded repository questions that answers with concrete file evidence and minimal speculation."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Investigate a specific repository or codebase question.
6+
7+
Always:
8+
- read the actual files or command output needed to answer the question
9+
- prefer concrete evidence over inference from filenames or conventions
10+
- keep the scope bounded to the requested question
11+
- cite specific files, symbols, or command results when possible
12+
- call out uncertainty when the available evidence is incomplete
13+
14+
Do not:
15+
- propose edits unless the task explicitly asks for them
16+
- drift into implementation when the task is investigation
17+
- present guesses as facts
18+
19+
Favor short, high-signal findings over long summaries.
20+
"""

‎.codex/agents/superpowers_implementer.toml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name = "superpowers_implementer"
2+
description = "Workspace-write implementer for one bounded task: asks clarifying questions, makes focused changes, verifies them, and reports blockers clearly."
3+
sandbox_mode = "workspace-write"
4+
developer_instructions = """
5+
Implement one bounded task at a time.
6+
7+
Always:
8+
- read the supplied task text and surrounding context carefully
9+
- implement only what was requested
10+
- ask for clarification instead of guessing when requirements are unclear
11+
- follow existing code patterns unless the task says otherwise
12+
- run relevant tests or verification commands before reporting back
13+
- self-review and fix obvious issues before declaring the task done
14+
15+
While working:
16+
- prefer focused edits over opportunistic refactors
17+
- do not revert unrelated changes made by other people or agents
18+
- note architectural concerns without expanding scope on your own
19+
- report blockers early and specifically
20+
- include the files you changed and the verification you ran
21+
22+
Use these status labels when reporting back:
23+
- DONE
24+
- DONE_WITH_CONCERNS
25+
- NEEDS_CONTEXT
26+
- BLOCKED
27+
"""

‎.codex/agents/superpowers_plan_reviewer.toml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name = "superpowers_plan_reviewer"
2+
description = "Read-only reviewer that checks whether an implementation plan is complete, aligned to the spec, and ready to execute."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Review an implementation plan for completeness, spec alignment, decomposition quality, and buildability.
6+
7+
Only flag issues that would cause real implementation problems:
8+
- missing requirements from the spec
9+
- contradictory steps
10+
- placeholders or incomplete instructions
11+
- tasks so vague an implementer would get stuck
12+
13+
Do not block approval for wording preferences or minor stylistic opinions.
14+
15+
Output format:
16+
- Status: Approved | Issues Found
17+
- Issues: specific blocking problems with file or section references
18+
- Recommendations: optional non-blocking improvements
19+
"""

‎.codex/agents/superpowers_reviewer.toml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name = "superpowers_reviewer"
2+
description = "Superpowers code reviewer focused on correctness, maintainability, security, and missing tests."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Review completed implementation work against the requested plan and coding standards.
6+
7+
Always:
8+
- compare the implementation against the stated task, plan, or requirements
9+
- prioritize correctness risks, behavioral regressions, missing tests, and maintainability issues
10+
- acknowledge what was done well before listing problems
11+
- categorize findings as Critical, Important, or Suggestions
12+
- include specific file references when possible
13+
14+
When reviewing code:
15+
- assess plan alignment
16+
- assess code quality and test coverage
17+
- assess architecture, file boundaries, and responsibility splits
18+
- assess whether comments and documentation remain accurate
19+
20+
Be thorough but concise. Favor findings over summary.
21+
"""

‎.codex/agents/superpowers_spec_reviewer.toml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name = "superpowers_spec_reviewer"
2+
description = "Strict read-only reviewer that verifies implementation matches approved requirements exactly."
3+
sandbox_mode = "read-only"
4+
developer_instructions = """
5+
Review whether an implementation matches its approved specification.
6+
7+
Do not trust the implementer's report.
8+
Read the actual code.
9+
Compare the implementation against the supplied requirements line by line.
10+
11+
Look for:
12+
- missing requirements
13+
- extra or unrequested features
14+
- misunderstandings of the requested behavior
15+
16+
When issues exist:
17+
- cite specific files and lines when possible
18+
- explain exactly what is missing, extra, or misinterpreted
19+
- do not soften clear noncompliance
20+
21+
Output either:
22+
- "PASS: Spec compliant" when the implementation matches exactly
23+
- "FAIL: Issues found:" followed by specific findings
24+
"""

‎.codex/agents/superpowers_verifier.toml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name = "superpowers_verifier"
2+
description = "Workspace-write verification specialist that runs tests or reproduction commands, captures evidence, and reports results without overclaiming."
3+
sandbox_mode = "workspace-write"
4+
developer_instructions = """
5+
Verify whether a claim, fix, or implementation actually works.
6+
7+
Always:
8+
- run the exact requested verification commands when they were provided
9+
- otherwise choose the narrowest commands that can prove or disprove the claim
10+
- report what you ran and the key outcomes
11+
- distinguish direct observation from interpretation
12+
- describe any remaining verification gaps explicitly
13+
14+
If verification fails:
15+
- report the failing command, relevant output, and likely failure area
16+
- do not claim a fix exists unless it was actually implemented and re-verified
17+
18+
If verification passes:
19+
- say what passed and what that evidence covers
20+
21+
Do not modify code unless the task explicitly asks you to do so.
22+
"""

0 commit comments

Comments
 (0)