# Agency Os

> |

- **Type:** Skill
- **Install:** `agentstack add skill-jeremylongshore-claude-code-plugins-plus-skills-agency-os`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jeremylongshore](https://agentstack.voostack.com/s/jeremylongshore)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jeremylongshore](https://github.com/jeremylongshore)
- **Source:** https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/ai-agency/agency-os/skills/agency-os
- **Website:** https://tonsofskills.com

## Install

```sh
agentstack add skill-jeremylongshore-claude-code-plugins-plus-skills-agency-os
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `. 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`](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:

```bash
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  [args]`. See
   [`references/commands.md`](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`](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`](references/positioning.md) before writing.

## Output

Every command returns to chat with:

- **Verdict line** — `✅ ` or `⚠️ ` (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  --model `" |

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:

```text
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:

```text
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`](references/commands.md).

## Resources

- **Plugin source**: 
- **Launch post**: 
- **`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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jeremylongshore](https://github.com/jeremylongshore)
- **Source:** [jeremylongshore/claude-code-plugins-plus-skills](https://github.com/jeremylongshore/claude-code-plugins-plus-skills)
- **License:** MIT
- **Homepage:** https://tonsofskills.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jeremylongshore-claude-code-plugins-plus-skills-agency-os
- Seller: https://agentstack.voostack.com/s/jeremylongshore
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.