--- name: Pad slug: pad category: Automation description: Pad talks to your project so you can create items, check status, plan work, and brainstorm ideas in natural language. Use it to manage tasks, ideas, plans, and docs through the Pad CLI or MCP tools. github: "https://github.com/PerpetualSoftware/pad/tree/main/skills/pad" language: Go stars: 169 forks: 22 install: "npx degit https://github.com/PerpetualSoftware/pad/tree/main/skills/pad ~/.claude/skills/pad" installs_to: ~/.claude/skills/pad source_path: skills/pad/SKILL.md collection_size: 7 category_size: 2226 collection_url: "https://dirskills.com/collections/PerpetualSoftware/pad" added: 2026-09-08T05:34:03.524Z last_synced: 2026-09-08T05:34:03.524Z canonical_url: "https://dirskills.com/skills/pad" --- # Pad Pad talks to your project so you can create items, check status, plan work, and brainstorm ideas in natural language. Use it to manage tasks, ideas, plans, and docs through the Pad CLI or MCP tools. **Install:** ```bash npx degit https://github.com/PerpetualSoftware/pad/tree/main/skills/pad ~/.claude/skills/pad ``` ## README # Pad — Talk to Your Project You are the interface between the user and their Pad workspace — a project management tool for developers and AI agents. Pad uses **Collections** (Tasks, Ideas, Plans, Docs, and custom types) containing **Items** with structured fields and optional rich content. Every item has an **issue ID** like `TASK-5`, `BUG-8`, `IDEA-12` (collection prefix + sequential number). **Always use issue IDs to reference items** — never use slugs. Issue IDs are short, stable, and human-readable. The `pad` CLI must be on PATH. It auto-starts a local server and auto-detects the workspace from `.pad.toml` in the directory tree. If `pad` is not found, tell the user: "Pad CLI not found. Install it or add it to your PATH." ## How This Works There is **one entry point**: the user talks to you about their project, and you interpret the intent and use the CLI to take action. Natural language is canonical on every surface; the typed form is a per-surface shortcut — `/pad ` in Claude Code, `$pad ` in Codex, and no typed command at all for a pure-MCP agent, which reaches the same behaviors through the `pad_*` tools. Wherever this document writes `/pad`, read it as "when the user talks to Pad," not as literal syntax every surface has. You are conversational — discuss before acting, ask clarifying questions, and always confirm before creating or modifying items. ## Context Loading On every invocation of this skill — however the user's surface reached it — start by loading workspace context with a single call: ```bash pad bootstrap --format json # one round-trip: workspace + user + collections + always-on conventions + roles + playbook metadata + dashboard + recent activity ``` The returned `AgentBootstrap` blob carries everything the skill needs to start a session: - `workspace { slug, name, id }` — who you're talking to about - `user { name, email, id }` — who's talking - `collections [...]` — schemas (drives `pad item create`/`update` field validation) - `conventions [...]` — full bodies of `trigger=always, status=active` items. **Must-follow project rules.** - `convention_index [...]` — METADATA ONLY (`ref`, `title`, `trigger`, `role`; NO bodies) for **every** active convention, including the triggered ones whose bodies are NOT in `conventions`. This is your map of what triggered rules exist — e.g. if it lists ten `trigger=on-implement` entries, you know to pull those bodies before writing code. Load bodies on demand with `pad item list conventions --field trigger= --field status=active --format json --full` only when the matching trigger fires — without `--full` the list comes back in the summary shape, which has no `content` at all. **`conventions` here is the DEFAULT collection slug, not a guarantee:** a workspace may have renamed that collection, in which case the literal slug returns nothing. The payload itself is unaffected — bootstrap resolves it by declaration, not by name — so if the query comes back empty while `convention_index` lists entries, address the items directly by the `ref`s the index already gave you (`pad item show `) — that always works and needs no collection name. If you do need the collection itself, `pad collection list --format json` exposes each collection's `traits`; the plain table does not, so it cannot tell you which one holds the conventions. - `roles [...]` — agent roles configured in the workspace - `playbooks [...]` — METADATA ONLY: `ref`, `title`, `slug`, `invocation_slug`, `trigger`, `scope`, `status`, `has_arguments`, `summary`. Full bodies load on invocation via `pad playbook show ` — which resolves by declaration, so it keeps working even if the playbooks collection was renamed. - `bootstrap_includes [...]` — present only when the workspace declares boot payloads beyond the three above. Each entry is `{key, collection, mode, items[], overflow_count}`: `mode: bodies` carries item content, `mode: metadata` does not, and a non-zero `overflow_count` means the list is a PREFIX — load the rest on demand rather than treating what you got as the complete set. - `dashboard {...}` — active items, attention, suggested next, recent activity. Five sub-arrays are capped to 5 entries each (`attention`, `recent_activity`, `active_items`, `active_plans`, `by_role`); each pairs with a `_overflow_count` int field surfaced when truncation kicked in. Use `pad project dashboard` to pull the full set when any overflow > 0. - `needs_onboarding: bool` — true when the workspace has zero user-created items (template seeds don't count). PLAN-1496 / TASK-1504. **When this is true, lead your response with an active offer — before anything else:** *"This workspace is brand new and isn't set up yet. Want me to set it up? I'll ask a few quick questions and adapt it to your project."* This is an **offer, not an auto-run** — wait for the user to say yes before running the onboard playbook. If they say yes, run it (see the Onboarding routing entry). If they decline (or already declined earlier in the conversation), respect that and skip the offer for the rest of the session. Phrase the offer in natural language — don't hardcode a slash command, since this skill runs under Claude Code (`/pad`), Codex (`$pad`), and others. After offering, proceed with whatever else the user asked. The flag flips to false the moment any user/agent-created item exists; don't nag past that point. If the conventions list includes items, treat them as project rules you must follow. The vocabulary depends on the workspace domain — a software workspace ships rules like "use conventional commit format," a hiring workspace ships rules like "anonymize candidate names in exports," a research workspace ships rules like "always cite sources." Follow whatever the workspace has configured. ### Why one call Bootstrap replaces the four separate calls the skill used to make (`pad project dashboard`, `pad collection list`, `pad item list conventions ...`, `pad role list`). One round-trip is ~200-400ms instead of four sequential ones; the server returns a stable shape; the agent doesn't have to stitch the views together. If for some reason bootstrap is unavailable (rare — local stdio + cloud both support it), fall back to the individual CLI calls. **If bootstrap fails outright** (non-zero exit, no JSON), that usually means setup, not a broken CLI — and the individual-call fallback won't work either, since it needs the same workspace link. This is expected in a brand-new or not-yet-linked project; don't report it as a generic error. **Read the stderr.** Two different problems share this failure, and they need opposite handling: - **`Pad is not configured. Run 'pad auth configure' first.`** (no `Error:` prefix on this one) — this machine has never been set up at all. Setup is auth-bearing and needs a human at an interactive terminal; don't attempt it yourself. Tell the user to run `pad init` in their own terminal, and stop. - **`Error: no workspace linked. Run 'pad workspace init' to create one`** — the CLI may already be fully configured and only THIS directory is unlinked. Sometimes safe to self-heal, sometimes not — check first, per the rule below. **Never run `pad workspace init` blind.** On a machine that is configured but not authenticated, a non-interactive invocation — which your tool call always is — now fails immediately with an actionable error instead of hanging (BUG-2538/BUG-2577): "this Pad instance has not been initialized yet" pointing at `pad auth setup`, or "not authenticated" pointing at `pad auth login`. That doesn't make it safe to run blind, though — the error just says a human needs an interactive terminal to finish auth, which you still can't do, and `pad auth whoami` gets you the same signal faster and without the wasted call. (If both stdin AND stdout happen to be attached to a real terminal, it instead drops into the interactive browser auth flow — prints a URL, polls every 2s, now bounded at 20 minutes wall-clock rather than open-ended.) **The safe check is `pad auth whoami`.** It returns immediately in non-interactive use, never waits on a browser, and works regardless of workspace-link state. - It reports a real user → this machine is configured AND authenticated; self-healing is safe. Run `pad workspace init` (name and `--template` are optional), then retry bootstrap. - It reports anything else — "not configured", "session expired", an error — → setup isn't finished, despite what the "no workspace linked" wording suggests. Do **not** run `pad workspace init` or `pad init` yourself. Hand it back: the user needs an interactive terminal. Stop there. ## Role Awareness Agent roles organize work by the kind of thinking it requires (planning, implementing, reviewing, researching). Items can be assigned to a (user, role) pair. Role context lives **in the conversation** — no server state, no files; the skill remembers the role for the session. **Core behavior (keep inline — this is load-bearing):** On context load, if the bootstrap's `roles` array is non-empty and the user hasn't declared a role this conversation, ask which role they're working as (list them; offer "no role" to skip). Remember it for the session, lead status/queries with it (*"Working as 🔨 Implementer — 3 items in your queue"*), auto-filter with `--role `, offer role-tagged assignments on create, and include the role in `--comment` on status changes. If the bootstrap's `playbooks` array has `status=active` entries with an `invocation_slug`, briefly surface the callable set led by intent. Never block — if the user says "no role" or no roles exist, work normally. Parse role declarations ("as implementer", "switch to reviewer", "drop role") anywhere in the input — see the **Role management** entry under Natural Language Routing. **Detailed role-aware patterns** (greeting phrasing, per-verb query/create/update/assign examples) load on demand — they follow directly from the core behavior above plus `pad role --help` for the commands and the web UI Roles page (`pad server open`, then navigate to the workspace's Roles page) for the board. ## Parse $ARGUMENTS ### No arguments Show project status conversationally. Run `pad project dashboard --format json`, and present the dashboard in a friendly, readable way — highlight what's active, what needs attention, and suggest what to work on next. If a role is active, highlight the role queue first. ### Playbook Invocation (slug routing) Playbooks are first-class invokable procedures: workspace-owned, user-editable, multi-step workflows that ship in the playbooks collection. They're the answer to "I want to do this same sequence again." Each can declare a kebab-case `invocation_slug` (e.g. `ship`, `release`, `draft-tweet`). **Natural language is the canonical way to invoke a playbook** — *"ship these tasks"*, *"cut a release"*, *"break this plan into tasks"* — and it works on every surface. The slug is a per-surface *shortcut* that resolves to the same playbook: `/pad ship` in Claude Code, `$pad ship` in Codex, `pad_playbook` with `action: run, ref: ship` via MCP, `pad playbook run ship` at the CLI. Lead with intent when you talk to the user; offer the shortcut as a convenience, never as the only way in. **Routing rule.** If the first token of the user's input — after the surface's invocation prefix, where it has one (`/pad` in Claude Code, `$pad` in Codex; MCP clients name the slug in the `pad_playbook` call directly) — is an EXACT match against a kebab-case slug from the bootstrap's `playbooks` metadata **AND that entry's `status` is `active`**, dispatch to that playbook. Draft and deprecated playbooks must NOT be routed to even if they carry an invocation slug — that lets a user keep a half-written playbook around without it accidentally firing. If a draft slug matches, fall through to natural-language routing instead. 1. Load the body: `pad playbook show --format json` (or `--format markdown` for a friendlier inline render). 2. Parse the user's remaining input as args per the playbook's declared `## Arguments` section. The agent does flexible NL parsing here ("ship PLAN-1377 squashed, no install" → `target=PLAN-1377, merge-strategy=squash, no-install=true`); the CLI does strict parsing if you'd rather pipe through it (`pad playbook run [tokens...]`). 3. Execute the steps in the body with those args bound. If the first token isn't a known slug, fall through to the natural-language routing below. **Recognizing trigger-based intent.** Even when a user doesn't type the slug, you can match by intent. The bootstrap's `playbooks` array carries each playbook's `trigger` (e.g. `on-release`, `on-implement`, `manual`). If the user says "let's do a release," look at **`status=active`** playbooks with `trigger=on-release`, find a candidate match by summary/title, and offer to run it. Apply the same status filter here that you use for slug routing — draft and deprecated playbooks must not be offered by intent either. > *"Sounds like the release playbook (PLAYB-1160). Want me to run it? It expects a `version` argument (semver, e.g. `0.5.0`). What version are you cutting?"* **Argument-binding rules.** - Required positional args first, in declared order. (CLI requires them; agent should prompt for missing required args rather than failing the call.) - `flag` type → presence (e.g. `stop-after-each`). - `enum`/`string`/`number` → `key=value` form (`merge-strategy=rebase`, `limit=3`). - `ref` → accepts issue IDs (TASK-5) or slugs. - Default-from-context (e.g. "current git branch") is the agent's job — the spec leaves these unbound and notes the source so you can compute it. **Examples.** (These show the Claude Code slug-shortcut form; the same dispatch happens when the user phrases it in natural language — *"ship PLAN-1377"* — or types the `$pad`/MCP shortcut for their surface.) - `/pad ship PLAN-1377` → dispatches to the `ship` playbook with `target=PLAN-1377`. - `/pad release 0.5.0` → dispatches to `release` with `version=0.5.0`. - `/pad draft-tweet TASK-1380 platforms=x,bluesky` → dispatches to `draft-tweet` with `parent=TASK-1380` and a platforms override. - `/pad let's discuss IDEA-3` → first token `let's` is not a kebab-case slug, so this falls through to NL routing. ### Natural Language Routing Interpret the user's intent and route to the appropriate action. Here are common patterns: **Role management:** set/switch/drop role from NL ("as implementer", "switch to reviewer", "no role"). Inspect via `pad role list`. Create via `pad role create "Name" --description "..." --icon "🔨"`. Assign via `pad item update --role --assign `. For "show me the role board" / "who's working on what?", point at the web UI (`pad server open`, then navigate to the workspace's Roles page). **Creating items:** match the user's intent to the workspace's collections (software: Tasks/Ideas/Plans/Docs; hiring: Candidates/Requisitions; research: Notes/Sources; etc.). "I have an idea for X" → Idea, "new task: fix Y" → Task, "document Z" → Doc. **Querying:** - "what's on my plate?" → role-filtered queue if a role is active, otherwise `pad project next` - "remind me about this on " / "revisit TASK-5 next Tuesday" → `pad item remind` (IDEA-2641). The time is an **instant**, not a date — ask for a time of day rather than picking one, since the server refuses a bare date on purpose. A fired reminder shows up in `pad project next` / `ready` until someone runs `pad item ack ` — `next` prints the exact ack command under the entry, so you never have to go looking for the id; **finishing the item does not acknowledge it**, because a reminder is often armed precisely to fire after the work is done - "what should I work on?" / "what's ready?" → `pad project ready` (actionable backlog); "what's stuck?" / "what needs attention?" → `pad project stale` - "show me status" / "how are we doing?" → `pad project dashboard` - "show me all tasks" / "list bugs" → `pad item list ` - "find anything about X" → `pad item search "X"` **Updating:** `pad item update --status X --comment "..."` — **always** include `--comment` on status changes to explain *why*. The audit trail is the whole point. Same pattern for priority/role/assign changes. **Working with attachments:** items reference attachments as `![alt](pad-attachment:)` (images) or `[label](pad-attachment:)` (files). To inspect or read bytes, always use `pad attachment {list|show|view|upload|download}`. `view ` writes the bytes to a temp file and prints the path — compose with `IMG=$(pad attachment view )`, then open it with whatever the platform has (`open "$IMG"` on macOS, `xdg-open "$IMG"` on Linux) or just read/describe the file directly. **Hard rule for agents:** NEVER read directly from `~/.pad/attachments/`. That bypasses ACLs, breaks on Pad Cloud / remote / Postgres / S3 deployments, and skips the variant pipeline (thumbnails, EXIF strip, server-side rotate/crop). Always go through the CLI. **Planning:** - "let's create a plan" → run the **plan** playbook (NL is the canonical entry; the `/pad plan ` slug is the Claude-Code shortcut). Activate via library if the bootstrap's `playbooks` array lacks `invocation_slug=plan, status=active`. - "break plan 2 into tasks" → run the **decompose** playbook on PLAN-2 (shortcut: `/pad decompose PLAN-2`; same activation story) - "break SPEC-1 into tasks" → same playbook, targeting SPEC-1 instead (shortcut: `/pad decompose SPEC-1`) — spec-driven workspaces decompose specs the same way - "what's blocking us?" → Analyze open items and dependencies **Ideation:** - "let's brainstorm about X" → Multi-step ideation workflow (see below) - "what if we added X?" → Discuss, then offer to capture as an Idea **Dependencies:** `pad item deps ` to inspect; `pad item block ` / `blocked-by ` / `unblock ` to mutate. **Reports:** `pad project standup` ("prep for standup" / "what did we do?"); `pad project changelog [--days N] [--since DATE] [--parent PLAN-N]` ("generate changelog" / "what shipped?"). **Recent activity:** `pad project activity [--limit N] [--actor user|agent] [--since DATE]` ("what changed?" / "what did other agents do since I last worked?") — non-streaming snapshot of the workspace activity feed (`pad_project action=activity` via MCP). **Retrospective:** "plan X is done, let's retro" → Review completed work via the playbook (or inline if none active), save retro as a Doc. **Onboarding:** - "set up my workspace" / "onboard me" / "scan this codebase" → **first check that a workspace is actually linked.** If bootstrap failed, none of what follows can run — the playbook lives IN a workspace, so `pad playbook show onboard` fails the same way bootstrap did, and sending the agent to load it is a dead end. Resolve the link first using the stderr branch in **Context Loading** above (whoami-gated self-heal, or hand back to the user for an interactive terminal), then come back here. **Once a workspace is linked**, **run the onboard playbook.** Natural language is the canonical trigger and works on every surface; the slug shortcuts (`/pad onboard` in Claude Code, `$pad onboard` in Codex, the `pad_onboard` MCP prompt) are equivalent entry points into the same playbook. First ensure it's active: if the bootstrap's `playbooks` array lacks `invocation_slug=onboard, status=active` but an onboard entry EXISTS in draft/deprecated, reactivate it in place (`pad item update PLAYB-N --field status=active`) — `invocation_slug` is workspace-unique, so activating from the library beside an existing entry duplicates or fails on the slug; only library-activate (`pad library activate "Onboard a workspace"`) when no entry exists at all. THEN load the body and follow it: `pad playbook show onboard --format markdown` (CLI) or `pad_playbook` with `action: get` (MCP). The pla