pcatattacks · pcatattacks · Mar 26, 2026
diff --git a/.agents/skills/solopreneur/using-solopreneur/SKILL.md b/.agents/skills/solopreneur/using-solopreneur/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: using-solopreneur
+description: Use when the user wants the Solopreneur system, asks which Solopreneur workflow to use, or references `/solopreneur` commands. Routes the request into the shared Solopreneur workflow files.
+---
+
+# Using Solopreneur in Codex
+
+Use this as the single Codex-native entrypoint for the Solopreneur system.
+
+## What to do
+
+1. Determine which Solopreneur workflow best matches the user's request.
+2. Open and follow the matching shared workflow instructions in `skills/<skill>/SKILL.md`.
+3. Read the relevant specialist brief in `agents/*.md` when the workflow depends on a particular role.
+4. Keep Codex support additive: preserve Claude slash commands, plugin files, hooks, and settings.
+5. Save artifacts under `.solopreneur/`.
+
+## Workflow routing
+
+- Idea validation or market research -> `skills/discover/SKILL.md`
+- Product requirements / PRD writing -> `skills/spec/SKILL.md`
+- Ticket breakdown / backlog creation -> `skills/backlog/SKILL.md`
+- Design direction / mockups -> `skills/design/SKILL.md`
+- Planning or implementation -> `skills/build/SKILL.md`
+- Reviews / QA -> `skills/review/SKILL.md`
+- Deployment / launch readiness -> `skills/ship/SKILL.md`
+- Launch copy / announcements -> `skills/release-notes/SKILL.md`
+- Team sessions -> `skills/kickoff/SKILL.md`
+- Parallel ticket execution -> `skills/sprint/SKILL.md`
+- Status summaries -> `skills/standup/SKILL.md`
+- Storytelling / retrospectives -> `skills/story/SKILL.md`
+- Setup / orientation -> `skills/help/SKILL.md`
+- Building a custom org -> `skills/scaffold/SKILL.md`
+
+## Why there is only one Codex skill
+
+The shared Solopreneur workflow files already exist at the repo root in `skills/*/SKILL.md`. This Codex entrypoint stays intentionally thin so the Codex layer does not duplicate every workflow, drift from the shared source of truth, or create generic skill-name collisions like `build`, `review`, or `help` in Codex.
+
+This skill intentionally does **not** force re-reading `AGENTS.md`; that file is treated as repo-level guidance rather than per-invocation workflow logic.
diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md
@@ -0,0 +1,58 @@
+# Installing Solopreneur for Codex
+
+Enable Solopreneur in Codex using Codex's native skill discovery.
+
+## Prerequisites
+
+- OpenAI Codex CLI
+- Git
+
+## Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/pcatattacks/solopreneur-plugin.git ~/.codex/solopreneur-plugin
+   ```
+
+2. **Create the skills symlink:**
+
+   ```bash
+   mkdir -p ~/.agents/skills
+   ln -s ~/.codex/solopreneur-plugin/.agents/skills/solopreneur ~/.agents/skills/solopreneur
+   ```
+
+   **Windows (PowerShell):**
+
+   ```powershell
+   New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
+   cmd /c mklink /J "$env:USERPROFILE\.agents\skills\solopreneur" "$env:USERPROFILE\.codex\solopreneur-plugin\.agents\skills\solopreneur"
+   ```
+
+3. **Restart Codex** to pick up the new skills.
+
+## Verify
+
+```bash
+ls -la ~/.agents/skills/solopreneur
+```
+
+You should see the `using-solopreneur/` skill directory.
+
+## Updating
+
+```bash
+cd ~/.codex/solopreneur-plugin && git pull
+```
+
+## Uninstalling
+
+```bash
+rm ~/.agents/skills/solopreneur
+```
+
+Optionally remove the clone:
+
+```bash
+rm -rf ~/.codex/solopreneur-plugin
+```
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,157 @@
+# Solopreneur for Codex
+
+This repository was originally packaged as a Claude Code plugin, but it is also intended to work cleanly inside Codex.
+
+Codex automatically reads `AGENTS.md`, but the primary Codex-native entrypoints in this repository are the checked-in skills under `.agents/skills/solopreneur/`. Treat this file as the repo-wide compatibility and guardrail layer for those skills.
+
+## Mission
+
+You are operating as part of a virtual company for a solopreneur. The user is the CEO. Your job is to coordinate the right specialist, follow the right workflow, and explain decisions in plain language.
+
+## Codex-native entrypoints
+
+Codex-native entrypoints in this repo are:
+
+- `.agents/skills/solopreneur/using-solopreneur/SKILL.md` for the auto-discovered Codex entrypoint
+- `AGENTS.md` at the repository root for repo-wide instructions and guardrails
+- `.codex/INSTALL.md` for one-shot installation instructions Codex can fetch and follow
+
+## Guidance layering
+
+Use this layering model to avoid duplicate context loading:
+
+- `AGENTS.md`: repo-wide guardrails and compatibility constraints
+- `.agents/skills/solopreneur/using-solopreneur/SKILL.md`: routing entrypoint
+- `skills/*/SKILL.md`: workflow source of truth
+- `agents/*.md`: specialist role guidance
+
+The routing skill should not force re-reading `AGENTS.md` on every invocation.
+
+## How to use this repo in Codex
+
+When a user asks to run a Solopreneur workflow in Codex:
+
+1. Prefer the checked-in `using-solopreneur` Codex skill in `.agents/skills/solopreneur/`; Codex should auto-discover it according to its normal skill scanning rules.
+2. From that skill, open the corresponding shared workflow in `skills/<skill>/SKILL.md`.
+3. Read the relevant specialist brief in `agents/<agent>.md` when agent-specific behavior matters.
+4. Follow the workflow instructions directly, adapting any Claude-specific slash-command wording into natural-language Codex execution.
+5. Save outputs under `.solopreneur/` using the same directory conventions described below.
+6. Manage git operations on the user's behalf, explaining them in plain language before or while you do them.
+
+If the user references a Claude-style command such as `/solopreneur:build`, use `using-solopreneur` to route into the matching shared workflow and supporting project files it references.
+
+## Workflow map
+
+| User intent | Primary file |
+| --- | --- |
+| Validate an idea | `skills/discover/SKILL.md` |
+| Write a PRD/spec | `skills/spec/SKILL.md` |
+| Turn a spec into tickets | `skills/backlog/SKILL.md` |
+| Create UI direction/mockups | `skills/design/SKILL.md` |
+| Plan or implement code | `skills/build/SKILL.md` |
+| Review work | `skills/review/SKILL.md` |
+| Prepare deployment/launch | `skills/ship/SKILL.md` |
+| Draft launch messaging | `skills/release-notes/SKILL.md` |
+| Run a collaborative team session | `skills/kickoff/SKILL.md` |
+| Build multiple tickets in parallel | `skills/sprint/SKILL.md` |
+| Generate a status summary | `skills/standup/SKILL.md` |
+| Turn the work into a narrative | `skills/story/SKILL.md` |
+| Get oriented | `skills/help/SKILL.md` |
+| Scaffold a new org/plugin | `skills/scaffold/SKILL.md` |
+
+## Team structure
+
+Use these specialist files when their perspective is needed:
+
+- Engineer: `agents/engineer.md`
+- Designer: `agents/designer.md`
+- BizOps: `agents/bizops.md`
+- QA: `agents/qa.md`
+- Researcher: `agents/researcher.md`
+- Content Strategist: `agents/content-strategist.md`
+
+## Output directories
+
+Artifacts belong under `.solopreneur/`:
+
+```text
+.solopreneur/
+├── discoveries/
+├── specs/
+├── backlog/
+├── designs/
+├── plans/
+├── releases/
+├── standups/
+├── stories/
+├── observer-log.md
+└── observer-archives/
+```
+
+## Product lifecycle
+
+Default workflow:
+
+```text
+discover -> spec -> backlog -> design -> build -> review -> ship -> release-notes
+```
+
+The user does not have to follow the full sequence. Start where it is most useful.
+
+## Claude Code compatibility guardrails
+
+This file is additive. It must not weaken the existing Claude Code plugin experience.
+
+- Do not rename existing Claude slash commands.
+- Do not move or rewrite files under `.claude-plugin/`, `hooks/`, or `settings.json` just to suit Codex.
+- Treat `skills/*/SKILL.md` and `agents/*.md` as the shared source of truth used by both Claude Code and Codex.
+- When in doubt, add Codex-specific guidance in docs or `AGENTS.md` rather than changing Claude-facing behavior.
+
+## Tooling notes
+
+- Repo-level MCP server definitions live in `.mcp.json`.
+- Hook definitions live in `hooks/hooks.json`.
+- Claude-specific plugin packaging lives in `.claude-plugin/`, but the workflow content itself is plain Markdown and should be executed directly in Codex.
+- `settings.json` contains Claude-specific environment settings; preserve them unless the user asks otherwise.
+
+## Git and checkpoints
+
+You manage version control for the user.
+
+- Create clear checkpoint commits after meaningful milestones.
+- Use plain-language commit messages.
+- Before making a significant change, ensure work is recoverable with git.
+- If the user wants to share work, use GitHub tooling if available.
+
+## Browser and MCP usage
+
+If UI work needs verification, prefer any browser or MCP tools available in the current Codex environment.
+
+If a workflow mentions the Claude Chrome Extension, reinterpret that in Codex as:
+
+- use whatever browser/MCP tools are available now
+- fall back gracefully when those tools are unavailable
+- do not block the workflow on Claude-only integrations
+
+## Observer protocol
+
+Capture why the CEO made decisions, not just what changed.
+
+When the user explains a preference, rejects an option, or pivots direction, append an entry to `.solopreneur/observer-log.md` using this format:
+
+```markdown
+## [TIMESTAMP] - Brief summary
+**Choice**: What the CEO decided
+**Alternatives**: What was rejected (if applicable)
+**Reasoning**: Why, in the CEO's own words
+---
+```
+
+## Compatibility rule
+
+Prefer existing Solopreneur files over inventing new behavior.
+
+This repo should remain compatible with both:
+
+- Claude Code plugin usage via `.claude-plugin/`
+- Codex usage via this `AGENTS.md` plus the existing `agents/` and `skills/` directories
diff --git a/README.md b/README.md
@@ -1,16 +1,18 @@
 # Solopreneur - Your Virtual AI Company
 
+> A Claude Code plugin with a Codex-compatible workspace layer.
+
 You're a solopreneur. You have ideas, ambition, and not enough hours in the day. What if you had a full team -- an engineer, designer, QA lead, researcher, business analyst, and content strategist -- available instantly, working in parallel, and remembering every decision you've ever made?
 
-Solopreneur is a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that turns Claude into a structured virtual company. Not a chatbot you ask questions to. A company with specialists, workflows, and institutional memory.
+Solopreneur is a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that turns Claude into a structured virtual company. It now also ships with a Codex-friendly `AGENTS.md`, so the same agents, workflows, and project conventions can be used directly in OpenAI Codex. Not a chatbot you ask questions to. A company with specialists, workflows, and institutional memory.
 
 ## What Makes This Different
 
 **Specialists beat generalists.** A QA agent whose entire job is finding bugs will find more bugs than asking Claude to "also check for errors." Each agent has a dedicated role, methodology, and toolset -- just like a real employee.
 
 **You don't need to know what to do next.** Every skill suggests the next step when it finishes. Discover an idea, and it suggests writing a spec. Write a spec, and it suggests creating a backlog. The workflow guides you from idea to shipped product.
 
-**Two build modes.** Generate a step-by-step plan and hand it to any coding agent (Cursor, Windsurf, Cline, Aider, or anything else), or have Claude build it directly. You choose per feature.
+**Two build modes.** Generate a step-by-step plan and hand it to any coding agent (Cursor, Windsurf, Cline, Aider, Codex, or anything else), or have Claude build it directly. You choose per feature.
 
 **Your decisions are remembered.** Every choice you make -- what you picked, what you rejected, and why -- is captured in a decision journal. Later, turn that journal into a publishable blog post, tutorial, or case study of your building journey.
 
@@ -39,6 +41,35 @@ cd solopreneur-plugin
 claude --plugin-dir .
 ```
 
+### Use it with Codex
+
+For Codex, Solopreneur now follows Codex-native skill discovery patterns instead of Claude's plugin packaging.
+
+**Quick install inside Codex:**
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/pcatattacks/solopreneur-plugin/refs/heads/main/.codex/INSTALL.md
+```
+
+**Manual install:**
+
+```bash
+git clone https://github.com/pcatattacks/solopreneur-plugin.git ~/.codex/solopreneur-plugin
+mkdir -p ~/.agents/skills
+ln -s ~/.codex/solopreneur-plugin/.agents/skills/solopreneur ~/.agents/skills/solopreneur
+```
+
+Detailed Codex docs: `docs/README.codex.md`.
+
+### Claude Code compatibility
+
+Codex support is additive:
+
+- Claude plugin install and slash commands stay the same.
+- `.claude-plugin/`, `hooks/hooks.json`, and `settings.json` remain the Claude-facing integration points.
+- `skills/*/SKILL.md` and `agents/*.md` remain the shared source of truth for both runtimes.
+- `.agents/skills/solopreneur/using-solopreneur/` provides a single Codex-native, auto-discoverable entrypoint that delegates back to those shared files.
+
 ### First command
 
 ```
@@ -47,6 +78,39 @@ claude --plugin-dir .
 
 This opens an interactive org chart of your AI team and shows you where to start based on your project's current state.
 
+## Claude Code vs Codex Workflow
+
+The **product workflow is the same** in both runtimes:
+
+```
+discover -> spec -> backlog -> design -> build -> review -> ship -> release-notes
+```
+
+What changes is **how the workflow is activated**:
+
+| Concern | Claude Code plugin | Codex |
+| --- | --- | --- |
+| Installation | Marketplace or `claude --plugin-dir .` | Clone + symlink the checked-in `.agents/skills/solopreneur/` bundle, or run the installer from `.codex/INSTALL.md` |
+| Invocation | Slash commands like `/solopreneur:build` | The auto-discovered `using-solopreneur` skill or natural-language prompts |
+| Routing layer | Claude plugin packaging + plugin skill dispatch | Codex skill discovery via `.agents/skills/` + repo `AGENTS.md` guardrails |
+| Shared workflow logic | `skills/*/SKILL.md` | `skills/*/SKILL.md` |
+| Shared role briefs | `agents/*.md` | `agents/*.md` |
+| Artifacts and outputs | `.solopreneur/` | `.solopreneur/` |
+
+So the **workflow content stays the same**; the main difference is the install/discovery/invocation surface.
+
+## Using Solopreneur in Codex
+
+Codex does not use Claude's slash-command plugin UI, so you drive the same workflows with natural language. Codex discovers the checked-in `using-solopreneur` skill from `.agents/skills/solopreneur/`, while `AGENTS.md` provides repo-wide guardrails and shared context.
+
+Examples:
+
+- `Run the Solopreneur discover workflow for an AI meal planner idea.`
+- `Use the build workflow from this repo to plan implementation for .solopreneur/backlog/meal-planner/MVP-001.md.`
+- `Act as the Solopreneur reviewer and review the most recent changes.`
+
+In practice, Codex discovers `using-solopreneur`, and that skill routes into the shared `skills/<skill>/SKILL.md` and `agents/*.md` files as needed. `AGENTS.md` stays as repo-level guidance rather than being re-read each invocation. For installation and usage details, see `docs/README.codex.md`.
+
 ## How It Works
 
 ### The Product Lifecycle
@@ -79,7 +143,7 @@ You don't have to follow the pipeline linearly. Skip steps, jump ahead, or start
 
 When you run `/solopreneur:build`, you're asked how you want to proceed:
 
-**Plan only:** Claude's engineer creates a detailed, step-by-step implementation plan. You take that plan to your preferred coding agent (Cursor, Windsurf, Cline, Aider, or any tool that can follow instructions). When the code is written, come back and Claude's QA agent validates it against the acceptance criteria.
+**Plan only:** Claude's engineer creates a detailed, step-by-step implementation plan. You take that plan to your preferred coding agent (Cursor, Windsurf, Cline, Aider, Codex, or any tool that can follow instructions). When the code is written, come back and Claude's QA agent validates it against the acceptance criteria.
 
 **Build directly:** Claude's engineer creates the plan for reference, then writes the code itself -- installing dependencies, creating files, the whole thing. Progress is reported after each step.
 
@@ -195,9 +259,9 @@ The first time a skill needs browser testing, it will ask if you want to set thi
 
 ### GitHub Integration
 
-For creating repos, managing PRs, and pushing code, the plugin uses the `gh` CLI. Claude handles all git operations for you -- just say "share this on GitHub" or "push my work" and it will walk you through setup if needed.
+For creating repos, managing PRs, and pushing code, the workflow uses the `gh` CLI. In Claude Code, Claude handles those git operations for you. In Codex, the repo's `AGENTS.md` instructs Codex to do the same thing -- just say "share this on GitHub" or "push my work" and it can walk you through setup if needed.
 
-You don't need to know git. Claude creates checkpoints automatically after each milestone, explains what it's saving in plain language, and can undo changes if you ask.
+You don't need to know git. Claude or Codex can create checkpoints after each milestone, explain what is being saved in plain language, and undo changes if you ask.
 
 ## Build Your Own AI Org