cofounder-crew 0.1.11 → 0.1.13

package/README.md

@@ -1,7 +1,9 @@
 <div align="center">
+  <img src="https://raw.githubusercontent.com/eugeneyvt/cofounder-crew/main/assets/cofounder_crew_social.png" alt="Cofounder Crew - local AI teams for Codex." />
+  <br />
   <h1>Cofounder Crew</h1>
   <p>
-    Conversation-first local AI teams for Codex.
+    Turn one Codex session into a local AI team for your repo.
     <br />
     No dashboard. No orchestration server. No new IDE.
   </p>
@@ -15,341 +17,288 @@
   <p>
     <a href="#quickstart">Quickstart</a>
     ·
-    <a href="#using-the-team">Using The Team</a>
+    <a href="#why-it-exists">Why</a>
     ·
-    <a href="#configuration">Configuration</a>
+    <a href="#how-it-works">How It Works</a>
     ·
-    <a href="#updating">Updating</a>
+    <a href="#configure-the-team">Configure</a>
     ·
-    <a href="#cli">CLI</a>
+    <a href="#docs">Docs</a>
   </p>
 </div>
 
 ## What It Is
 
-Cofounder Crew gives a project-local team to the Codex session you already use.
+Cofounder Crew is a plain-file team runtime for Codex.
 
-You initialize a project once, open Codex in that directory, and talk normally. Codex becomes the Cofounder/orchestrator: it reads the roster, delegates focused work to configured teammates, waits for results, reviews outputs, and owns the final response back to you.
+You keep using Codex as the interface. Cofounder adds a project-local `.cofounder/` folder, a small MCP server, and a roster of teammates that Codex can delegate to. Each teammate can have its own prompt, model, sandbox, write mode, memory, MCP servers, and native Codex skills.
 
-Everything is stored as plain files in the project. There is no web app, hosted control plane, or separate editor.
+The result is simple: open Codex in a repo, talk normally, and let Codex coordinate focused workers instead of stuffing every role and every tool into one context.
 
 ## Quickstart
 
-Open Codex in the project you want to configure and paste:
+Fastest path: open Codex in your project and paste the bootstrap prompt.
+
+<details>
+<summary><strong>Copy Codex bootstrap prompt</strong></summary>
 
 ```text
-Install and configure Cofounder Crew for this computer and this project.
-Use https://github.com/eugeneyvt/cofounder-crew as the source/reference if you need more context.
-
-Before changing anything, inspect:
-- Node.js and npm are available, and Node is >=22.
-- Whether this project already has .cofounder/.
-- Whether this project already has AGENTS.md.
-- Whether cofounder-crew is already installed in package.json.
-- Whether Codex already has an MCP server named "cofounder".
-- Whether this is a Git repo with at least one commit.
-
-Then choose the smallest safe setup:
-- If .cofounder/ is missing, initialize Cofounder. Use the worktree template only when the repo has at least one commit; otherwise use the default template.
-- If .cofounder/ already exists, do not reinitialize it. Verify the files, report the project_context mode, and report whether .cofounder/.gitignore ignores runs/, worktrees/, and members/*/home/. Do not change .cofounder/.gitignore unless I explicitly ask.
-- Keep project_context.mode as auto unless I ask for a manually curated .cofounder/project.md.
-- If this project has package.json, prefer a dev dependency install. Otherwise use npm create.
-- Install or repair the Codex MCP entry only if it is missing or wrong.
-- If AGENTS.md already exists, do not overwrite it. Show me the Cofounder bridge block to add.
-- If AGENTS.md does not exist, let Cofounder create it.
-
-After setup, summarize exactly what changed and tell me whether I need to restart Codex.
+Set up Cofounder Crew in this project and explain each meaningful action as you go.
+
+Use https://github.com/eugeneyvt/cofounder-crew as the reference if you need more context. Work from the current project cwd. Do not commit, push, publish, or overwrite existing AGENTS.md or .cofounder files without asking.
+
+Goal:
+- make the global cofounder command available
+- initialize or repair the project-local Cofounder setup
+- install or repair the Codex MCP entry
+- verify the setup
+- tell me exactly how to start using the team from Codex
+
+Process:
+
+1. Inspect the current state first.
+   Check:
+   - current cwd
+   - node --version and npm --version
+   - codex --version
+   - whether command -v cofounder succeeds
+   - whether package.json exists
+   - whether package.json already contains cofounder-crew in dependencies or devDependencies
+   - whether .cofounder/team.yaml exists
+   - whether AGENTS.md exists
+   - whether AGENTS.md contains the Cofounder Crew bridge
+   - whether this is a Git repo
+   - whether Git HEAD exists
+   - whether Codex MCP server "cofounder" exists and points to:
+     npx -y --package cofounder-crew -- cofounder serve mcp
+
+2. Install the global CLI when needed.
+   - If command -v cofounder fails, run:
+     npm install -g cofounder-crew@latest
+   - Do not add cofounder-crew to package.json unless I explicitly ask for project-local pinning.
+   - If global install fails or is not allowed, use the one-off npm runner:
+     npx -y --package cofounder-crew@latest -- cofounder <command>
+     and substitute that prefix for `cofounder` in the commands below.
+
+3. Initialize or repair with the CLI.
+   - If .cofounder/team.yaml is missing, run:
+     cofounder start --setup-codex --yes
+   - If .cofounder/team.yaml already exists, do not re-run init. Run the safe updater instead:
+     cofounder update --yes
+   - Use --template worktree only if I explicitly asked for isolated worktrees or this repo clearly already uses that workflow. Worktree mode requires a Git repo with at least one commit.
+
+4. Preserve user-owned files.
+   - Do not overwrite AGENTS.md.
+   - If AGENTS.md exists but the Cofounder bridge is missing, show me the exact bridge block and explain that I should add it for proactive delegation.
+   - Do not overwrite existing member prompts, member settings, memory files, or project-owned MCP files.
+   - Do not add root .gitignore entries automatically. Only report recommended ignore entries if they are missing.
+
+5. Verify before claiming success.
+   Run:
+   - cofounder doctor
+   - codex mcp get cofounder, if Codex CLI is available
+   - npm ls -g cofounder-crew --depth=0, if global npm installs are available
+   - npm ls cofounder-crew --depth=0 only if the project is intentionally pinned
+
+6. Final response format.
+   Tell me:
+   - whether Cofounder is available globally or via the one-off npm runner
+   - which files were created or changed
+   - whether AGENTS.md needs a manual bridge block
+   - whether I need to restart Codex
+   - the first message to send after restart:
+     Use the Cofounder team. Show me who is available.
+   - the 3 most useful follow-up commands:
+     cofounder add
+     cofounder doctor
+     cofounder team
+
+Do not stop after printing commands unless a command would be unsafe. Actually perform the safe setup steps, then report the result.
+If a verification step fails, do not say the setup is complete. Explain the failure and the next command or manual step needed.
 ```
 
-Manual setup:
+</details>
+
+The same prompt is available at [docs/prompts/bootstrap-codex.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/prompts/bootstrap-codex.md).
+
+Terminal setup:
 
 ```bash
+npm install -g cofounder-crew@latest
 cd my-project
-npm create cofounder@latest -- --setup-codex --yes
+cofounder start --setup-codex
 codex
 ```
 
-For isolated implementation work in Git worktrees:
+For non-interactive setup:
 
 ```bash
-cd my-project
-npm create cofounder@latest -- --template worktree --setup-codex --yes
-codex
+cofounder start --setup-codex --yes
 ```
 
-Worktree mode requires a Git repository with at least one commit.
-
-For an existing package where you want the runtime pinned in `devDependencies`:
+For isolated implementation tasks, use the worktree template. It requires a Git repo with at least one commit:
 
 ```bash
-npm install --save-dev cofounder-crew
-npx cofounder init --template worktree
-npx cofounder setup codex --install
+cofounder start --template worktree --setup-codex
 codex
 ```
 
-## Using The Team
-
-After installation, the main interface is Codex chat:
+Then ask Codex:
 
 ```text
 Use the Cofounder team. Show me who is available.
 ```
 
-```text
-Plan this feature, delegate implementation to the right teammate, and keep me posted.
-```
+## How It Feels
 
-```text
-Ask backend to inspect this repo and summarize the implementation boundaries.
-```
+You keep talking to Codex. Cofounder turns the background work into delegated, inspectable tasks.
 
 ```text
-Ask reviewer to review backend's last diff before we apply it.
-```
-
-Codex should delegate when a configured teammate owns the work. It should also wait for a real result before treating delegated work as complete.
+You: Plan this billing change and use the team.
 
-## What Gets Installed
+Codex: I will ask backend to inspect the implementation boundary, then ask reviewer to check the patch.
 
-```text
-AGENTS.md
-.cofounder/
-  .gitignore
-  codex-instructions.md
-  project.md
-  team.yaml
-  members/
-    lead/
-      prompt.md
-      settings.toml
-      home/
-    backend/
-      prompt.md
-      settings.toml
-      home/
-    reviewer/
-      prompt.md
-      settings.toml
-      home/
-  memory/
-  runs/
-  worktrees/
+Cofounder:
+- backend runs in an isolated worktree
+- reviewer checks the diff
+- Codex reads the results, applies only what you approve, and gives you the final summary
 ```
 
-`AGENTS.md` is for the primary Codex session. It tells Codex to act as the Cofounder/orchestrator.
-
-Worker project context has two modes:
-
-```yaml
-project_context:
-  mode: auto
-  file: project.md
-```
+## Why It Exists
 
-`auto` is the default. Each delegated worker gets fresh context derived from `AGENTS.md`, with the Cofounder bridge/orchestrator text removed. Project rules after the bridge are preserved even when there is no following heading.
+Most "AI crew" tools start with a UI, a server, or a framework. Cofounder starts with the thing you already use: Codex in your repo.
 
-`manual` makes workers read `.cofounder/project.md` instead. Use it when you want a curated worker context that does not change until you edit or sync it.
+| What you get | Why it matters |
+| --- | --- |
+| Codex stays the interface | No new app to learn. Chat with Codex and let it orchestrate. |
+| Local plain files | Team config, prompts, memory, runs, and worktrees are inspectable in the repo. |
+| Focused teammates | Backend, reviewer, designer, or any custom role can have its own instructions and settings. |
+| Scoped MCP | Give Pencil to a designer, GitHub to a reviewer, or no tools to a strict review agent. |
+| Scoped skills | Assign selected project skills, selected user skills, or team-only skills per teammate. |
+| Worktree execution | Let workers make patches in isolated Git worktrees before you apply them. |
+| Observable delegation | Codex can list the team, delegate, wait, inspect logs, read results, review diffs, cancel, and interrupt. |
 
-```yaml
-project_context:
-  mode: manual
-  file: project.md
-```
+Good fit:
 
-Refresh the manual snapshot with:
+- repos where Codex already does useful work, but needs clearer role boundaries
+- teams that want local, inspectable configuration instead of a hosted agent dashboard
+- projects with specialist tools that should not be exposed to every agent
 
-```bash
-npx cofounder sync project
-```
+Not the goal:
 
-Generated task logs, worktrees, and member runtime home files are ignored by `.cofounder/.gitignore`.
+- replacing Codex
+- running a hosted orchestration platform
+- hiding prompts, logs, memory, or task output behind a private control plane
 
-## Existing AGENTS.md
+## How It Works
 
-If `AGENTS.md` already exists, Cofounder will not overwrite it.
+Cofounder installs one MCP server into Codex:
 
-Add this bridge block so Codex adopts the Cofounder role:
+```bash
+codex mcp add cofounder -- npx -y --package cofounder-crew -- cofounder serve mcp
+```
 
-```markdown
-## Cofounder Crew
+Inside each project, Cofounder creates:
 
-This project uses Cofounder Crew for local AI teamwork. You are the Cofounder/orchestrator for this project. Read .cofounder/codex-instructions.md, use the Cofounder MCP tools, and proactively delegate substantive work to the team member whose responsibilities best match the task. Do not perform specialist work yourself when a configured team member owns that responsibility; coordinate the work, monitor progress, and synthesize the final response.
+```text
+.cofounder/
+  team.yaml                 # roster, responsibilities, context mode
+  codex-instructions.md     # orchestrator instructions for the primary Codex session
+  project.md                # worker-safe project context
+  members/<member>/         # prompt, settings, runtime home
+  mcp/                      # project-owned MCP servers
+  skills/                   # team-only skills
+  memory/                   # project and member memory notes
+  runs/                     # task records, logs, results
+  worktrees/                # optional isolated task worktrees
 ```
 
-When `project_context.mode` is `auto`, keep this bridge text unchanged unless you know why you are changing it. Cofounder recognizes this orchestrator text and removes it from delegated worker context, so workers receive project rules without being told that they are the main orchestrator.
-
-Cofounder keeps the full generated guidance in `.cofounder/codex-instructions.md`.
+The primary Codex session reads the Cofounder instructions and uses MCP tools to coordinate the team. Delegated teammates still run from the original project cwd, but with their own Codex settings and runtime home when isolation is needed.
 
-## Configuration
+## Configure The Team
 
-The roster lives in `.cofounder/team.yaml`:
+The guided flow covers the common edits:
 
-```yaml
-members:
-  backend:
-    title: Backend Engineer
-    responsibilities:
-      - inspect and modify code
-      - understand implementation boundaries
-      - write focused tests
-    can_call:
-      - reviewer
+```bash
+cofounder start
+cofounder add
+cofounder doctor
 ```
 
-Each teammate has a prompt and settings:
+Deterministic commands are available for agents and scripts:
 
-```text
-.cofounder/members/backend/
-  prompt.md
-  settings.toml
-  home/
+```bash
+cofounder member add designer --title "Product Designer" --model gpt-5.5 --write-mode worktree
+cofounder mcp add pencil --url https://example.com/mcp --assign designer
+cofounder skill add design-review --scope team --assign designer
+cofounder skill assign api-workflow backend --scope project
+cofounder context mode manual
+cofounder context sync
 ```
 
-Example settings:
+If the global command is not available, prefix commands with `npx -y --package cofounder-crew -- cofounder`.
 
-```toml
-model = "gpt-5.5"
-sandbox = "workspace-write"
-approval = "never"
-reasoning_effort = "high"
+Project skills live in `.agents/skills/` and can also be assigned to teammates. Team-only skills live in `.cofounder/skills/` and are only linked into selected member runtimes.
 
-[write]
-mode = "worktree"
+Common recipes are in [docs/examples.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/examples.md).
 
-[mcp]
-mode = "inherit"
-allow = []
+## Updating
 
-[memory]
-project = true
-member = true
-max_snippets = 5
+Safe project update:
 
-[runner.codex]
-include_project_doc = false
-json = true
-extra_args = []
-use_member_home = false
+```bash
+cofounder update
 ```
 
-Useful settings:
-
-| Setting | Purpose |
-| --- | --- |
-| `write.mode = "direct"` | Run the teammate in the main working tree. |
-| `write.mode = "worktree"` | Run implementation in `.cofounder/worktrees/<task_id>` for review before apply. |
-| `mcp.mode = "inherit"` | Give the teammate the same Codex MCP environment. |
-| `mcp.mode = "none"` | Keep the teammate local-only. The generated reviewer uses this default. |
-| `mcp.mode = "allowlist"` | Give the teammate only selected MCP servers. |
-| `include_project_doc = false` | Prevent raw `AGENTS.md` from being injected by Codex. Cofounder supplies worker-safe project context itself. |
-
-## MCP Tools
-
-Cofounder exposes the team runtime to Codex through MCP:
-
-| Tool | Purpose |
-| --- | --- |
-| `team.list` | Read the roster and responsibility map. |
-| `team.capabilities` | Inspect runtime capabilities. |
-| `team.delegate` | Start a delegated task. |
-| `team.wait` | Wait briefly for a task and return status, next action, result, and recent logs. A wait timeout means the task is still running, not failed. |
-| `team.result` | Read a task result with explicit empty/truncated flags. |
-| `team.status` | Check task status and metadata. |
-| `team.logs` | Read task events and logs. |
-| `team.diff` | Inspect a worktree task patch. |
-| `team.apply` | Apply a worktree task patch to the main tree. |
-| `team.cancel` | Cancel a running task. |
-| `team.interrupt` | Cancel and resume with steering instructions. |
-
-Manual MCP setup:
+If the global command is not available, use the one-off npm runner:
 
 ```bash
-codex mcp add cofounder -- npx -y --package cofounder-crew -- cofounder mcp
+npx -y --package cofounder-crew@latest -- cofounder update --yes
 ```
 
-Restart Codex after changing MCP configuration.
+`cofounder update` repairs the Codex MCP entry, runs doctor, and preserves existing `.cofounder/`, member prompts/settings, memory, MCP config, `package.json`, and `AGENTS.md`. Skip MCP repair with `cofounder update --no-setup-codex`.
 
-## Updating
+Update the global CLI itself:
 
-Paste this into Codex from the project you want to update:
-
-```text
-Update Cofounder Crew for this computer and this project.
-
-Inspect first:
-- Latest npm versions for cofounder-crew and create-cofounder.
-- Whether this project has cofounder-crew in package.json.
-- The installed project version with `npm ls cofounder-crew --depth=0` when package.json exists.
-- Whether Codex MCP server "cofounder" exists and points at `npx -y --package cofounder-crew -- cofounder mcp`.
-- Whether .cofounder/team.yaml, project_context mode, member prompts/settings, .cofounder/project.md, and .cofounder/.gitignore exist.
-- Whether .cofounder/.gitignore ignores runs/, worktrees/, and members/*/home/.
-- Whether AGENTS.md contains the Cofounder bridge block.
-
-Then update safely:
-- If cofounder-crew is installed in package.json, update it with npm.
-- If MCP is missing or wrong, repair it.
-- Do not re-run init over an existing .cofounder/.
-- Do not overwrite team prompts, settings, memory, or AGENTS.md.
-- If .cofounder/.gitignore is missing entries, report the recommended entries but do not add them without explicit approval.
-- If project_context mode is manual, run `cofounder sync project` if you want to refresh .cofounder/project.md from AGENTS.md.
-- If generated instructions changed, show me any bridge/config changes to apply manually.
-- If MCP changed, tell me to restart Codex from this project directory.
-
-Summarize old versions, new versions, changed files, and manual follow-ups.
+```bash
+cofounder self update
 ```
 
-Manual update commands:
+Project-local pinning is optional:
 
 ```bash
-npm install --save-dev cofounder-crew@latest
-
-# Optional: inspect recommended runtime ignore entries without changing files.
-printf "runs/\nworktrees/\nmembers/*/home/\n"
-
-# Optional when project_context.mode is manual:
-npx cofounder sync project
-
-codex mcp remove cofounder
-codex mcp add cofounder -- npx -y --package cofounder-crew -- cofounder mcp
-
-npm view cofounder-crew version
-npm ls cofounder-crew --depth=0
-codex mcp get cofounder
+cofounder pin
 ```
 
-## CLI
+## Docs
 
-The CLI is for setup, debugging, automation, and fallback workflows.
+| Topic | Link |
+| --- | --- |
+| Docs home | [docs/README.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/README.md) |
+| Codex bootstrap prompt | [docs/prompts/bootstrap-codex.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/prompts/bootstrap-codex.md) |
+| Team configuration, AGENTS.md, context, MCP, and skills | [docs/configuration.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/configuration.md) |
+| CLI commands | [docs/cli.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/cli.md) |
+| Delegation runtime, worktrees, logs, and interrupts | [docs/runtime.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/runtime.md) |
+| Practical examples | [docs/examples.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/examples.md) |
+| FAQ | [docs/faq.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/faq.md) |
+| Updating an existing project | [docs/updating.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/docs/updating.md) |
 
-```bash
-npx -y --package cofounder-crew -- cofounder setup codex --install
-npx -y --package cofounder-crew -- cofounder sync project
-npx -y --package cofounder-crew -- cofounder team
-npx -y --package cofounder-crew -- cofounder status <task_id>
-npx -y --package cofounder-crew -- cofounder logs <task_id>
-npx -y --package cofounder-crew -- cofounder diff <task_id>
-npx -y --package cofounder-crew -- cofounder apply <task_id>
-```
+## Packages
 
-## Interruption
+`create-cofounder` initializes a project with `npm create cofounder@latest`.
 
-Codex `exec` currently runs delegated tasks as subprocesses. Cofounder supports cancellation and resume-based steering:
+`cofounder-crew` provides the `cofounder` CLI and MCP runtime.
 
-1. discover the Codex session id,
-2. cancel the running process,
-3. start a resumed task with revised instructions.
+## Requirements
 
-The runtime reports this as:
+- Node.js 22+
+- npm
+- Codex CLI
+- Git with at least one commit when using worktree mode
 
-```json
-{
-  "live_interrupt": false,
-  "interrupt_mode": "cancel-resume"
-}
-```
+## Contributing
 
-## Development
+Local development quick start:
 
 ```bash
 npm install
@@ -358,26 +307,12 @@ npm test
 npm run build
 ```
 
-## Publishing
-
-Publishing runs through GitHub Actions and npm Trusted Publishing.
-
-One-time npm setup for both packages:
+Before opening a pull request, read [CONTRIBUTING.md](https://github.com/eugeneyvt/cofounder-crew/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/eugeneyvt/cofounder-crew/blob/main/CODE_OF_CONDUCT.md). Report vulnerabilities through the [Security Policy](https://github.com/eugeneyvt/cofounder-crew/blob/main/SECURITY.md), not public issues.
 
-| Package | Trusted publisher |
-| --- | --- |
-| `cofounder-crew` | GitHub Actions, `eugeneyvt/cofounder-crew`, workflow `publish-npm.yml` |
-| `create-cofounder` | GitHub Actions, `eugeneyvt/cofounder-crew`, workflow `publish-npm.yml` |
+## Support
 
-Release flow:
+Use [GitHub Issues](https://github.com/eugeneyvt/cofounder-crew/issues) for bugs, broken setup flows, and feature requests.
 
-```bash
-npm version <new-version> --no-git-tag-version
-npm version <new-version> --workspace create-cofounder --no-git-tag-version
-git add package.json package-lock.json packages/create-cofounder/package.json
-git commit -m "chore: release v<new-version>"
-git tag v<new-version>
-git push origin main --tags
-```
+## License
 
-Then publish the GitHub release for the new `vX.Y.Z` tag. The workflow checks, builds, tests, and publishes both npm packages.
+MIT