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.
- caokit/__init__.py +3 -0
- caokit/adapters.py +259 -0
- caokit/cli.py +704 -0
- caokit/company.py +115 -0
- caokit/config.py +191 -0
- caokit/data/adapters/antigravity.toml +35 -0
- caokit/data/adapters/claude.toml +38 -0
- caokit/data/adapters/codex.toml +33 -0
- caokit/data/roles/engineer.md +90 -0
- caokit/data/roles/general.md +177 -0
- caokit/data/roles/inspector.md +55 -0
- caokit/data/roles/scout.md +77 -0
- caokit/data/scaffold/company/BACKLOG.md +5 -0
- caokit/data/scaffold/company/COMPANY.md +28 -0
- caokit/data/scaffold/company/DECISIONS.md +5 -0
- caokit/data/scaffold/company/README.md +16 -0
- caokit/data/scaffold/company/TEAM.md +7 -0
- caokit/data/scaffold/company/contracts/ARTIFACT_CONTRACT.md +44 -0
- caokit/data/scaffold/company/contracts/COMMUNICATION_CONTRACT.md +38 -0
- caokit/data/scaffold/company/contracts/COMPANY_CONTRACT.md +42 -0
- caokit/data/scaffold/company/contracts/REVIEW_CONTRACT.md +36 -0
- caokit/data/scaffold/company/contracts/SAFETY_CONTRACT.md +40 -0
- caokit/data/scaffold/company/contracts/STATE_CONTRACT.md +31 -0
- caokit/data/scaffold/company/contracts/TASK_CONTRACT.md +26 -0
- caokit/data/scaffold/company/prompts/first-run.md +18 -0
- caokit/data/scaffold/company/tasks/TASK-0001-smoke-test.md +109 -0
- caokit/data/scaffold/company/tasks/TASK_TEMPLATE.md +73 -0
- caokit/doctor.py +287 -0
- caokit/gitignore.py +36 -0
- caokit/init_project.py +183 -0
- caokit/install.py +242 -0
- caokit/launch.py +102 -0
- caokit/project.py +359 -0
- caokit/render.py +129 -0
- caokit/reset.py +208 -0
- caokit/roster.py +95 -0
- caokit/schedule.py +104 -0
- caokit/stack.py +117 -0
- caokit/tasks.py +180 -0
- caokit/worktrees.py +107 -0
- caokit-0.3.0.dev0.dist-info/METADATA +382 -0
- caokit-0.3.0.dev0.dist-info/RECORD +46 -0
- caokit-0.3.0.dev0.dist-info/WHEEL +5 -0
- caokit-0.3.0.dev0.dist-info/entry_points.txt +2 -0
- caokit-0.3.0.dev0.dist-info/licenses/LICENSE +21 -0
- 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,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
|