From d99347b20dd618e6893dd58104480316e87c841f Mon Sep 17 00:00:00 2001 From: Pranav Dhingra <22510675+pcatattacks@users.noreply.github.com> Date: Wed, 25 Mar 2026 22:44:21 -0400 Subject: [PATCH] Document guidance layering and remove AGENTS re-read --- .../solopreneur/using-solopreneur/SKILL.md | 39 +++++ .codex/INSTALL.md | 58 +++++++ AGENTS.md | 157 ++++++++++++++++++ README.md | 74 ++++++++- docs/README.codex.md | 94 +++++++++++ docs/codex.md | 3 + 6 files changed, 420 insertions(+), 5 deletions(-) create mode 100644 .agents/skills/solopreneur/using-solopreneur/SKILL.md create mode 100644 .codex/INSTALL.md create mode 100644 AGENTS.md create mode 100644 docs/README.codex.md create mode 100644 docs/codex.md diff --git a/.agents/skills/solopreneur/using-solopreneur/SKILL.md b/.agents/skills/solopreneur/using-solopreneur/SKILL.md new file mode 100644 index 0000000..6eedc34 --- /dev/null +++ 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.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 new file mode 100644 index 0000000..945bd69 --- /dev/null +++ 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 new file mode 100644 index 0000000..cdfb105 --- /dev/null +++ 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.md`. +3. Read the relevant specialist brief in `agents/.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 index 1969cad..08af873 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # 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 @@ -10,7 +12,7 @@ Solopreneur is a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude- **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.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 diff --git a/docs/README.codex.md b/docs/README.codex.md new file mode 100644 index 0000000..4767a1d --- /dev/null +++ b/docs/README.codex.md @@ -0,0 +1,94 @@ +# Solopreneur for Codex + +Guide for using the Solopreneur workflow in OpenAI Codex using Codex's native skill discovery. + +## Quick Install + +Tell Codex: + +``` +Fetch and follow instructions from https://raw.githubusercontent.com/pcatattacks/solopreneur-plugin/refs/heads/main/.codex/INSTALL.md +``` + +## Manual Installation + +### Prerequisites + +- OpenAI Codex CLI +- Git + +### Steps + +1. Clone the repo: + + ```bash + git clone https://github.com/pcatattacks/solopreneur-plugin.git ~/.codex/solopreneur-plugin + ``` + +2. Symlink the checked-in Codex skill bundle into the user skill folder Codex scans: + + ```bash + mkdir -p ~/.agents/skills + ln -s ~/.codex/solopreneur-plugin/.agents/skills/solopreneur ~/.agents/skills/solopreneur + ``` + +3. Restart Codex. + +## How this differs from the Claude plugin + +The Solopreneur lifecycle itself does **not** change in Codex. The same shared workflow files still drive the work: + +- `skills/*/SKILL.md` for workflow behavior +- `agents/*.md` for specialist briefs +- `.solopreneur/` for generated artifacts + +What changes in Codex is the outer shell: + +1. **Installation** uses clone + symlink (or `.codex/INSTALL.md`) instead of Claude marketplace/plugin installation. +2. **Invocation** uses the auto-discovered `using-solopreneur` skill (or natural-language prompts) instead of slash commands like `/solopreneur:build`. +3. **Routing** happens through `.agents/skills/solopreneur/using-solopreneur/SKILL.md` into shared root workflows, with `AGENTS.md` as repo-level guardrails. + +If you already know the Claude plugin workflow, think of Codex as a different launcher around the same Solopreneur system. + +## How it works + +- Codex automatically discovers skills from `~/.agents/skills/`. +- This repository ships a single Codex-native entrypoint at `.agents/skills/solopreneur/using-solopreneur/`. +- That skill routes into the existing shared workflow files in `skills/*/SKILL.md` and the role briefs in `agents/*.md`. +- The repository root `AGENTS.md` remains the shared repo-wide guardrail file for Codex. + +## Local repository usage + +If you are already inside this repository and launch `codex` from the repo root, Codex can also discover the checked-in `.agents/skills/` directory directly. + +## Included Codex skills + +- `using-solopreneur` + +## Usage examples + +After installation, Codex can activate Solopreneur skills automatically or by name. Examples: + +- `Use using-solopreneur and help me figure out the right workflow for a new SaaS idea.` +- `Use using-solopreneur for an AI meal planner idea and route me to the right Solopreneur workflow.` +- `Use using-solopreneur for .solopreneur/backlog/meal-planner/MVP-001.md.` +- `Use using-solopreneur to review the most recent changes.` + +## Design choices + +These choices are intentional and should be preserved unless there is a clear reason to change them: + +1. **Single Codex entry skill** (`using-solopreneur`) rather than many wrappers. +2. **Shared workflow source of truth** in root `skills/*/SKILL.md` and `agents/*.md`. +3. **No forced AGENTS re-read** from the routing skill, to avoid duplicate global context loading. +4. **Additive compatibility**: Codex changes must not alter Claude plugin behavior. + +## Compatibility guarantees + +- Claude plugin packaging stays in `.claude-plugin/`. +- Claude hooks stay in `hooks/hooks.json`. +- Claude settings stay in `settings.json`. +- Shared workflow content stays in `skills/*/SKILL.md`. +- Shared role briefs stay in `agents/*.md`. + +Codex support is additive rather than a replacement for Claude Code. diff --git a/docs/codex.md b/docs/codex.md new file mode 100644 index 0000000..09f00b2 --- /dev/null +++ b/docs/codex.md @@ -0,0 +1,3 @@ +# Moved + +See `docs/README.codex.md` for the maintained Codex installation and usage guide, including design choices and guidance layering.