Update release notes for v3.3.1 writing improvements

Applied Strunk's "Elements of Style" principles:
- Rule 13: Omitted needless words (removed "already", "genuinely", etc.)
- Rule 11: Converted negative to positive form ("don't ask" → "ask only when")
- Rule 10: Used active voice where appropriate
- Rule 15: Improved parallel construction in lists
- General: Made language more direct and concrete

Changes maintain the skill's functionality while improving readability.

.codex/INSTALL.md

@@ -0,0 +1,35 @@
+# Installing Superpowers for Codex
+
+Quick setup to enable superpowers skills in Codex.
+
+## Installation
+
+1. **Clone superpowers repository**:
+   ```bash
+   mkdir -p ~/.codex/superpowers
+   cd ~/.codex/superpowers
+   git clone https://github.com/obra/superpowers.git .
+   ```
+
+2. **Create personal skills directory**:
+   ```bash
+   mkdir -p ~/.codex/skills
+   ```
+
+3. **Update ~/.codex/AGENTS.md** to include this superpowers section:
+   ```markdown
+   ## Superpowers System
+
+   <EXTREMELY_IMPORTANT>
+   You have superpowers. Superpowers teach you new skills and capabilities. RIGHT NOW run: `~/.codex/superpowers/.codex/superpowers-codex bootstrap` and follow the instructions it returns.
+   </EXTREMELY_IMPORTANT>
+   ```
+
+## Verification
+
+Test the installation:
+```bash
+~/.codex/superpowers/.codex/superpowers-codex bootstrap
+```
+
+You should see skill listings and bootstrap instructions. The system is now ready for use.

.codex/superpowers-bootstrap.md

@@ -0,0 +1,33 @@
+# Superpowers Bootstrap for Codex
+
+<EXTREMELY_IMPORTANT>
+You have superpowers.
+
+**Tool for running skills:**
+- `~/.codex/superpowers/.codex/superpowers-codex use-skill <skill-name>`
+
+**Tool Mapping for Codex:**
+When skills reference tools you don't have, substitute your equivalent tools:
+- `TodoWrite` → `update_plan` (your planning/task tracking tool)
+- `Task` tool with subagents → Tell the user that subagents aren't available in Codex yet and you'll do the work the subagent would do
+- `Skill` tool → `~/.codex/superpowers/.codex/superpowers-codex use-skill` command (already available)
+- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
+
+**Skills naming:**
+- Superpowers skills: `superpowers:skill-name` (from ~/.codex/superpowers/skills/)
+- Personal skills: `skill-name` (from ~/.codex/skills/)
+- Personal skills override superpowers skills when names match
+
+**Critical Rules:**
+- Before ANY task, review the skills list (shown below)
+- If a relevant skill exists, you MUST use `~/.codex/superpowers/.codex/superpowers-codex use-skill` to load it
+- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
+- Skills with checklists require `update_plan` todos for each item
+- NEVER skip mandatory workflows (brainstorming before coding, TDD, systematic debugging)
+
+**Skills location:**
+- Superpowers skills: ~/.codex/superpowers/skills/
+- Personal skills: ~/.codex/skills/ (override superpowers when names match)
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+</EXTREMELY_IMPORTANT>

.codex/superpowers-codex

@@ -3,14 +3,40 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { execSync } = require('child_process');
 
 // Paths
 const homeDir = os.homedir();
 const superpowersSkillsDir = path.join(homeDir, '.codex', 'superpowers', 'skills');
 const personalSkillsDir = path.join(homeDir, '.codex', 'skills');
-const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', 'codex', 'superpowers-bootstrap.md');
+const bootstrapFile = path.join(homeDir, '.codex', 'superpowers', '.codex', 'superpowers-bootstrap.md');
+const superpowersRepoDir = path.join(homeDir, '.codex', 'superpowers');
 
 // Utility functions
+function checkForUpdates() {
+    try {
+        // Quick check with 3 second timeout to avoid delays if network is down
+        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
+            cwd: superpowersRepoDir,
+            timeout: 3000,
+            encoding: 'utf8',
+            stdio: 'pipe'
+        });
+
+        // Parse git status output to see if we're behind
+        const statusLines = output.split('\n');
+        for (const line of statusLines) {
+            if (line.startsWith('## ') && line.includes('[behind ')) {
+                return true; // We're behind remote
+            }
+        }
+        return false; // Up to date
+    } catch (error) {
+        // Network down, git error, timeout, etc. - don't block bootstrap
+        return false;
+    }
+}
+
 function extractFrontmatter(filePath) {
     try {
         const content = fs.readFileSync(filePath, 'utf8');
@@ -144,6 +170,17 @@ function runBootstrap() {
     console.log('# ================================');
     console.log('');
 
+    // Check for updates (with timeout protection)
+    if (checkForUpdates()) {
+        console.log('## Update Available');
+        console.log('');
+        console.log('⚠️  Your superpowers installation is behind the latest version.');
+        console.log('To update, run: `cd ~/.codex/superpowers && git pull`');
+        console.log('');
+        console.log('---');
+        console.log('');
+    }
+
     // Show the bootstrap instructions
     if (fs.existsSync(bootstrapFile)) {
         console.log('## Bootstrap Instructions:');

README.md

@@ -1,6 +1,6 @@
 # Superpowers
 
-Give Claude Code superpowers with a comprehensive skills library of proven techniques, patterns, and workflows.
+A comprehensive skills library of proven techniques, patterns, and workflows for AI coding assistants.
 
 ## What You Get
 
@@ -21,7 +21,7 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 
 ## Installation
 
-### Via Plugin Marketplace (Recommended)
+### Claude Code (via Plugin Marketplace)
 
 ```bash
 # In Claude Code
@@ -41,6 +41,12 @@ Read the introduction: [Superpowers for Claude Code](https://blog.fsck.com/2025/
 # /superpowers:execute-plan - Execute plan in batches
 ```
 
+### Codex (Experimental)
+
+**Note:** Codex support is experimental and may require refinement based on user feedback.
+
+Tell Codex to fetch https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md and follow the instructions.
+
 ## Quick Start
 
 ### Using Slash Commands

RELEASE-NOTES.md

@@ -1,5 +1,44 @@
 # Superpowers Release Notes
 
+## v3.3.1 (2025-10-28)
+
+### Improvements
+
+- Updated `brainstorming` skill to require autonomous recon before questioning, encourage recommendation-driven decisions, and prevent agents from delegating prioritization back to humans.
+- Applied writing clarity improvements to `brainstorming` skill following Strunk's "Elements of Style" principles (omitted needless words, converted negative to positive form, improved parallel construction).
+
+### Bug Fixes
+
+- Clarified `writing-skills` guidance so it points to the correct agent-specific personal skill directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex).
+
+## v3.3.0 (2025-10-28)
+
+### New Features
+
+**Experimental Codex Support**
+- Added unified `superpowers-codex` script with bootstrap/use-skill/find-skills commands
+- Cross-platform Node.js implementation (works on Windows, macOS, Linux)
+- Namespaced skills: `superpowers:skill-name` for superpowers skills, `skill-name` for personal
+- Personal skills override superpowers skills when names match
+- Clean skill display: shows name/description without raw frontmatter
+- Helpful context: shows supporting files directory for each skill
+- Tool mapping for Codex: TodoWrite→update_plan, subagents→manual fallback, etc.
+- Bootstrap integration with minimal AGENTS.md for automatic startup
+- Complete installation guide and bootstrap instructions specific to Codex
+
+**Key differences from Claude Code integration:**
+- Single unified script instead of separate tools
+- Tool substitution system for Codex-specific equivalents
+- Simplified subagent handling (manual work instead of delegation)
+- Updated terminology: "Superpowers skills" instead of "Core skills"
+
+### Files Added
+- `codex/INSTALL.md` - Installation guide for Codex users
+- `codex/superpowers-bootstrap.md` - Bootstrap instructions with Codex adaptations
+- `scripts/superpowers-codex` - Unified Node.js executable with all functionality
+
+**Note:** Codex support is experimental. The integration provides core superpowers functionality but may require refinement based on user feedback.
+
 ## v3.2.3 (2025-10-23)
 
 ### Improvements

codex/INSTALL.md

@@ -1,135 +0,0 @@
-# Installing Superpowers for Codex
-
-This guide will help you install and set up the Superpowers skill system for Codex.
-
-## Quick Installation
-
-1. **Clone Superpowers to ~/.codex/superpowers/**:
-   ```bash
-   mkdir -p ~/.codex/superpowers
-   cd ~/.codex/superpowers
-   git clone https://github.com/obra/superpowers.git .
-   ```
-
-2. **Create personal skills directory**:
-   ```bash
-   mkdir -p ~/.codex/skills
-   ```
-
-3. **Add script paths to your environment** (optional but recommended):
-   ```bash
-   echo 'export PATH="$HOME/.codex/superpowers/scripts:$PATH"' >> ~/.bashrc
-   source ~/.bashrc
-   ```
-
-## Directory Structure
-
-After installation, you'll have:
-
-```
-~/.codex/
-├── superpowers/           # Core superpowers repository
-│   ├── skills/           # Core skills (brainstorming, TDD, etc.)
-│   ├── scripts/          # find-skills and skill-run tools
-│   └── .codex/           # Codex-specific configuration
-└── skills/               # Your personal skills (override core)
-    └── category/
-        └── skill-name/
-            └── SKILL.md
-```
-
-## Tool Usage
-
-### Finding Skills
-```bash
-find-skills                    # List all available skills
-find-skills brainstorm        # Filter skills by pattern
-```
-
-### Running Skills
-```bash
-skill-run brainstorming              # Load a skill
-skill-run skills/brainstorming       # Same thing
-```
-
-## Skill Override System
-
-Personal skills in `~/.codex/skills/` take precedence over core skills:
-
-- **Core skill**: `~/.codex/superpowers/skills/brainstorming/SKILL.md`
-- **Personal override**: `~/.codex/skills/brainstorming/SKILL.md` ← This wins
-
-## Bootstrap Setup
-
-The bootstrap system ensures Codex automatically:
-
-1. Reads the superpowers-bootstrap.md on startup
-2. Runs find-skills to show available skills
-3. Knows how to use the skill tools
-
-See `~/.codex/AGENTS.md` for the bootstrap configuration.
-
-## Troubleshooting
-
-### Scripts not found
-```bash
-# Add to PATH or use full paths:
-~/.codex/superpowers/scripts/find-skills
-~/.codex/superpowers/scripts/skill-run
-```
-
-### No skills showing
-```bash
-# Check directory structure:
-ls ~/.codex/superpowers/skills/
-ls ~/.codex/skills/
-```
-
-### Permission errors
-```bash
-# Make scripts executable:
-chmod +x ~/.codex/superpowers/scripts/*
-```
-
-## Creating Personal Skills
-
-1. Create directory structure:
-   ```bash
-   mkdir -p ~/.codex/skills/my-category/my-skill
-   ```
-
-2. Create SKILL.md with frontmatter:
-   ```markdown
-   ---
-   name: My Skill Name
-   description: What this skill does
-   when_to_use: When to apply this skill
-   ---
-
-   # My Skill
-
-   Skill content here...
-   ```
-
-3. Test it:
-   ```bash
-   find-skills my-skill
-   skill-run my-skill
-   ```
-
-## Integration with Codex
-
-Once installed, Codex will automatically have access to:
-
-- **find-skills**: Discover available skills
-- **skill-run**: Load and apply skills
-- **Mandatory workflows**: Brainstorming before coding, systematic debugging, etc.
-- **TodoWrite integration**: Checklist tracking from skills
-
-The bootstrap ensures these tools are available from the first Codex session.
-
-## Compatibility Notes
-
-- Scripts are compatible with bash 3.2+ (works on macOS and Linux)
-- No external dependencies required
-- Works with existing Codex configuration

codex/superpowers-bootstrap.md

@@ -1,131 +0,0 @@
-# Superpowers Bootstrap for Codex
-
-<EXTREMELY_IMPORTANT>
-You have superpowers.
-
-**Tool path for running skills:**
-- superpowers-codex: ~/.codex/superpowers/scripts/superpowers-codex
-
-**Important:** ALL AVAILABLE SKILLS ARE DISCLOSED ABOVE. You have complete visibility into every skill at session start.
-
-**Tool Mapping for Codex:**
-When skills reference tools you don't have, substitute your equivalent tools:
-- `TodoWrite` → `update_plan` (your planning/task tracking tool)
-- `Task` tool with subagents → `codex --yolo exec "prompt"` (see subagent section below)
-- `Skill` tool → `superpowers-codex use-skill` command (already available)
-- `Read`, `Write`, `Edit`, `Bash` → Use your native tools with similar functions
-</EXTREMELY_IMPORTANT>
-
-## Getting Started with Skills
-
-Two skill libraries work together:
-- **Superpowers skills** at `~/.codex/superpowers/skills/` (from superpowers repository)
-- **Personal skills** at `~/.codex/skills/` (yours to create and share)
-
-Personal skills shadow superpowers skills when names match.
-
-## Critical Rules
-
-1. **Use skill-run before announcing skill usage.** The bootstrap does NOT read skills for you. Announcing without calling skill-run = lying.
-
-2. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
-
-3. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
-
-## Mandatory Workflow: Before ANY Task
-
-**1. Review skills list** (completely disclosed above - no searching needed).
-
-**2. If relevant skill exists, YOU MUST use it:**
-
-- Use superpowers-codex: `~/.codex/superpowers/scripts/superpowers-codex use-skill superpowers:skill-name`
-- Read ENTIRE output, not just summary
-- Announce: "I've read the [Skill Name] skill and I'm using it to [purpose]"
-- Follow it exactly
-
-**Don't rationalize:**
-- "I remember this skill" - Skills evolve. Read the current version.
-- "Bootstrap showed it to me" - That was just the list. Read the actual skill.
-- "This doesn't count as a task" - It counts. Find and read skills.
-
-**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
-
-## Skills with Checklists
-
-If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
-
-**Don't:**
-- Work through checklist mentally
-- Skip creating todos "to save time"
-- Batch multiple items into one todo
-- Mark complete without doing them
-
-**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time.
-
-## How to Use skill-run
-
-Every skill has the same structure:
-
-1. **Frontmatter** - `when_to_use` tells you if this skill matches your situation
-2. **Overview** - Core principle in 1-2 sentences
-3. **Quick Reference** - Scan for your specific pattern
-4. **Implementation** - Full details and examples
-5. **Supporting files** - Load only when implementing
-
-**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
-
-**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
-
-## Instructions ≠ Permission to Skip Workflows
-
-Your human partner's specific instructions describe WHAT to do, not HOW.
-
-"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
-
-## Summary
-
-**Starting any task:**
-1. Run find-skills to check for relevant skills
-2. If relevant skill exists → Use skill-run with full path
-3. Announce you're using it
-4. Follow what it says
-
-**Skill has checklist?** TodoWrite for every item.
-
-**Finding a relevant skill = mandatory to read and use it. Not optional.**
-
-## Subagent Orchestration for Codex
-
-When skills reference dispatching subagents or parallel agents, use Codex's subagent capabilities:
-
-**Launch subagents with:**
-```bash
-codex --yolo exec "your detailed prompt here"
-```
-
-**Key guidelines:**
-1. **Always quote/escape prompts** - avoid unescaped backticks or `$()` that shell might interpolate
-2. **Set timeout for long tasks** - use `timeout_ms: 1800000` (30 minutes) in your bash calls
-3. **Parallel execution** - use background jobs (`& ... & wait`) but check individual logs for completion
-4. **Lightweight prompts** - subagents inherit CLI defaults, so keep prompts focused and clear
-
-**Example:**
-```bash
-# Single subagent
-codex --yolo exec "Debug the authentication bug in user.py and propose a fix"
-
-# Parallel subagents
-codex --yolo exec "Test the API endpoints" &
-codex --yolo exec "Review the database schema" &
-wait
-
-# Using superpowers skills in subagents
-codex --yolo exec "Use superpowers:systematic-debugging to find the root cause of the login failure"
-```
-
-**When to use subagents:**
-- Skills mention "dispatching parallel agents"
-- Tasks that can be broken into independent work
-- Code review, testing, or investigation that benefits from fresh perspective
-
----

skills/brainstorming/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating or developing anything, before writing code or im
 
 Transform rough ideas into fully-formed designs through structured questioning and alternative exploration.
 
-**Core principle:** Ask questions to understand, explore alternatives, present design incrementally for validation.
+**Core principle:** Research first, ask targeted questions to fill gaps, explore alternatives, present design incrementally for validation.
 
 **Announce at start:** "I'm using the brainstorming skill to refine your idea into a design."
 
@@ -17,7 +17,8 @@ Transform rough ideas into fully-formed designs through structured questioning a
 
 | Phase | Key Activities | Tool Usage | Output |
 |-------|---------------|------------|--------|
-| **1. Understanding** | Ask questions (one at a time) | AskUserQuestion for choices | Purpose, constraints, criteria |
+| **Prep: Autonomous Recon** | Inspect repo/docs/commits, form initial model | Native tools (ls, cat, git log, etc.) | Draft understanding to confirm |
+| **1. Understanding** | Share findings, ask only for missing context | AskUserQuestion for real decisions | Purpose, constraints, criteria (confirmed) |
 | **2. Exploration** | Propose 2-3 approaches | AskUserQuestion for approach selection | Architecture options with trade-offs |
 | **3. Design Presentation** | Present in 200-300 word sections | Open-ended questions | Complete design with validation |
 | **4. Design Documentation** | Write design document | writing-clearly-and-concisely skill | Design doc in docs/plans/ |
@@ -30,6 +31,7 @@ Copy this checklist to track progress:
 
 ```
 Brainstorming Progress:
+- [ ] Prep: Autonomous Recon (repo/docs/commits reviewed, initial model shared)
 - [ ] Phase 1: Understanding (purpose, constraints, criteria gathered)
 - [ ] Phase 2: Exploration (2-3 approaches proposed and evaluated)
 - [ ] Phase 3: Design Presentation (design validated in sections)
@@ -38,47 +40,53 @@ Brainstorming Progress:
 - [ ] Phase 6: Planning Handoff (if implementing)
 ```
 
-### Phase 1: Understanding
+### Prep: Autonomous Recon
-- Check current project state in working directory
+- Use existing tools (file browsing, docs, git history, tests) to understand current project state before asking anything.
-- Ask ONE question at a time to refine the idea
+- Form your draft model: what problem you're solving, what artifacts exist, and what questions remain.
-- **Use AskUserQuestion tool** when you have multiple choice options
+- Start the conversation by sharing that model: "Based on exploring the project state, docs, working copy, and recent commits, here's how I think this should work…"
-- Gather: Purpose, constraints, success criteria
+- Ask follow-up questions only for information you cannot infer from available materials.
 
-**Example using AskUserQuestion:**
+### Phase 1: Understanding
+- Share your synthesized understanding first, then invite corrections or additions.
+- Ask one focused question at a time, only for gaps you cannot close yourself.
+- **Use AskUserQuestion tool** only when you need the human to make a decision among real alternatives.
+- Gather: Purpose, constraints, success criteria (confirmed or amended by your partner)
+
+**Example summary + targeted question:**
 ```
-Question: "Where should the authentication data be stored?"
+Based on the README and yesterday's commit, we're expanding localization to dashboard and billing emails; admin console is still untouched. Only gap I see is whether support responses need localization in this iteration. Did I miss anything important?
-Options:
-  - "Session storage" (clears on tab close, more secure)
-  - "Local storage" (persists across sessions, more convenient)
-  - "Cookies" (works with SSR, compatible with older approach)
 ```
 
 ### Phase 2: Exploration
 - Propose 2-3 different approaches
-- For each: Core architecture, trade-offs, complexity assessment
+- For each: Core architecture, trade-offs, complexity assessment, and your recommendation
-- **Use AskUserQuestion tool** to present approaches as structured choices
+- **Use AskUserQuestion tool** to present approaches when you truly need a judgement call
-- Ask your human partner which approach resonates
+- Lead with the option you prefer and explain why; invite disagreement if your partner sees it differently
+- Own prioritization: if the repo makes priorities clear, state them and proceed rather than asking
 
 **Example using AskUserQuestion:**
 ```
 Question: "Which architectural approach should we use?"
 Options:
+  - "Direct API calls with retry logic" (simple, synchronous, easier to debug) ← recommended for current scope
   - "Event-driven with message queue" (scalable, complex setup, eventual consistency)
-  - "Direct API calls with retry logic" (simple, synchronous, easier to debug)
   - "Hybrid with background jobs" (balanced, moderate complexity, best of both)
+
+I recommend the direct API approach because it matches existing patterns and minimizes new infrastructure. Let me know if you see a blocker that pushes us toward the other options.
 ```
 
 ### Phase 3: Design Presentation
-- Present in 200-300 word sections
+- Present in coherent sections; use ~200-300 words when introducing new material, shorter summaries once alignment is obvious
 - Cover: Architecture, components, data flow, error handling, testing
-- Ask after each section: "Does this look right so far?" (open-ended)
+- Check in at natural breakpoints rather than after every paragraph: "Stop me if this diverges from what you expect."
-- Use open-ended questions here to allow freeform feedback
+- Use open-ended questions to allow freeform feedback
+- Assume ownership and proceed unless your partner redirects you
 
 ### Phase 4: Design Documentation
-After design is validated, write it to a permanent document:
+After validating the design, write it to a permanent document:
 - **File location:** `docs/plans/YYYY-MM-DD-<topic>-design.md` (use actual date and descriptive topic)
 - **RECOMMENDED SUB-SKILL:** Use elements-of-style:writing-clearly-and-concisely (if available) for documentation quality
-- **Content:** Capture the design as discussed and validated in Phase 3, organized into the sections that emerged from the conversation
+- **Content:** Capture the design as discussed and validated in Phase 3, organized into sections that emerged from the conversation
 - Commit the design document to git before proceeding
 
 ### Phase 5: Worktree Setup (for implementation)
@@ -100,16 +108,15 @@ When your human partner confirms (any affirmative response):
 
 ### When to Use AskUserQuestion Tool
 
-**Use AskUserQuestion for:**
+**Use AskUserQuestion when:**
-- Phase 1: Clarifying questions with 2-4 clear options
+- You need your partner to make a judgement call among real alternatives
-- Phase 2: Architectural approach selection (2-3 alternatives)
+- You have a recommendation and can explain why it’s your preference
-- Any decision with distinct, mutually exclusive choices
+- Prioritization is ambiguous and cannot be inferred from existing materials
-- When options have clear trade-offs to explain
 
-**Benefits:**
+**Best practices:**
-- Structured presentation of options with descriptions
+- State your preferred option and rationale inside the question so your partner can agree or redirect
-- Clear trade-off visibility for partner
+- If you know the answer from repo/docs, state it as fact and proceed—no question needed
-- Forces explicit choice (prevents vague "maybe both" responses)
+- When priorities are spelled out, acknowledge them and proceed rather than delegating the choice back to your partner
 
 ### When to Use Open-Ended Questions
 
@@ -119,6 +126,8 @@ When your human partner confirms (any affirmative response):
 - When partner should describe their own requirements
 - When structured options would limit creative input
 
+Frame them to confirm or expand your current understanding rather than reopening settled topics.
+
 **Example decision flow:**
 - "What authentication method?" → Use AskUserQuestion (2-4 options)
 - "Does this design handle your use case?" → Open-ended (validation)
@@ -150,16 +159,17 @@ digraph revisit_phases {
 - Partner questions approach during Phase 3 → Return to Phase 2
 - Something doesn't make sense → Go back and clarify
 
-**Don't force forward linearly** when going backward would give better results.
+**Avoid forcing forward linearly** when going backward would give better results.
 
 ## Key Principles
 
 | Principle | Application |
 |-----------|-------------|
-| **One question at a time** | Phase 1: Single question per message, use AskUserQuestion for choices |
+| **One question at a time** | Phase 1: Single targeted question only for gaps you can’t close yourself |
 | **Structured choices** | Use AskUserQuestion tool for 2-4 options with trade-offs |
 | **YAGNI ruthlessly** | Remove unnecessary features from all designs |
 | **Explore alternatives** | Always propose 2-3 approaches before settling |
 | **Incremental validation** | Present design in sections, validate each |
 | **Flexible progression** | Go backward when needed - flexibility > rigidity |
+| **Own the initiative** | Recommend priorities and next steps; ask if you should proceed only when requirements conflict |
 | **Announce usage** | State skill usage at start of session |

skills/writing-skills/SKILL.md

@@ -9,7 +9,7 @@ description: Use when creating new skills, editing existing skills, or verifying
 
 **Writing skills IS Test-Driven Development applied to process documentation.**
 
-**Personal skills are written to `~/.claude/skills`** 
+**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** 
 
 You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).