caokit 0.3.0.dev0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. caokit/__init__.py +3 -0
  2. caokit/adapters.py +259 -0
  3. caokit/cli.py +704 -0
  4. caokit/company.py +115 -0
  5. caokit/config.py +191 -0
  6. caokit/data/adapters/antigravity.toml +35 -0
  7. caokit/data/adapters/claude.toml +38 -0
  8. caokit/data/adapters/codex.toml +33 -0
  9. caokit/data/roles/engineer.md +90 -0
  10. caokit/data/roles/general.md +177 -0
  11. caokit/data/roles/inspector.md +55 -0
  12. caokit/data/roles/scout.md +77 -0
  13. caokit/data/scaffold/company/BACKLOG.md +5 -0
  14. caokit/data/scaffold/company/COMPANY.md +28 -0
  15. caokit/data/scaffold/company/DECISIONS.md +5 -0
  16. caokit/data/scaffold/company/README.md +16 -0
  17. caokit/data/scaffold/company/TEAM.md +7 -0
  18. caokit/data/scaffold/company/contracts/ARTIFACT_CONTRACT.md +44 -0
  19. caokit/data/scaffold/company/contracts/COMMUNICATION_CONTRACT.md +38 -0
  20. caokit/data/scaffold/company/contracts/COMPANY_CONTRACT.md +42 -0
  21. caokit/data/scaffold/company/contracts/REVIEW_CONTRACT.md +36 -0
  22. caokit/data/scaffold/company/contracts/SAFETY_CONTRACT.md +40 -0
  23. caokit/data/scaffold/company/contracts/STATE_CONTRACT.md +31 -0
  24. caokit/data/scaffold/company/contracts/TASK_CONTRACT.md +26 -0
  25. caokit/data/scaffold/company/prompts/first-run.md +18 -0
  26. caokit/data/scaffold/company/tasks/TASK-0001-smoke-test.md +109 -0
  27. caokit/data/scaffold/company/tasks/TASK_TEMPLATE.md +73 -0
  28. caokit/doctor.py +287 -0
  29. caokit/gitignore.py +36 -0
  30. caokit/init_project.py +183 -0
  31. caokit/install.py +242 -0
  32. caokit/launch.py +102 -0
  33. caokit/project.py +359 -0
  34. caokit/render.py +129 -0
  35. caokit/reset.py +208 -0
  36. caokit/roster.py +95 -0
  37. caokit/schedule.py +104 -0
  38. caokit/stack.py +117 -0
  39. caokit/tasks.py +180 -0
  40. caokit/worktrees.py +107 -0
  41. caokit-0.3.0.dev0.dist-info/METADATA +382 -0
  42. caokit-0.3.0.dev0.dist-info/RECORD +46 -0
  43. caokit-0.3.0.dev0.dist-info/WHEEL +5 -0
  44. caokit-0.3.0.dev0.dist-info/entry_points.txt +2 -0
  45. caokit-0.3.0.dev0.dist-info/licenses/LICENSE +21 -0
  46. caokit-0.3.0.dev0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,382 @@
1
+ Metadata-Version: 2.4
2
+ Name: caokit
3
+ Version: 0.3.0.dev0
4
+ Summary: Chain-of-command agent company kit for CAO (cli-agent-orchestrator)
5
+ Author: Armando Zubillaga
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/ajzpiv97/cao-kit
8
+ Project-URL: Repository, https://github.com/ajzpiv97/cao-kit
9
+ Project-URL: Changelog, https://github.com/ajzpiv97/cao-kit/blob/main/CHANGELOG.md
10
+ Project-URL: Issues, https://github.com/ajzpiv97/cao-kit/issues
11
+ Keywords: ai-agents,multi-agent,agent-orchestration,claude-code,coding-agents,cli,tmux
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development
21
+ Requires-Python: >=3.11
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Dynamic: license-file
25
+
26
+ <p align="center">
27
+ <img src="https://raw.githubusercontent.com/ajzpiv97/cao-kit/main/docs/logo.svg" width="140" height="140" alt="caokit logo: a general's star above three double-chevron units"/>
28
+ </p>
29
+
30
+ <h1 align="center">caokit</h1>
31
+
32
+ <p align="center">
33
+ <b>Command a swarm of coding agents from one terminal.</b>
34
+ </p>
35
+
36
+ <p align="center">
37
+ <a href="https://github.com/ajzpiv97/cao-kit/actions/workflows/ci.yml"><img src="https://github.com/ajzpiv97/cao-kit/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"/></a>
38
+ <a href="https://github.com/ajzpiv97/cao-kit/tags"><img src="https://img.shields.io/github/v/tag/ajzpiv97/cao-kit?label=version&color=blue" alt="Version"/></a>
39
+ <a href="https://github.com/ajzpiv97/cao-kit/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue" alt="License: MIT"/></a>
40
+ <a href="https://github.com/ajzpiv97/cao-kit/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python 3.11+"/></a>
41
+ <img src="https://img.shields.io/badge/Platform-macOS-lightgrey?logo=apple" alt="Platform: macOS"/>
42
+ <a href="https://github.com/awslabs/cli-agent-orchestrator"><img src="https://img.shields.io/badge/CAO-2.5.4-FF9900" alt="CAO 2.5.4"/></a>
43
+ </p>
44
+
45
+ You talk to **one** commanding agent, the *General* (Claude Code by default). It drafts task files,
46
+ waits for your approval, then delegates to specialist coding-agent CLIs through
47
+ [CAO](https://github.com/awslabs/cli-agent-orchestrator) (`cli-agent-orchestrator`).
48
+
49
+ - **One agent to talk to.** The General takes the goal, writes the task file, dispatches an engineer,
50
+ a scout and an inspector, and reports back. You approve plans and accept results.
51
+ - **Review comes from a different vendor.** Claude implements and Antigravity inspects Claude's code,
52
+ re-running the task's validation commands itself. caokit refuses a roster where author and reviewer
53
+ share a provider unless you opt in.
54
+ - **Your subscriptions, your machine.** It drives the CLIs you already pay for, holds no credentials,
55
+ and no agent may merge, push or deploy. The human commits.
56
+
57
+ **Get started.** Needs macOS, `tmux`, `uv`, CAO 2.5.4, `claude` and `agy` ([full install](#install)):
58
+
59
+ ```bash
60
+ uv tool install git+https://github.com/ajzpiv97/cao-kit
61
+ caokit doctor # checks CLIs, auth, CAO version and the server
62
+ caokit company create # pick a tool and model per role
63
+ caokit install # install the profiles into CAO
64
+ caokit init /path/to/repo # scaffold .company/ in your project
65
+ caokit server # terminal A: leave running
66
+ caokit launch /path/to/repo # terminal B: talk to the General
67
+ ```
68
+
69
+ The kit is generic: it assumes no particular project, language or stack. A project brings its
70
+ own validation commands (test/CI command) and its own rules.
71
+
72
+ - **Platform:** macOS (Apple Silicon tested), tmux backend.
73
+ - **CAO:** exactly **2.5.4**, installed with `uv tool`.
74
+ - **Status:** validated end to end with a Claude + Antigravity roster (see [Validation](#validation)).
75
+
76
+ **Contents:** [Install](#install) · [Quick start](#quick-start) · [Roles](#roles) ·
77
+ [Task workflow](#task-workflow) · [Working with the General](#working-with-the-general) ·
78
+ [Commands](#commands) · [Configuration](#configuration) · [Worktrees](#worktrees-one-per-task) ·
79
+ [Safety model](#safety-model) · [Validation](#validation) · [Developing caokit](#developing-caokit)
80
+
81
+ ---
82
+
83
+ ## Install
84
+
85
+ You need `git`, `tmux`, `uv`, `python3` (3.11+), CAO (`cao`, `cao-server`, `cao-mcp-server`),
86
+ `claude` and `agy`.
87
+
88
+ ```bash
89
+ brew install tmux uv
90
+ uv tool install 'cli-agent-orchestrator==2.5.4'
91
+ curl -fsSL https://claude.ai/install.sh | bash
92
+ curl -fsSL https://antigravity.google/cli/install.sh | bash
93
+ uv tool install git+https://github.com/ajzpiv97/cao-kit # or, from a checkout: uv tool install --from . caokit
94
+ caokit doctor # CLIs, auth, CAO version, single CAO install, server, roster
95
+ ```
96
+
97
+ - Log in to `claude` and `agy` **directly, outside CAO**, once (send one harmless prompt each), so
98
+ no login screen appears inside an orchestrated terminal. `agy models` lists the exact model IDs.
99
+ - Change the CAO version only with `uv tool install --force 'cli-agent-orchestrator==X'`, never
100
+ `uv tool upgrade` or `cao update`.
101
+ - After pulling new changes to a checkout, reinstall with `uv tool install --force --from . caokit`.
102
+
103
+ ## Quick start
104
+
105
+ ```bash
106
+ caokit company create --general claude:sonnet --engineer claude:opus \
107
+ --scout antigravity:gemini-3.8-flash-medium --inspector antigravity:gemini-4-argon-high
108
+ caokit install # render and install the profiles into CAO
109
+ caokit init /path/to/repo # scaffold .company/, ROSTER.md, merge .gitignore
110
+ caokit server # terminal A: start cao-server (leave running)
111
+ caokit launch /path/to/repo # terminal B: start the General in this project
112
+ ```
113
+
114
+ `caokit company create` with no role flags asks for a tool and model per role and offers the
115
+ recommended one.
116
+
117
+ For a hands-off smoke test instead of talking to the General, launch the scaffolded TASK-0001:
118
+
119
+ ```bash
120
+ caokit launch /path/to/repo --headless --auto-approve --prompt-file /path/to/repo/.company/prompts/first-run.md
121
+ caokit status /path/to/repo # watch the workers
122
+ ```
123
+
124
+ Expect artifacts under `.company/` (`artifacts/`, `research/`, `reviews/`, `decisions/`) and no
125
+ application-source changes.
126
+
127
+ ## Roles
128
+
129
+ | Role | Default tool | Job | Tool limits |
130
+ |---|---|---|---|
131
+ | `general` | Claude Code, `permissionMode: auto` | Single entry point: task intake, dispatch, acceptance procedure, synthesis | Native: no Bash, Agent/Task, Monitor, web. Read, list and write plus `cao-mcp-server` |
132
+ | `engineer` | Claude Code | Implements; runs **only** the task's authorised validation commands | Web blocked. `execute_bash` also unlocks Claude's Agent/Task tools, so "no subagents" is instruction-only |
133
+ | `scout` | Antigravity (`gemini-3.8-flash-medium`) | Research; does not build | Advisory only |
134
+ | `inspector` | Antigravity (`gemini-4-argon-high`) | Independent review; re-runs the authorised commands | Advisory only |
135
+
136
+ Why this split: **Claude implements, Antigravity inspects Claude's code.** Claude's tool limits are
137
+ enforced natively by CAO. Antigravity's are **advisory**: CAO launches it with
138
+ `--dangerously-skip-permissions`, so review must come from a different tool and model vendor than
139
+ the author.
140
+
141
+ Any role can be bound to any active tool (`caokit company create`). A soft-enforcement tool as
142
+ `engineer` or `general` needs an explicit opt-in (see [Policy](#policy)) because nothing then stops
143
+ it writing anywhere. Codex is parked (see [Parked: Codex](#parked-codex)).
144
+
145
+ Keep `fs_write` in the General's profile. CAO's validator warns that it is "not recognised", but
146
+ that is a gap in its own vocabulary check, and removing it would block the General's `.company/`
147
+ writes.
148
+
149
+ ## Task workflow
150
+
151
+ 1. **Intake.** You state the goal. The General writes `.company/tasks/TASK-NNNN-<slug>.md` from the
152
+ template, then takes one of two paths:
153
+ - **Fast path**, for a clear task that needs at most two agents and meets no plan-path trigger:
154
+ the General records `APPROVED` under the pre-authorised rule and dispatches without stopping.
155
+ You review the output afterwards.
156
+ - **Plan path**, for anything else: `State: PROPOSED`, a Team plan with a per-agent cost
157
+ estimate, draft acceptance checks marked "human must confirm", then the General **stops** for
158
+ your approval. Triggers are auth or secrets, data deletion or migration, new dependencies,
159
+ anything external, ambiguity, or more than two agents. In Claude Code's plan mode approval is
160
+ always forced.
161
+ 2. **Approval.** Only your explicit approval moves a plan-path task to `APPROVED`, logged in
162
+ `DECISIONS.md`. You own the acceptance checks and the allowed-path review.
163
+ 3. **Clarification.** Workers ask the General with `send_message`; the General answers from the task
164
+ file and repository if it can, and otherwise asks you. It does not guess.
165
+ 4. **Authorised validation commands.** The engineer and inspector run exactly the commands the task
166
+ lists and nothing else (no `rm`/cleanup, installs, network, or state-changing git). Both write a
167
+ **Commands run** section with real output. The inspector re-runs the commands itself.
168
+ 5. **Acceptance procedure.** The General diffs every reported command against the allowlist and flags
169
+ extras as a **contract breach**. It never accepts silently.
170
+ 6. **Accept.** Only your "accept" moves a task to `ACCEPTED`. Then run `caokit tasks archive`.
171
+
172
+ Task files are the audit trail. Contracts live in `.company/contracts/` and are tracked by git; the
173
+ rest of `.company/` is git-ignored.
174
+
175
+ ## Working with the General
176
+
177
+ - `caokit launch` **without** `--headless` attaches you to the General's Claude Code inside tmux.
178
+ Workers are other tmux windows: `Ctrl-b w` lists them, `Ctrl-b d` detaches (the session keeps running).
179
+ - Web UI with live terminals: `http://127.0.0.1:9889/` (root path only). `cao tui` also exists.
180
+ - **Don't type into the General while it is mid-turn.** Worker reports queue and are delivered when it
181
+ is idle. For check-ins use `caokit send "<msg>"`.
182
+ - Session names get a `cao-` prefix (project `proja` becomes `cao-proja`).
183
+ - Never use `cao launch --yolo` and never `allowedTools: ["*"]`: both bypass restrictions.
184
+
185
+ ## Commands
186
+
187
+ Destructive commands (`uninstall`, `tasks prune`, `reset`) are dry runs unless you pass `--yes`.
188
+
189
+ **Setup**
190
+
191
+ | Command | Purpose |
192
+ |---|---|
193
+ | `caokit doctor` | Check CLIs, auth, CAO version, a single CAO install (uv tool only), the server and its web UI, and the roster |
194
+ | `caokit company create [--general\|--engineer\|--scout\|--inspector TOOL[:MODEL]] [--force]` | Write `caokit.toml` (role to tool and model), with every guardrail checked; `--force` overwrites an existing file |
195
+ | `caokit install [--project REPO]` | Render, validate, install and byte-verify profiles; `--replace-legacy` / `--remove-legacy` for old copies |
196
+ | `caokit uninstall [--project REPO] [--yes]` | Remove a roster's profiles from CAO. Leftover `agent-context` copies are moved to a backup, not deleted |
197
+ | `caokit init REPO [--name P] [--override ROLE=TOOL[:MODEL]] [--force-project]` | Scaffold `.company/` in a git repo; `--name` namespaces its profiles; `--force-project` overwrites an existing project file |
198
+ | `caokit reset [--yes]` | Back up CAO's state, reinstall CAO 2.5.4 and the profiles |
199
+
200
+ **Running a session**
201
+
202
+ | Command | Purpose |
203
+ |---|---|
204
+ | `caokit server` | Run `cao-server` (tmux backend) in the foreground |
205
+ | `caokit launch [REPO]` | Start the project's General; `--prompt-file F`, `--headless`, `--auto-approve`, `--async` |
206
+ | `caokit status [REPO]` | Show sessions and workers |
207
+ | `caokit send MESSAGE [--repo REPO] [--timeout S]` | Message the General (waits up to 600 s by default) |
208
+ | `caokit stop [REPO]` | Shut the session down |
209
+
210
+ **Tasks and worktrees**
211
+
212
+ | Command | Purpose |
213
+ |---|---|
214
+ | `caokit tasks [list] [REPO]` | Open tasks and what blocks them (`--all` includes finished ones) |
215
+ | `caokit tasks archive [REPO] [--delete]` | Move `ACCEPTED`, `CANCELLED` and `FAILED` tasks to `.company/tasks/archive/`; `--delete` removes them instead |
216
+ | `caokit tasks policy [REPO] [--keep-archived-days N] [--worktrees on\|off]` | Set how long a project keeps archived tasks, and whether each task gets its own worktree |
217
+ | `caokit tasks prune [REPO] [--days N] [--yes]` | Delete archived tasks older than the policy |
218
+ | `caokit tasks schedule [REPO] [--install\|--remove] [--at HH:MM]` | Print, add or remove the daily cron entry that archives and prunes |
219
+ | `caokit worktrees [REPO]` | List the `cao/*` task branches and checkouts, with unmerged commits |
220
+
221
+ ## Configuration
222
+
223
+ Config lives in `~/.config/caokit/caokit.toml` (`$CAOKIT_HOME` or `--config` to override). Roles are
224
+ tool-agnostic; concrete CAO profiles are named `<role>-<tool>` (CAO allows only `[A-Za-z0-9_-]`).
225
+
226
+ ### Per-project setups
227
+
228
+ CAO's profile store is machine-global (profiles are not looked up in a project directory), so two
229
+ projects sharing `engineer-claude` would overwrite each other's model. Give a project its own
230
+ namespaced profiles:
231
+
232
+ ```bash
233
+ caokit init ~/proj-a --name proja # same roster as the user-level config
234
+ caokit init ~/proj-b --name projb --override engineer=:sonnet --override scout=claude:haiku
235
+ caokit install --project ~/proj-a # installs proja_general-claude, proja_engineer-claude, ...
236
+ caokit install --project ~/proj-b
237
+ caokit launch ~/proj-a # session cao-proja
238
+ ```
239
+
240
+ - Two layers: the user-level `caokit.toml`, then the project's `.company/caokit.toml` (git-ignored) with a
241
+ `[project] name`, optional `[policy]`, `[tasks]`, and per-role `tool`/`model` overrides.
242
+ - Override forms: `role=tool`, `role=tool:model`, `role=:model` (keep the tool). Changing a role's tool
243
+ without a model drops the user-level model (a model ID from one tool means nothing to another).
244
+ - Names are `<project>_<role>-<tool>`; the project is 1-24 lowercase letters, digits or `-`.
245
+ - All guardrails (cross-provider inspection, soft-tool opt-ins, model validation) re-run on the merged config.
246
+ - Without `--name`, `init` uses shared `<role>-<tool>` profiles, and the session is named after the directory.
247
+ - Each project is its own CAO session; one `cao-server` serves them all.
248
+ - Remove a project's profiles with `caokit uninstall --project ~/proj-a --yes` (it touches only that project's names).
249
+
250
+ ### Policy
251
+
252
+ | Setting | Where | Effect |
253
+ |---|---|---|
254
+ | `allow_soft_engineer` | `[policy]` / `--allow-soft-engineer` | Lets a soft-enforcement tool (Antigravity) be the engineer |
255
+ | `allow_soft_general` | `[policy]` / `--allow-soft-general` | Lets a soft-enforcement tool be the General. CAO cannot deny its tools, so it could write anywhere and run commands. Prompt rules are all that hold it back |
256
+ | `allow_single_provider` | `[policy]` / `--allow-single-provider` | Downgrades the cross-provider inspection rule to a warning |
257
+ | `keep_archived_days` | project `[tasks]` | `tasks prune` deletes archived tasks older than this; unset keeps them forever |
258
+
259
+ ### Keeping and pruning finished tasks
260
+
261
+ `caokit tasks archive` moves finished tasks out of the active folder and stamps the archive date.
262
+ Archived tasks are kept until the project's policy says otherwise:
263
+
264
+ ```bash
265
+ caokit tasks policy ~/proj-a --keep-archived-days 90 # per project, stored in .company/caokit.toml
266
+ caokit tasks prune ~/proj-a # dry run: lists archived tasks older than 90 days
267
+ caokit tasks prune ~/proj-a --yes # deletes them
268
+ caokit tasks schedule ~/proj-a # prints the daily cron line
269
+ caokit tasks schedule ~/proj-a --install --at 03:17 # adds it to your crontab (only its own line)
270
+ ```
271
+
272
+ Scheduling uses cron. `--install` refuses until a retention policy exists, replaces only the line
273
+ for that project, and `--remove` takes it out again. cron runs with a minimal environment, so the line
274
+ uses the absolute path to `caokit`. On macOS cron may need Full Disk Access to read your project folder.
275
+
276
+ ## Worktrees: one per task
277
+
278
+ ```bash
279
+ caokit tasks policy /path/to/repo --worktrees on # needs a git repo root with a commit
280
+ caokit install # reinstall profiles so the roles carry the rules
281
+ caokit worktrees /path/to/repo # list the task branches CAO left behind
282
+ ```
283
+
284
+ With it on, the General dispatches each source-changing engineer through CAO's `use_worktree`: a private checkout at
285
+ `<repo>/.cao/worktrees/<terminal-id>` on branch `cao/<terminal-id>`, cut from HEAD. What to know:
286
+
287
+ - The engineer **commits on its own branch** (the only git write any worker may do, and only there). CAO deletes the
288
+ checkout, with anything uncommitted, when the terminal is deleted; a committed branch survives.
289
+ - The General keeps the engineer's terminal until the task is accepted or cancelled, and sends rework to the same
290
+ terminal, so one task is one worktree.
291
+ - The inspector reviews and re-runs the validation commands inside that checkout (`cd <worktree> && ...`).
292
+ - **You merge**: `git merge cao/<id>`, then `git branch -d cao/<id>`. caokit never merges or deletes branches.
293
+ - A new worktree starts from the last commit, so uncommitted changes in your main checkout are not in it.
294
+ - `.company/` is git-ignored, so agents read and write it at the project root, not in the checkout.
295
+ - **Git-ignored files are not in the checkout** (`node_modules`, `.venv`, `.env`, build caches), and CAO deletes them
296
+ with it. Have the task's authorised commands start with your install step (`npm ci`, `pnpm install --frozen-lockfile`,
297
+ `uv sync`); pnpm and uv share a global store, so that is cheap. Do not symlink the main `node_modules` in: parallel
298
+ engineers would write into one shared tree. CAO has no setup hook, so caokit does not run the install for you yet.
299
+
300
+ ## Safety model
301
+
302
+ - Claude roles: CAO deny-lists (native) plus `permissionMode: auto`.
303
+ - Antigravity: restrictions are **advisory**; treat its profile as guidance, not a boundary.
304
+ - No path-level enforcement: any agent with write access can write anywhere in the repo. Turn on
305
+ [worktrees](#worktrees-one-per-task) so each writing task gets its own git worktree, and inspect
306
+ `git diff` afterwards.
307
+ - No role may deploy, merge, push, contact third parties, use production credentials, change billing,
308
+ or run destructive git. The human commits.
309
+ - Human approval is required for plan-path tasks, acceptance, merges, pushes, deployments, secrets,
310
+ dependency changes and destructive actions.
311
+ - The kit holds no credentials by design.
312
+
313
+ ## Validation
314
+
315
+ Last run on the `caokit` path: PASS with 13 checks passing and 1 manual (read the synthesis). About
316
+ 122k fresh Claude tokens (input, output and cache writes), plus about 1.0M cache reads. Antigravity
317
+ leaves no token data, so its share is not counted.
318
+
319
+ The proof harness is `scripts/95-validate-e2e.sh`. It builds a throwaway repo (`taskly` sample app)
320
+ under `validation/`, runs `caokit init --name e2e` and `caokit install --project`, launches TASK-0001
321
+ with `caokit launch`, polls the CAO API, collects evidence and writes `evidence/ACCEPTANCE.md` with a
322
+ PASS/FAIL verdict and `evidence/token-usage.md`. Knobs:
323
+ `TIMEOUT_MIN=60 POLL_SEC=15 AUTO_NUDGE=1 STALL_MIN=10 KEEP_SESSION=0 FORCE_REPLACE=0 SKIP_AGY_MODELS=0`.
324
+ It needs Python 3.11+. `validation/` is local run evidence and is not committed.
325
+
326
+ ## Developing caokit
327
+
328
+ ```bash
329
+ export PYTHONPATH=src
330
+ uvx ruff check src tests && uvx ruff format --check src tests # lint + format (Google docstrings enforced)
331
+ uvx mypy # strict types for src, lenient for tests
332
+ python3 -B -m unittest discover -s tests -t . # unit tests (a real-cao test runs if `cao` is installed)
333
+ ```
334
+
335
+ CI (`.github/workflows/ci.yml`) runs the same four checks on macOS with Python 3.11 and 3.13 for
336
+ every push to `main` and every pull request.
337
+
338
+ Ruff and mypy both target Python 3.11, the minimum (`requires-python = ">=3.11"`); caokit has no
339
+ runtime dependencies. `uv tool install` fetches a suitable interpreter, so the system Python does
340
+ not matter.
341
+
342
+ ### Releasing
343
+
344
+ Versions follow PEP 440 and are bumped with [`bump-my-version`](https://github.com/callowayproject/bump-my-version),
345
+ which rewrites the version in `pyproject.toml` and `src/caokit/__init__.py`, commits and tags `vX.Y.Z`:
346
+
347
+ ```bash
348
+ uvx bump-my-version show-bump # preview what each bump would produce
349
+ uvx bump-my-version bump minor # 0.2.2 -> 0.3.0.dev0 (start a new version)
350
+ uvx bump-my-version bump pre_n # 0.3.0.dev0 -> 0.3.0.dev1
351
+ uvx bump-my-version bump pre_l # 0.3.0.dev1 -> 0.3.0.rc0, and again -> 0.3.0
352
+ git push origin main --follow-tags
353
+ gh release create vX.Y.Z --notes "..." # add --prerelease for dev and rc versions
354
+ ```
355
+
356
+ Publishing the GitHub release runs `.github/workflows/release.yml`, which checks the tag against the
357
+ package version, builds, and uploads to PyPI. Update `CHANGELOG.md` before bumping.
358
+
359
+ `scripts/95-validate-e2e.sh` (the harness above) and `scripts/token_usage.py` (Claude token use per
360
+ session) are development tools for this repo, not part of the installed CLI.
361
+
362
+ ## Parked: Codex
363
+
364
+ Codex was removed after every CAO failure turned out to be Codex-specific (MCP approval denied,
365
+ inherited `xhigh` reasoning, config drift). Its adapter is kept as metadata only and cannot be
366
+ selected. If Codex returns, the `send_message` callback needs:
367
+
368
+ ```yaml
369
+ codexConfig:
370
+ mcp_servers.cao-mcp-server.tools.send_message.approval_mode: "approve"
371
+ ```
372
+
373
+ and an explicit `model_reasoning_effort`. Codex 0.134+ reads `~/.codex/NAME.config.toml` files.
374
+ The old Codex profile files are in git history.
375
+
376
+ ## More
377
+
378
+ [`TROUBLESHOOTING.md`](https://github.com/ajzpiv97/cao-kit/blob/main/TROUBLESHOOTING.md), [`SOURCES.md`](https://github.com/ajzpiv97/cao-kit/blob/main/SOURCES.md), [`CHANGELOG.md`](https://github.com/ajzpiv97/cao-kit/blob/main/CHANGELOG.md).
379
+
380
+ ## License
381
+
382
+ MIT, see [`LICENSE`](https://github.com/ajzpiv97/cao-kit/blob/main/LICENSE).
@@ -0,0 +1,46 @@
1
+ caokit/__init__.py,sha256=FgUgXPGa5BzOTDn7Uo_9BdSYCwC_sI7DbbOJoTMSASk,86
2
+ caokit/adapters.py,sha256=U0k5FR-Njogrl3Rt8nVlW9lWKa2JK1Ip71rmn6D1z3A,9883
3
+ caokit/cli.py,sha256=LATXhIMVXtA8QaF3WOOIGn9tfuoOjZ3IMee4BKmlEB8,26680
4
+ caokit/company.py,sha256=fWMfdxMHzYNZQp9KUaRUNPDTnNXqR3gL0WEfchNfjmY,4327
5
+ caokit/config.py,sha256=15FLl0TfvAogQRoxzyMJGxiEHtUaO0q7GZK3CY9DqDI,6769
6
+ caokit/doctor.py,sha256=w9D5uBDpCuoQV_tLj_HLyoNDT0pjnGcfkhH_PnrEVFQ,9952
7
+ caokit/gitignore.py,sha256=aLoGrgEU5ePctn18hcDJYcnwHFA6bKEkFB-IdFwZs1w,1468
8
+ caokit/init_project.py,sha256=t-sV7G9Sa4KaNcM212j1oCQAU0c00BPU-jMU1GQlc3w,7337
9
+ caokit/install.py,sha256=rbs1ebwNp48HTNgs__YayVude1sSikXk9GifrUUdB9Q,9132
10
+ caokit/launch.py,sha256=x3-GcqEjYu6nN44EK5KMv8j0-lEzUTVuYozH43AB-WA,3955
11
+ caokit/project.py,sha256=j6Asx4YbUHcp9OzVgjvXDR3DTZJRZx9wkwDVSL40zQM,12822
12
+ caokit/render.py,sha256=Rikr9X0bg1sX8v0167Ha9otyUA2I-bJrwta7JmvEcYo,4640
13
+ caokit/reset.py,sha256=yCYYAABgc7XFfp8x90K6B8EHcTvj76BancyMKuYMC0M,7685
14
+ caokit/roster.py,sha256=0dUTpleln9RERZBXEe6jNH852p2kWqI_qDYHHFlV3sI,3975
15
+ caokit/schedule.py,sha256=CnmfmR5b3ARdmazW0d_gXiTwm_mz0Kho9xcbCPk48hQ,3510
16
+ caokit/stack.py,sha256=jBgRHI0AMoYRRun7DMgjrBGrM18DMw_pgIzOGTzfM1s,4346
17
+ caokit/tasks.py,sha256=NyiKWQzKhanJZTRUuQxMqbqVfg06RNGOfDHuBeutKJs,5814
18
+ caokit/worktrees.py,sha256=tGW5cZKDeftIcIC6msbSgZmHRGh_9x1Y2zKTBAAtp1Q,4181
19
+ caokit/data/adapters/antigravity.toml,sha256=7vMSRprpztBaraJPOxx2_COVHZXs6xe306zx1z_wDsA,1055
20
+ caokit/data/adapters/claude.toml,sha256=WAaBIMLJN6yZZUpdwytQipFeZY4aTsIY2lh-sBesfjM,763
21
+ caokit/data/adapters/codex.toml,sha256=pgxFRQKBRjBbNS4a04NUnn359A0qYZSr5U3e0gRzN3M,527
22
+ caokit/data/roles/engineer.md,sha256=cWh7ufcGXNALzOn2uRgAM-LwvHBAn_vj9T4XjRGjFwA,4056
23
+ caokit/data/roles/general.md,sha256=mzdh0dVmN7LB7H_YZuq4qBZkULEro_KIJWa4YJT1CjY,15082
24
+ caokit/data/roles/inspector.md,sha256=3dkBR4U_T2eHBuHjsFw9_Di9fKBixcvSwUiXYtrdzP0,3362
25
+ caokit/data/roles/scout.md,sha256=ttwGTKyAUK_Pb83DIFDMFp3iw9DqHi2cubsIg361FFo,2197
26
+ caokit/data/scaffold/company/BACKLOG.md,sha256=uRn68jIxo7bZkusiLP0ZF-kWbi0v5esyL84k6tAuQEQ,188
27
+ caokit/data/scaffold/company/COMPANY.md,sha256=Nv1nz16cog9NvOzeHkbp_QyjMbdxc_ll-3SP_5qXywE,1221
28
+ caokit/data/scaffold/company/DECISIONS.md,sha256=gpEyOiWEdIDiWCLIBg1HYDR0XNpDRlkpb8_0A3eBwbs,204
29
+ caokit/data/scaffold/company/README.md,sha256=P5uDDIGuVAeuRXkylDlR-Pks8i6KnWlEkassNkQCBTQ,512
30
+ caokit/data/scaffold/company/TEAM.md,sha256=qXrUswdPUsYZUw7lei_2yRJEIiP7YioimmR0RCWKX9o,272
31
+ caokit/data/scaffold/company/contracts/ARTIFACT_CONTRACT.md,sha256=U8tMhDG2iOdhmSlYewOBBRmNIzg9qd5-zJTG7O39PIo,895
32
+ caokit/data/scaffold/company/contracts/COMMUNICATION_CONTRACT.md,sha256=xz04cwCmkOiTxlpX5q1f9UbCVDXUBZOsMq_qwUJLuL0,1243
33
+ caokit/data/scaffold/company/contracts/COMPANY_CONTRACT.md,sha256=pg8023YkZWpHXfl5UB5EV0hl4YXuiijginP5fuHTn4w,1472
34
+ caokit/data/scaffold/company/contracts/REVIEW_CONTRACT.md,sha256=XBEM2_65C1ARv6dIV6mwC7McBuMKj-a7kN3pJD2jG0w,993
35
+ caokit/data/scaffold/company/contracts/SAFETY_CONTRACT.md,sha256=Y6H5lAb00KdRUPZNfCbgR2QNPDn0Ms_VeSnsJqMEH98,1850
36
+ caokit/data/scaffold/company/contracts/STATE_CONTRACT.md,sha256=SHKk_Gh_VUVeX3TZp46I7hvaa7eex-RPq_CdwzFpWA0,1172
37
+ caokit/data/scaffold/company/contracts/TASK_CONTRACT.md,sha256=aemZwi4itGP7k1BNWHk7a23WXRekVAhvhq3iRh7NUbU,1361
38
+ caokit/data/scaffold/company/prompts/first-run.md,sha256=9dUz2GJFFzIbX5VW8KJRgsZHq0IY3-l4JSiGoGWL-H4,1718
39
+ caokit/data/scaffold/company/tasks/TASK-0001-smoke-test.md,sha256=fXkwJ8Mnfv_JgWDG7gSreWCpbaYeb7Jub7gCzPaKBBg,3369
40
+ caokit/data/scaffold/company/tasks/TASK_TEMPLATE.md,sha256=-uRwKub_O0cWJL_KjziMMfOSrLuae1G0sAtsXytK8AU,2378
41
+ caokit-0.3.0.dev0.dist-info/licenses/LICENSE,sha256=bs1ZmsX4vV7FiTIVbuGYtiQWBslJLs7pNch_OdQjUH0,1074
42
+ caokit-0.3.0.dev0.dist-info/METADATA,sha256=hwPOqBeHmYqRpddp1qTvdqDrjqbI-hL9lwpx4nJEb1s,22355
43
+ caokit-0.3.0.dev0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
44
+ caokit-0.3.0.dev0.dist-info/entry_points.txt,sha256=5WhsDx9lAeNgP3L7gnifxJVUeO6EYIdPSVpa_BKiAqs,43
45
+ caokit-0.3.0.dev0.dist-info/top_level.txt,sha256=_FZta-3NDKTb2TjR2cnlTYIm7kZkDIJZmxtXXsfaW-Y,7
46
+ caokit-0.3.0.dev0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ caokit = caokit.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Armando Zubillaga
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ caokit