diff --git a/AGENTS.md b/AGENTS.md index 0cfd78a..523ae78 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,3 +32,14 @@ For `docs/tests/inbox/`: - organize by folder plus `README.md` - do not use numeric test IDs - use stable case slugs and keep the roadmap synchronized with the actual files on disk + +## Project Skills + +For `skills/`: + +- treat this directory as project-local Codex skill packages, not general documentation +- use skills to package reusable agent workflows, constraints, and bundled assets so other agents can use them without rediscovering repository context +- keep each skill self-contained around `SKILL.md`; add `agents/openai.yaml` and bundled assets only when they directly support real invocation +- if a skill depends on an executable or other runtime asset, prefer bundling the required artifact with the skill instead of relying on ad hoc rebuild instructions as the primary workflow +- when updating an existing skill, keep `SKILL.md`, `agents/openai.yaml`, and bundled assets consistent with each other +- if you add or materially change a project skill, update [docs/implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) in the same change diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index 5781fec..85f8f70 100644 --- a/docs/implementation-roadmap.md +++ b/docs/implementation-roadmap.md @@ -21,6 +21,7 @@ As of now: - `inbox` supports blocking waits, lease renewal, unread fetches backed by per-agent read cursors, `--body-file`, artifact attachments, and structured JSON errors with stable exit codes - integration tests now cover each implemented inbox command, plus the main inbox workflows, wait/watch flows, artifact persistence, unread behavior, and JSON error contracts - a human-readable inbox command test-plan set has been authored under `docs/tests/inbox/` +- a reusable Codex skill package for `inbox` now exists under `skills/inbox/`, with a formal `SKILL.md`, `agents/openai.yaml`, and a bundled CLI binary asset - `orch` currently exists as a command skeleton only - no scheduler workflows have been implemented yet diff --git a/skills/inbox/SKILL.md b/skills/inbox/SKILL.md new file mode 100644 index 0000000..5d56526 --- /dev/null +++ b/skills/inbox/SKILL.md @@ -0,0 +1,60 @@ +--- +name: inbox +description: Durable agent-to-agent coordination through a bundled inbox CLI. Use when an agent needs to fetch work, claim a thread, report progress, ask blocked questions, wait for replies, inspect thread history, or return done/fail results through a SQLite-backed inbox instead of ad hoc chat. +--- + +# Inbox + +Use the bundled `./assets/inbox` CLI to communicate through a durable SQLite-backed inbox. + +## Quick Start + +- Invoke `./assets/inbox` relative to this skill directory. +- Pass `--db` explicitly for every command. +- Prefer `--json` whenever another agent or script will read the output. +- Run `init` before first use on a new database path. + +## Rules + +- Treat `fetch` as discovery only; only `claim` grants ownership. +- Do not start work without a valid lease. +- Use `update --status in_progress` for progress and `update --status blocked` for precise questions. +- Prefer `wait-reply` over manual sleep loops when blocked. +- Use `done` for terminal success and `fail` for terminal failure. +- Keep scheduling and dependency decisions out of this layer; those belong to `orch`. + +## Typical Commands + +```bash +./assets/inbox --db ./coord.db --json init +./assets/inbox --db ./coord.db --json fetch --agent backend-worker --status pending +./assets/inbox --db ./coord.db --json claim --agent backend-worker --thread thr_123 --lease-seconds 900 +./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status in_progress --summary "Implementing post CRUD routes" +./assets/inbox --db ./coord.db --json update --agent backend-worker --thread thr_123 --status blocked --summary "Need auth decision" --payload-json '{"question":"Should admin auth use email/password in MVP?"}' +./assets/inbox --db ./coord.db --json wait-reply --agent backend-worker --thread thr_123 --after-event 51 --timeout-seconds 1800 +./assets/inbox --db ./coord.db --json reply --from leader --to backend-worker --thread thr_123 --summary "Use email/password for MVP" --body "Use a simple credential flow for the first iteration." +./assets/inbox --db ./coord.db --json done --agent backend-worker --thread thr_123 --summary "Post CRUD implemented" --body-file result.md +``` + +## Command Map + +- `init`: initialize schema and pragmas on a database path +- `send`: create a new thread or append a message +- `fetch`: list candidate threads for an agent without claiming them +- `claim`: acquire a lease on a thread +- `renew`: extend an active lease +- `update`: send progress or blocked updates +- `reply`: send an answer, control message, or follow-up inside a thread +- `done`: mark a thread complete with final result data +- `fail`: mark a thread failed with failure details +- `cancel`: cancel a thread +- `list`: list threads by filters +- `show`: inspect thread state and message history +- `watch`: block until matching thread activity arrives +- `wait-reply`: block until a reply arrives for a specific thread + +## Notes + +- `body-file` and artifact-heavy flows are supported; prefer them over long inline strings when sending reports or patches. +- `fetch --unread` and `show --mark-read` depend on per-agent read cursors. +- If the bundled binary cannot execute on the current host, stop and report the compatibility issue instead of guessing a replacement path or workflow. diff --git a/skills/inbox/agents/openai.yaml b/skills/inbox/agents/openai.yaml new file mode 100644 index 0000000..603835d --- /dev/null +++ b/skills/inbox/agents/openai.yaml @@ -0,0 +1,7 @@ +interface: + display_name: "Inbox CLI" + short_description: "Durable agent coordination CLI" + default_prompt: "Use $inbox to coordinate work through the bundled inbox CLI and a SQLite inbox database." + +policy: + allow_implicit_invocation: true diff --git a/skills/inbox/assets/inbox b/skills/inbox/assets/inbox new file mode 100755 index 0000000..ff68f32 Binary files /dev/null and b/skills/inbox/assets/inbox differ