agency-os

Notion-as-source-of-truth dispatch board. One Tasks database, one Hub page, one
page per Corpus, one page each for General Guidance and Resources. The skill
mutates Notion via the Notion MCP (mcp__*__notion-* tools); only
references/notion-pointers.json is committed to git.

Skill name decision: the skill is named agency-os (matching the repo). All
commands are /agency-os <cmd>. This is the single plugin entry point; there
is no agency-os/notion sub-namespace. If you embed this plugin alongside
others, prefix commands with agency-os to avoid collisions.

Overview

agency-os turns a single Notion database into a multi-status dispatch board for
AI work. The model is intentionally narrow:

• One Tasks database is the source of truth for status, priority, model
  selection, and ownership. No parallel kanban tools.
• One Hub page holds the General Guidance, Resources, and Corpus pointers
  that every task consults.
• Tasks flow through five statuses: Suggestion → Discussion → To-Do →
  In Progress → Done. The dedup gate at each transition prevents accidental
  re-execution.
• run fans approved To-Do rows out to parallel agents. Each task carries
  its own model selection (Haiku for cheap fan-out, Sonnet for default,
  Opus for hard reasoning) and respects declared dependencies.

The skill is stateless on disk — the only committed artifact is
references/notion-pointers.json (database/page IDs). All runtime state lives
in Notion.

For the full architecture (status flow, sync protocol, workspace structure,
pointer/cache format), see `references/architecture.md`.

Prerequisites

• Notion MCP server installed:
  npx -y @notionhq/notion-mcp-server (declare in .mcp.json)
• Notion integration token (NOTION_TOKEN) with read+write access to your
  workspace. Add .env to .gitignore — never commit the token.
• A Notion Tasks database with the columns the skill expects (see
  references/architecture.md § "Workspace structure" for the schema). The
  /agency-os init command can scaffold this for you.
• Python 3 for the optional scripts/query-tasks.py helper.

First-time setup:

ccpi install agency-os
# then in Claude Code:
/agency-os init --harness=basic --haiku=cost-tier --sonnet=default --opus=hard-reasoning

Instructions

The skill is a CLI surface over Notion. Three usage patterns:

1. Direct command invocation — /agency-os <cmd> [args]. See
   `references/commands.md` for the full reference
   of 19 commands (init, scaffold, suggest, discuss, log,
   add-subtask, approve, start, refresh, run, done, kill,
   next, status, list, show, update, move, plus launch alias).

2. Natural-language driving — the skill translates conversational chat into
   the corresponding command. Examples in
   `references/natural-language.md`.

3. Batch execution — /agency-os run [--go] fans the entire To-Do queue
   out to parallel agents with per-task model selection. See ## Examples
   below for the canonical flow.

Status flow is enforced — you cannot skip a stage. Every command performs a
sync preflight to ensure your local view of Notion is current (see
references/architecture.md § "Sync — preflight on every command").

When drafting any user-facing copy (READMEs, blog posts, launch surfaces),
apply the positioning brief at
`references/positioning.md` before writing.

Output

Every command returns to chat with:

• Verdict line — ✅ <action> or ⚠️ <reason> (one line, scannable)
• Affected task IDs and titles — every task touched, with its new status
• Next-action hint — what command the operator would typically run next

Batch run additionally emits:

• A per-task pass/fail table
• Total model spend estimate (Haiku/Sonnet/Opus call counts)
• Outstanding-dependency callouts for tasks that couldn't start

Error Handling

The skill fails closed on five well-defined cases (full details in
references/architecture.md § "Status flow — the dedup gate"):

Condition	Behavior
Notion API auth fails	Halt, print "NOTION_TOKEN missing or invalid", exit 1
Database/page ID drift (pointers stale)	Halt, print "Run /agency-os refresh", exit 1
Status-flow violation (e.g. approve on a Suggestion)	Halt with the required prerequisite step quoted
Dependency cycle detected during run	Halt, list the cycle, exit 1
Task missing required model selection	Halt, print "Run /agency-os update <id> --model <tier>"

The skill never silently corrects state in Notion — every fix is an explicit
command the operator must run.

Examples

Capture a chat insight as a Suggestion:

User: add a suggestion: refactor the auth flow to use the new token cache
Skill: → /agency-os suggest "refactor the auth flow to use the new token cache"
       ✅ Created Suggestion #t-2026-05-23-001 in corpus "platform"
       Next: /agency-os discuss t-2026-05-23-001

Approve and run a batch:

User: approve t-2026-05-23-{001..003} then run the queue
Skill: ✅ Approved 3 tasks → To-Do
       /agency-os run --go
       → fanning to 3 parallel agents...
       ✅ Done: 2 | ⚠️ Blocked on deps: 1 | Total spend: ~$0.04

More examples and the full command catalog are in
`references/commands.md`.

Resources

• Plugin source: https://github.com/ratamaha-git/agency-os
• Launch post: https://automatelab.tech/agency-os-launch/
• references/architecture.md — status flow, sync protocol, workspace schema
• references/commands.md — full CLI reference (19 commands)
• references/natural-language.md — chat-to-command translation table
• references/positioning.md — canonical brief for user-facing copy
• references/general-guidance.md — shared operating principles applied to every task
• references/notion-pointers.json — pointer file scaffold (database/page IDs)
• references/task-page-template.md — Notion page template for new tasks
• references/corpus-template.md — Notion page template for a Corpus
• references/config-template.json — default per-task model routing
• scripts/query-tasks.py — optional Python helper for offline introspection