Agency OS Skill for Claude

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:

• 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).

• Natural-language driving — the skill translates conversational chat into

the corresponding command. Examples in

references/natural-language.md.

• 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