oacp-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{oacp_cli-0.2.0 → oacp_cli-0.2.2}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-04-17
+
+### Added
+
+- `oacp watch` — monitor-friendly inbox/outbox watcher with structured output and partial-progress preservation on errors
+
+### Changed
+
+- Docs: refreshed cross-runtime capability matrix and public-skill parity framing
+
+## [0.2.1] - 2026-03-22
+
+### Fixed
+
+- `oacp doctor` no longer fails when `gh` CLI is not installed — `gh` is now optional (#78)
+- `oacp send` relaxed handoff body schema validation to accept freeform content (#78)
+- `oacp write-event --related` now handles JSON arrays correctly (#76)
+
+### Changed
+
+- README: refreshed command table with all v0.2.0 CLI commands, updated workspace layout diagram (#75, #77, #84)
+- SPEC.md: synced with v0.2.0 — version header, org-memory section, kernel inventory with exposure column (#85)
+- Onboarding docs: setup.md uses `pip install` as primary install, QUICKSTART.md adds `--agents`/`--repo` flags, CHANGELOG.md fixes `oacp memory archive` command name (#86)
+
 ## [0.2.0] - 2026-03-20
 
 ### Added
@@ -22,7 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Memory archive layer with `oacp archive` CLI command for active/archive split (#62, #11)
+- Memory archive layer with `oacp memory archive` CLI command for active/archive split (#62, #11)
 - Declarative agent profiles with YAML schema and `oacp agent init|show|list` CLI commands (#52, #48)
 - `known_debt.md` as standard memory file for tracking technical debt (#53, #32)
 
@@ -86,6 +110,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Checkout step in github-release workflow job (#19)
 - Pre-release audit fixes: SHA-pinned actions, dangling doc refs (#15, #16)
 
+[0.2.2]: https://github.com/kiloloop/oacp/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/kiloloop/oacp/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/kiloloop/oacp/compare/v0.1.9...v0.2.0
 [0.1.9]: https://github.com/kiloloop/oacp/compare/v0.1.2...v0.1.9
 [0.1.2]: https://github.com/kiloloop/oacp/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/kiloloop/oacp/compare/v0.1.0...v0.1.1

{oacp_cli-0.2.0 → oacp_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oacp-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open Agent Coordination Protocol CLI for file-based multi-agent workflows
 Project-URL: Homepage, https://github.com/kiloloop/oacp
 Project-URL: Repository, https://github.com/kiloloop/oacp
@@ -34,44 +34,38 @@ Description-Content-Type: text/markdown
 
 > **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.
 
-**Empowering solo founders to coordinate AI agents, with human-in-the-loop for control.**
+**Coordinate agents without the chaos.**
 
-A file-based coordination protocol for multi-agent engineering workflows. OACP defines the message formats, state machines, review processes, and safety rules that enable AI agents on different runtimes to collaborate asynchronously through a shared filesystem.
+A file-based protocol for multi-agent engineering workflows. OACP defines the message formats, review processes, and safety rules that let AI agents on different runtimes collaborate through a shared filesystem. Not a framework or SDK — just conventions, YAML schemas, and scripts that any runtime can implement.
 
-**OACP is not a framework or SDK.** It is a set of conventions, YAML schemas, and shell scripts that any agent runtime can implement — Claude, Codex, Gemini, or your own.
-
-## Try it now
-
-See if your machine is ready for multi-agent workflows — no project setup required:
+## Quick Start
 
 ```bash
 pip install oacp-cli
-oacp doctor
+oacp init my-project --agents alice,bob
+oacp send my-project --from alice --to bob --type task_request \
+  --subject "Implement feature X" --body "Details here..."
 ```
 
-```
-[-] Environment
-    [+] git — git version 2.47.0
-    [+] python3 — Python 3.12.4
-    [+] gh — gh version 2.62.0 (2024-11-14)
-    [+] ruff — ruff 0.8.1
-    [-] shellcheck — not installed (optional)
-        Install: brew install shellcheck
-    [+] pyyaml — available
-
-No issues found.
-```
+When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough.
+
+### What you get
+
+- **Inbox/outbox messaging** — async YAML messages with threading, broadcast, and expiry
+- **Structured review loop** — severity-graded findings, quality gates, multi-round review
+- **Inbox CLI** — `oacp inbox` lists pending messages across agents with table or `--json` output
+- **Watch CLI** — `oacp watch` emits inbox delta events for Claude Monitor or shell loops
+- **Durable shared memory** — project facts, decisions, and known debt with active/archive split
+- **Agent safety defaults** — baseline rules for git, credentials, and scope discipline
+- **Runtime-agnostic** — works with any runtime that reads/writes files
 
-Doctor checks your CLI tools, and with `--project` it audits workspace structure, inbox health, YAML schemas, and agent status. See the [full doctor guide](docs/guides/doctor.md) for details.
+## Try It Now
 
-### Features
+After installing, run `oacp doctor` to verify your environment is wired up:
 
-- **Inbox/outbox messaging** — async YAML-based communication with threading, broadcast, and expiry
-- **Structured review loop** — severity-graded findings, quality gates, and multi-round review
-- **Durable shared memory** — project facts, decisions, open threads, and known debt with an explicit active/archive split
-- **Dispatch state machine** — full task lifecycle tracking from assignment to merge
-- **Agent safety defaults** — baseline rules for git, credentials, staging, and scope discipline
-- **Runtime-agnostic** — works with any agent runtime that can read/write files
+```bash
+oacp doctor
+```
 
 ## Why OACP?
 
@@ -150,13 +144,36 @@ uv tool install .
 
 ## Commands
 
-- `oacp init` creates a project workspace under `$OACP_HOME/projects/`
-- `oacp memory` archives or restores project memory files
-- `oacp send` sends a protocol-compliant inbox message
-- `oacp doctor` checks environment and workspace health
-- `oacp validate` validates an inbox/outbox YAML message
+| Command | Description |
+|---------|-------------|
+| `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |
+| `oacp add-agent` | Add an agent to an existing project workspace |
+| `oacp setup` | Generate runtime-specific config files (Claude, Codex, etc.) |
+| `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |
+| `oacp inbox` | List pending messages across agents (table or `--json`) |
+| `oacp watch` | Emit inbox delta events for one agent across selected projects |
+| `oacp memory` | Archive or restore project memory files |
+| `oacp agent` | Manage global agent profiles (`init`, `show`, `list`) |
+| `oacp org-memory` | Initialize org-level memory at `$OACP_HOME/org-memory/` |
+| `oacp write-event` | Write an event to `org-memory/events/` |
+| `oacp doctor` | Check environment and workspace health |
+| `oacp validate` | Validate an inbox/outbox YAML message |
+| `oacp --version` | Print the installed version |
+
+<details>
+<summary>Key flags</summary>
+
+**`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
+
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`
+
+**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
+
+**`oacp memory`**: `oacp memory archive <project> <file>`, `oacp memory restore <project> <file>`
+
+</details>
 
-If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
+If `OACP_HOME` is unset, workspace commands default to `~/oacp`.
 
 ## Key Concepts
 
@@ -174,61 +191,24 @@ If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
 ```
 oacp/
 ├── docs/
-│   ├── protocol/       # Canonical protocol specifications (13 specs)
+│   ├── protocol/       # Canonical protocol specifications
 │   └── guides/         # Setup, adoption, versioning
-├── scripts/            # 18 kernel scripts (Python + shell)
-├── templates/          # Packet, role, and guardrail templates (19)
+├── scripts/            # Kernel scripts (Python + shell)
+├── templates/          # Packet, role, and guardrail templates
 ├── tests/              # Test suite
 ├── Makefile            # Task runner (make help for all targets)
 └── SPEC.md             # Full protocol specification
 ```
 
-## Quick Start
-
-```bash
-# 1. Clone the repo
-git clone https://github.com/kiloloop/oacp.git
-cd oacp
-
-# 2. Install the CLI
-uv tool install oacp-cli
-
-# 3. Initialize a project workspace
-export OACP_HOME="$HOME/oacp"
-oacp init my-project
-
-# 4. Send your first message
-oacp send my-project \
-  --from alice --to bob --type task_request \
-  --subject "Implement feature X" \
-  --body "Details here..."
-
-# 5. Check environment health
-oacp doctor
-```
-
-See [QUICKSTART.md](QUICKSTART.md) for a complete 5-minute walkthrough.
-
-## Scripts
-
-OACP ships kernel scripts — the key CLI commands you'll use most:
+## Related
 
-- **`oacp init`** — create a new project workspace (the first command you run)
-- **`oacp add-agent`** — add an agent to an existing project workspace
-- **`oacp memory`** — archive or restore project memory files
-- **`oacp setup`** — generate runtime-specific config files (Claude, Codex, Gemini)
-- **`oacp send`** — send protocol-compliant messages between agents
-- **`oacp doctor`** — environment and workspace health check
-- **`oacp validate`** — validate inbox/outbox YAML messages
-
-Run `make help` to see all available Makefile targets, or see [SPEC.md](SPEC.md) for the full script inventory.
+- **[agent-estimate](https://github.com/kiloloop/agent-estimate)** — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.
 
 ## Prerequisites
 
 - Python 3.9+
 - Bash 3.2+ (macOS default is fine)
-- `gh` CLI (for GitHub operations)
-- `pyyaml` (`pip install pyyaml`)
+- `gh` CLI (optional, for GitHub operations)
 
 ## Protocol Specification
 
@@ -244,16 +224,15 @@ Individual protocol specs live in [`docs/protocol/`](docs/protocol/).
 
 ## Workspace Layout
 
-When you initialize a project, OACP creates this structure:
+`oacp init` creates a project workspace with this structure:
 
 ```
 $OACP_HOME/projects/<project>/
 ├── agents/
 │   ├── <agent-a>/
-│   │   ├── inbox/          # Other agents write here
-│   │   ├── outbox/         # Sent messages (copies)
-│   │   ├── status.yaml     # Dynamic agent state
-│   │   └── agent_card.yaml # Static agent identity
+│   │   ├── inbox/           # Other agents write here
+│   │   ├── outbox/          # Sent messages (copies)
+│   │   └── dead_letter/     # Undeliverable messages
 │   └── <agent-b>/
 │       └── ...
 ├── memory/                  # Shared durable memory
@@ -262,10 +241,24 @@ $OACP_HOME/projects/<project>/
 │   ├── open_threads.md
 │   ├── known_debt.md
 │   └── archive/
+├── artifacts/               # Build/research artifacts
+├── checkpoints/             # Progress checkpoints
+├── logs/                    # Agent session logs
+├── merges/                  # Merge decision records
 ├── packets/                 # Review/findings artifacts
 └── workspace.json           # Project metadata
 ```
 
+Optionally, `oacp org-memory init` creates org-level shared memory:
+
+```
+$OACP_HOME/org-memory/
+├── recent.md                # Always-loaded rolling summary
+├── decisions.md             # Org-wide decisions
+├── rules.md                 # Standing conventions
+└── events/                  # Timestamped event entries
+```
+
 ## Development
 
 ```bash

{oacp_cli-0.2.0 → oacp_cli-0.2.2}/QUICKSTART.md

@@ -5,7 +5,6 @@ Get from zero to your first agent-to-agent message in 5 minutes.
 ## Prerequisites
 
 - Python 3.9+ and Bash 3.2+
-- `pip install pyyaml`
 
 ## 1. Set Up OACP Home
 
@@ -34,6 +33,12 @@ pipx install oacp-cli
 
 Every project gets its own workspace with agent inboxes, shared memory, and packet directories.
 
+```bash
+oacp init my-first-project --agents claude,codex,gemini --repo /path/to/repo
+```
+
+Or with defaults (agents: claude, codex, gemini):
+
 ```bash
 oacp init my-first-project
 ```

{oacp_cli-0.2.0 → oacp_cli-0.2.2}/README.md

@@ -8,44 +8,38 @@
 
 > **[Try the quickstart →](examples/quickstart/)** — send your first message to an AI agent in 5 minutes.
 
-**Empowering solo founders to coordinate AI agents, with human-in-the-loop for control.**
+**Coordinate agents without the chaos.**
 
-A file-based coordination protocol for multi-agent engineering workflows. OACP defines the message formats, state machines, review processes, and safety rules that enable AI agents on different runtimes to collaborate asynchronously through a shared filesystem.
+A file-based protocol for multi-agent engineering workflows. OACP defines the message formats, review processes, and safety rules that let AI agents on different runtimes collaborate through a shared filesystem. Not a framework or SDK — just conventions, YAML schemas, and scripts that any runtime can implement.
 
-**OACP is not a framework or SDK.** It is a set of conventions, YAML schemas, and shell scripts that any agent runtime can implement — Claude, Codex, Gemini, or your own.
-
-## Try it now
-
-See if your machine is ready for multi-agent workflows — no project setup required:
+## Quick Start
 
 ```bash
 pip install oacp-cli
-oacp doctor
+oacp init my-project --agents alice,bob
+oacp send my-project --from alice --to bob --type task_request \
+  --subject "Implement feature X" --body "Details here..."
 ```
 
-```
-[-] Environment
-    [+] git — git version 2.47.0
-    [+] python3 — Python 3.12.4
-    [+] gh — gh version 2.62.0 (2024-11-14)
-    [+] ruff — ruff 0.8.1
-    [-] shellcheck — not installed (optional)
-        Install: brew install shellcheck
-    [+] pyyaml — available
-
-No issues found.
-```
+When running inside a configured agent runtime, `--from` can be omitted — OACP infers the sender from `OACP_AGENT`, `AGENT_NAME`, or the agent card. See [QUICKSTART.md](QUICKSTART.md) for a full walkthrough.
+
+### What you get
+
+- **Inbox/outbox messaging** — async YAML messages with threading, broadcast, and expiry
+- **Structured review loop** — severity-graded findings, quality gates, multi-round review
+- **Inbox CLI** — `oacp inbox` lists pending messages across agents with table or `--json` output
+- **Watch CLI** — `oacp watch` emits inbox delta events for Claude Monitor or shell loops
+- **Durable shared memory** — project facts, decisions, and known debt with active/archive split
+- **Agent safety defaults** — baseline rules for git, credentials, and scope discipline
+- **Runtime-agnostic** — works with any runtime that reads/writes files
 
-Doctor checks your CLI tools, and with `--project` it audits workspace structure, inbox health, YAML schemas, and agent status. See the [full doctor guide](docs/guides/doctor.md) for details.
+## Try It Now
 
-### Features
+After installing, run `oacp doctor` to verify your environment is wired up:
 
-- **Inbox/outbox messaging** — async YAML-based communication with threading, broadcast, and expiry
-- **Structured review loop** — severity-graded findings, quality gates, and multi-round review
-- **Durable shared memory** — project facts, decisions, open threads, and known debt with an explicit active/archive split
-- **Dispatch state machine** — full task lifecycle tracking from assignment to merge
-- **Agent safety defaults** — baseline rules for git, credentials, staging, and scope discipline
-- **Runtime-agnostic** — works with any agent runtime that can read/write files
+```bash
+oacp doctor
+```
 
 ## Why OACP?
 
@@ -124,13 +118,36 @@ uv tool install .
 
 ## Commands
 
-- `oacp init` creates a project workspace under `$OACP_HOME/projects/`
-- `oacp memory` archives or restores project memory files
-- `oacp send` sends a protocol-compliant inbox message
-- `oacp doctor` checks environment and workspace health
-- `oacp validate` validates an inbox/outbox YAML message
+| Command | Description |
+|---------|-------------|
+| `oacp init` | Create a project workspace under `$OACP_HOME/projects/` |
+| `oacp add-agent` | Add an agent to an existing project workspace |
+| `oacp setup` | Generate runtime-specific config files (Claude, Codex, etc.) |
+| `oacp send` | Send a protocol-compliant inbox message (`--from` auto-inferred) |
+| `oacp inbox` | List pending messages across agents (table or `--json`) |
+| `oacp watch` | Emit inbox delta events for one agent across selected projects |
+| `oacp memory` | Archive or restore project memory files |
+| `oacp agent` | Manage global agent profiles (`init`, `show`, `list`) |
+| `oacp org-memory` | Initialize org-level memory at `$OACP_HOME/org-memory/` |
+| `oacp write-event` | Write an event to `org-memory/events/` |
+| `oacp doctor` | Check environment and workspace health |
+| `oacp validate` | Validate an inbox/outbox YAML message |
+| `oacp --version` | Print the installed version |
+
+<details>
+<summary>Key flags</summary>
+
+**`oacp send`**: `--in-reply-to`, `--expires`, `--body-file`, `--channel`, `--dry-run`, `--json`, `--quiet`
+
+**`oacp watch`**: `--agent`, repeatable `--project`, `--all-projects`, `--json`
+
+**`oacp doctor`**: `--fix` (auto-fix safe issues), `--json`, `-o/--output`
+
+**`oacp memory`**: `oacp memory archive <project> <file>`, `oacp memory restore <project> <file>`
+
+</details>
 
-If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
+If `OACP_HOME` is unset, workspace commands default to `~/oacp`.
 
 ## Key Concepts
 
@@ -148,61 +165,24 @@ If `OACP_HOME` is unset, workspace commands default to `~/oacp` (underscore).
 ```
 oacp/
 ├── docs/
-│   ├── protocol/       # Canonical protocol specifications (13 specs)
+│   ├── protocol/       # Canonical protocol specifications
 │   └── guides/         # Setup, adoption, versioning
-├── scripts/            # 18 kernel scripts (Python + shell)
-├── templates/          # Packet, role, and guardrail templates (19)
+├── scripts/            # Kernel scripts (Python + shell)
+├── templates/          # Packet, role, and guardrail templates
 ├── tests/              # Test suite
 ├── Makefile            # Task runner (make help for all targets)
 └── SPEC.md             # Full protocol specification
 ```
 
-## Quick Start
-
-```bash
-# 1. Clone the repo
-git clone https://github.com/kiloloop/oacp.git
-cd oacp
-
-# 2. Install the CLI
-uv tool install oacp-cli
-
-# 3. Initialize a project workspace
-export OACP_HOME="$HOME/oacp"
-oacp init my-project
-
-# 4. Send your first message
-oacp send my-project \
-  --from alice --to bob --type task_request \
-  --subject "Implement feature X" \
-  --body "Details here..."
-
-# 5. Check environment health
-oacp doctor
-```
-
-See [QUICKSTART.md](QUICKSTART.md) for a complete 5-minute walkthrough.
-
-## Scripts
-
-OACP ships kernel scripts — the key CLI commands you'll use most:
+## Related
 
-- **`oacp init`** — create a new project workspace (the first command you run)
-- **`oacp add-agent`** — add an agent to an existing project workspace
-- **`oacp memory`** — archive or restore project memory files
-- **`oacp setup`** — generate runtime-specific config files (Claude, Codex, Gemini)
-- **`oacp send`** — send protocol-compliant messages between agents
-- **`oacp doctor`** — environment and workspace health check
-- **`oacp validate`** — validate inbox/outbox YAML messages
-
-Run `make help` to see all available Makefile targets, or see [SPEC.md](SPEC.md) for the full script inventory.
+- **[agent-estimate](https://github.com/kiloloop/agent-estimate)** — Estimate how long agent tasks take. Pairs with OACP dispatch for task sizing.
 
 ## Prerequisites
 
 - Python 3.9+
 - Bash 3.2+ (macOS default is fine)
-- `gh` CLI (for GitHub operations)
-- `pyyaml` (`pip install pyyaml`)
+- `gh` CLI (optional, for GitHub operations)
 
 ## Protocol Specification
 
@@ -218,16 +198,15 @@ Individual protocol specs live in [`docs/protocol/`](docs/protocol/).
 
 ## Workspace Layout
 
-When you initialize a project, OACP creates this structure:
+`oacp init` creates a project workspace with this structure:
 
 ```
 $OACP_HOME/projects/<project>/
 ├── agents/
 │   ├── <agent-a>/
-│   │   ├── inbox/          # Other agents write here
-│   │   ├── outbox/         # Sent messages (copies)
-│   │   ├── status.yaml     # Dynamic agent state
-│   │   └── agent_card.yaml # Static agent identity
+│   │   ├── inbox/           # Other agents write here
+│   │   ├── outbox/          # Sent messages (copies)
+│   │   └── dead_letter/     # Undeliverable messages
 │   └── <agent-b>/
 │       └── ...
 ├── memory/                  # Shared durable memory
@@ -236,10 +215,24 @@ $OACP_HOME/projects/<project>/
 │   ├── open_threads.md
 │   ├── known_debt.md
 │   └── archive/
+├── artifacts/               # Build/research artifacts
+├── checkpoints/             # Progress checkpoints
+├── logs/                    # Agent session logs
+├── merges/                  # Merge decision records
 ├── packets/                 # Review/findings artifacts
 └── workspace.json           # Project metadata
 ```
 
+Optionally, `oacp org-memory init` creates org-level shared memory:
+
+```
+$OACP_HOME/org-memory/
+├── recent.md                # Always-loaded rolling summary
+├── decisions.md             # Org-wide decisions
+├── rules.md                 # Standing conventions
+└── events/                  # Timestamped event entries
+```
+
 ## Development
 
 ```bash