cofounder-crew 0.1.11 → 0.1.13

package/docs/configuration.md

@@ -0,0 +1,200 @@
+# Configuration
+
+Cofounder Crew is configured with plain files in the project.
+
+```text
+.cofounder/
+  team.yaml
+  codex-instructions.md
+  project.md
+  members/<member>/prompt.md
+  members/<member>/settings.toml
+  members/<member>/home/
+  mcp/<server>.toml
+  skills/<skill>/SKILL.md
+  memory/project.md
+  memory/members/<member>.md
+```
+
+## AGENTS.md
+
+`AGENTS.md` is for the primary Codex session. It should tell Codex to act as the Cofounder/orchestrator and to use the Cofounder MCP tools.
+
+If `AGENTS.md` already exists, Cofounder does not overwrite it. Add this bridge block manually:
+
+```markdown
+## Cofounder Crew
+
+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.
+```
+
+Keep the bridge text stable unless you know why you are changing it. In automatic context mode, Cofounder removes this orchestrator block before building worker context, so delegated workers receive project rules without being told they are the primary orchestrator.
+
+## Project Context
+
+Worker project context supports two modes:
+
+```yaml
+project_context:
+  mode: auto
+  file: project.md
+```
+
+`auto` derives worker-safe context from `AGENTS.md` and strips the Cofounder orchestrator block.
+
+`manual` makes workers read `.cofounder/project.md` as the curated project context:
+
+```yaml
+project_context:
+  mode: manual
+  file: project.md
+```
+
+Refresh the manual file with:
+
+```bash
+cofounder context sync
+```
+
+## Team Roster
+
+The roster lives in `.cofounder/team.yaml`.
+
+```yaml
+members:
+  backend:
+    title: Backend Engineer
+    runner: codex
+    prompt: members/backend/prompt.md
+    settings: members/backend/settings.toml
+    home: members/backend/home
+    responsibilities:
+      - inspect and modify code
+      - understand implementation boundaries
+      - write focused tests
+    can_call:
+      - reviewer
+```
+
+`responsibilities` are how the orchestrator decides who should receive work. `can_call` controls which teammates a member may delegate to.
+
+## Member Settings
+
+Each member has a `settings.toml` file:
+
+```toml
+model = "gpt-5.5"
+sandbox = "workspace-write"
+approval = "never"
+reasoning_effort = "high"
+live_interrupt = false
+
+[write]
+mode = "worktree"
+
+[mcp]
+mode = "isolated"
+from_main = []
+team = ["cofounder"]
+
+[skills]
+mode = "isolated"
+from_project = []
+from_main = []
+team = []
+
+[memory]
+project = true
+member = true
+max_snippets = 5
+
+[runner.codex]
+json = true
+extra_args = []
+use_member_home = false
+include_project_doc = false
+```
+
+Common settings:
+
+| Setting | Purpose |
+| --- | --- |
+| `model` | Codex model for this teammate. |
+| `reasoning_effort` | Codex reasoning setting for this teammate. |
+| `sandbox` | Codex sandbox mode. |
+| `approval` | Codex approval policy. |
+| `write.mode = "direct"` | Run in the main working tree. |
+| `write.mode = "worktree"` | Run in `.cofounder/worktrees/<task_id>` and review before apply. |
+| `include_project_doc = false` | Let Cofounder provide worker-safe project context instead of raw `AGENTS.md`. |
+
+## MCP Scoping
+
+MCP is scoped per member.
+
+```toml
+[mcp]
+mode = "isolated"
+from_main = ["github"]
+team = ["pencil"]
+```
+
+`from_main` selects MCP servers from the primary Codex config. By default Cofounder reads `$CODEX_HOME/config.toml`, or `mcp.config_path` if you set it.
+
+`team` selects project-owned MCP servers from `.cofounder/mcp/<server>.toml`.
+
+Modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `isolated` | Give the member only `from_main` and `team` servers. |
+| `none` | Give the member no MCP servers. |
+| `inherit` | Give the member the primary Codex MCP environment. Use sparingly. |
+
+Example project-owned MCP server:
+
+```toml
+# .cofounder/mcp/pencil.toml
+url = "https://example.com/mcp"
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+```
+
+Assign it:
+
+```bash
+cofounder mcp add pencil --url https://example.com/mcp --assign designer
+cofounder mcp assign github backend --source main
+```
+
+## Skill Scoping
+
+Skills are not loaded by pasting paths into prompts. Codex discovers skills at process startup from skill folders, so Cofounder prepares the member runtime before launching Codex.
+
+```toml
+[skills]
+mode = "isolated"
+from_project = ["api-workflow"]
+from_main = ["uncodixfy"]
+team = ["design-review"]
+```
+
+Sources:
+
+| Source | Location | Use it when |
+| --- | --- | --- |
+| `from_project` | `.agents/skills/<skill>/SKILL.md` | The skill is normal project surface and may also be visible to primary Codex. |
+| `from_main` | Existing user/global Codex skill roots | The member should reuse a skill already installed for the main user. |
+| `team` | `.cofounder/skills/<skill>/SKILL.md` | The skill should exist only for selected teammates. |
+
+When `skills.mode = "isolated"`, Cofounder launches the member with a member-specific `HOME` and `CODEX_HOME`, links selected skills into that runtime home, and disables unselected project skills for that member.
+
+## Memory
+
+Memory is explicit local text:
+
+```text
+.cofounder/memory/project.md
+.cofounder/memory/members/<member>.md
+```
+
+Keep durable project facts in project memory and role-specific notes in member memory.

package/docs/development.md

@@ -0,0 +1,19 @@
+# Development
+
+Local setup:
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+```
+
+Useful package commands:
+
+```bash
+npm create cofounder@latest -- --yes
+npx -y --package cofounder-crew -- cofounder start
+```
+
+The root package publishes the runtime CLI and MCP server. The `packages/create-cofounder` package publishes the `npm create cofounder` initializer.

package/docs/examples.md

@@ -0,0 +1,79 @@
+# Examples
+
+These examples are meant to be run from a project that already has Cofounder Crew initialized.
+
+## Add A Designer With Pencil MCP
+
+Use this when a specialist needs a tool that should not be exposed to the primary Codex session.
+
+```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
+```
+
+Then ask Codex:
+
+```text
+Use the Cofounder team. Ask designer to inspect the product flow and propose UI fixes.
+```
+
+## Reuse A Project Skill For One Member
+
+Project skills live in `.agents/skills/`. They can be visible to the primary Codex session and selectively assigned to members.
+
+```bash
+cofounder skill add api-workflow --scope project --assign backend
+```
+
+Then ask Codex:
+
+```text
+Ask backend to use the api-workflow skill while inspecting the API boundary.
+```
+
+## Reuse A Main Codex Skill
+
+Use this when a skill is already installed for your main Codex runtime and you want one member to inherit it.
+
+```bash
+cofounder skill assign uncodixfy designer --scope main
+```
+
+## Give A Member One Main MCP Server
+
+Use `--source main` when the MCP server already exists in the primary Codex config.
+
+```bash
+cofounder mcp assign github reviewer --source main
+```
+
+The reviewer gets only the selected server when its MCP mode is `isolated`.
+
+## Run A Worktree Task
+
+Worktree mode requires a Git repo with at least one commit.
+
+```bash
+cofounder task delegate backend "implement the smallest safe version of this change"
+cofounder task watch <task_id>
+cofounder task diff <task_id>
+cofounder task apply <task_id>
+```
+
+The daily path is still Codex chat:
+
+```text
+Delegate this implementation to backend in a worktree, then review the diff before applying it.
+```
+
+## Switch To Manual Project Context
+
+Automatic context derives worker instructions from `AGENTS.md`. Manual context uses `.cofounder/project.md`.
+
+```bash
+cofounder context mode manual
+cofounder context sync
+```
+
+Edit `.cofounder/project.md` when you want workers to see a curated project brief.

package/docs/faq.md

@@ -0,0 +1,89 @@
+# FAQ
+
+## Does Cofounder replace Codex?
+
+No. Codex remains the interface. Cofounder adds a local team runtime and MCP tools so Codex can delegate work to focused teammates.
+
+## Should I commit `.cofounder/`?
+
+Commit the team configuration that is part of the project:
+
+- `.cofounder/team.yaml`
+- member prompts and settings
+- project-owned MCP definitions that do not contain secrets
+- team-owned skills
+- curated memory if your team wants it shared and it contains no secrets
+
+Do not commit generated runtime state:
+
+- `.cofounder/runs/`
+- `.cofounder/worktrees/`
+- `.cofounder/members/*/home/`
+
+Cofounder creates `.cofounder/.gitignore` for those runtime folders.
+
+## Can different members have different MCP servers?
+
+Yes. In a member `settings.toml`:
+
+```toml
+[mcp]
+mode = "isolated"
+from_main = ["github"]
+team = ["pencil"]
+```
+
+`from_main` selects existing MCP servers from the primary Codex config. `team` selects project-owned MCP servers from `.cofounder/mcp/`.
+
+## Can different members have different skills?
+
+Yes. In a member `settings.toml`:
+
+```toml
+[skills]
+mode = "isolated"
+from_project = ["api-workflow"]
+from_main = ["uncodixfy"]
+team = ["design-review"]
+```
+
+Project skills live in `.agents/skills/`. Team-only skills live in `.cofounder/skills/`. Main skills are selected from the existing user/global Codex skill roots.
+
+## Why does Cofounder need an AGENTS.md bridge?
+
+The primary Codex session needs to know it should act as the Cofounder/orchestrator. The bridge points Codex to `.cofounder/codex-instructions.md` and tells it to delegate proactively when a teammate owns the work.
+
+In automatic context mode, Cofounder strips that orchestrator text before building worker context, so workers receive project rules without being told they are the orchestrator.
+
+## Why does worktree mode require one commit?
+
+Git worktrees are created from `HEAD`. A repo with no commits has no baseline for a delegated task to branch from.
+
+## Does updating npm update everyone automatically?
+
+The MCP entry usually runs:
+
+```bash
+npx -y --package cofounder-crew -- cofounder serve mcp
+```
+
+That means new Codex sessions resolve the MCP runtime from npm unless your environment has a cache. The global CLI is updated separately:
+
+```bash
+cofounder self update
+```
+
+Project-local pinning is optional. Add or update it with `cofounder pin` only when the repo should record a Cofounder package dependency.
+
+Restart Codex after changing MCP configuration.
+
+## Is live interrupt supported?
+
+Cofounder supports cancel-resume steering. Codex subprocesses do not currently expose true live stdin steering through this runtime.
+
+```json
+{
+  "live_interrupt": false,
+  "interrupt_mode": "cancel-resume"
+}
+```

package/docs/prompts/bootstrap-codex.md

@@ -0,0 +1,78 @@
+# Codex Bootstrap Prompt
+
+Copy this into Codex from the project directory where you want Cofounder Crew installed.
+
+```text
+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.
+```

package/docs/releasing.md

@@ -0,0 +1,23 @@
+# Releasing
+
+Publishing runs through GitHub Actions and npm Trusted Publishing.
+
+Trusted publisher setup is the same workflow for both npm packages:
+
+| Package | GitHub repository | Workflow |
+| --- | --- | --- |
+| `cofounder-crew` | `eugeneyvt/cofounder-crew` | `publish-npm.yml` |
+| `create-cofounder` | `eugeneyvt/cofounder-crew` | `publish-npm.yml` |
+
+Release flow:
+
+```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
+```
+
+Then publish the GitHub release for the `vX.Y.Z` tag. The workflow checks, builds, tests, and publishes both npm packages.

package/docs/runtime.md

@@ -0,0 +1,96 @@
+# Runtime
+
+Cofounder exposes the team to Codex through one MCP server. The primary Codex session coordinates tasks, while delegated members run as Codex subprocesses from the original project working directory.
+
+## MCP Tools
+
+| 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 and return current status, recent logs, and result metadata. |
+| `team.result` | Read the final result with explicit empty and 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. |
+
+## Task Files
+
+Each delegated task creates a run directory:
+
+```text
+.cofounder/runs/<task_id>/
+  task.json
+  prompt.md
+  events.jsonl
+  stdout.log
+  stderr.log
+  result.md
+```
+
+Worktree tasks can also produce an apply patch after completion.
+
+`team.wait` timing out means the task is still running, not failed. Always check `team.status`, `team.logs`, and `team.result` before claiming delegated work is done.
+
+An empty `result.md` means the delegated task did not return a usable final answer. Treat that as incomplete work, even if the subprocess ran commands.
+
+## Direct Mode
+
+```toml
+[write]
+mode = "direct"
+```
+
+The member runs in the main working tree. Use this for read-only analysis, reviews, or small trusted edits.
+
+## Worktree Mode
+
+```toml
+[write]
+mode = "worktree"
+```
+
+The member runs in `.cofounder/worktrees/<task_id>`. The primary Codex session can inspect the patch with:
+
+```bash
+cofounder task diff <task_id>
+```
+
+Apply it with:
+
+```bash
+cofounder task apply <task_id>
+```
+
+Worktree mode requires a Git repository with at least one commit.
+
+## Interruption
+
+Codex `exec` subprocesses do not currently support true live stdin steering. Cofounder uses cancel-resume:
+
+1. identify the running task
+2. cancel the process
+3. resume with revised instructions
+
+Runtime capabilities report this as:
+
+```json
+{
+  "live_interrupt": false,
+  "interrupt_mode": "cancel-resume"
+}
+```
+
+## Member Runtime
+
+When a member needs isolated MCP or skills, Cofounder prepares a member runtime home under:
+
+```text
+.cofounder/members/<member>/home/
+```
+
+This directory can contain generated Codex config, linked skills, and a symlink to the local Codex auth file. It is ignored by `.cofounder/.gitignore`.

package/docs/updating.md

@@ -0,0 +1,93 @@
+# Updating
+
+Updates should be conservative. Do not re-run init over an existing team, and do not overwrite member prompts, settings, memory, MCP config, or `AGENTS.md`.
+
+## Codex Prompt
+
+Paste this into Codex from the project you want to update:
+
+```text
+Update Cofounder Crew in this project.
+
+Inspect first:
+- whether command -v cofounder succeeds
+- whether npm ls -g cofounder-crew --depth=0 works
+- whether package.json contains cofounder-crew as an intentional project-local pin
+- whether Codex MCP server "cofounder" exists and points to: npx -y --package cofounder-crew -- cofounder serve mcp
+- whether .cofounder/team.yaml, member prompts/settings, memory, MCP config, project_context mode, and AGENTS.md exist
+- whether .cofounder/.gitignore ignores runs/, worktrees/, and members/*/home/
+
+Then update safely:
+- If the global cofounder command is missing, install it with npm install -g cofounder-crew@latest.
+- If cofounder-crew is pinned in package.json, report it and only update that pin when I explicitly ask.
+- If MCP is missing or wrong, repair it.
+- Do not re-run init over existing .cofounder/.
+- Do not add cofounder-crew to package.json during update.
+- Do not overwrite member prompts, settings, memory, MCP config, or AGENTS.md.
+- If runtime ignore entries are missing, report the recommended entries but do not add them automatically.
+- If project_context.mode is manual, ask before syncing .cofounder/project.md.
+- If MCP changed, tell me to restart Codex from this project directory.
+
+Summarize old versions, new versions, changed files, and manual follow-ups.
+```
+
+## Command
+
+Default flow:
+
+```bash
+cofounder update
+```
+
+Non-interactive:
+
+```bash
+cofounder update --yes
+```
+
+If the global command is not available, run the latest updater from npm:
+
+```bash
+npx -y --package cofounder-crew@latest -- cofounder update --yes
+```
+
+What it does:
+
+- repairs the Codex MCP entry by default
+- runs `cofounder doctor`
+- leaves `.cofounder/`, prompts, settings, memory, MCP files, `package.json`, and `AGENTS.md` untouched
+
+Skip MCP repair when you only want checks:
+
+```bash
+cofounder update --no-setup-codex
+```
+
+Update a globally installed `cofounder` command:
+
+```bash
+cofounder self update
+```
+
+Project-local pinning is optional and explicit:
+
+```bash
+cofounder pin
+```
+
+Check npm versions:
+
+```bash
+npm view cofounder-crew version
+npm view create-cofounder version
+npm ls -g cofounder-crew --depth=0
+npm ls cofounder-crew --depth=0 # only for pinned projects
+```
+
+Manual context refresh when using `project_context.mode = "manual"`:
+
+```bash
+cofounder context sync
+```
+
+Restart Codex after changing the MCP entry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofounder-crew",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Codex-backed local team runtime",
   "keywords": [
     "codex",
@@ -23,7 +23,8 @@
   "type": "module",
   "files": [
     "dist/src",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "exports": {
     ".": "./dist/src/runtime.js",