📦 convert repo to Claude Code plugin
Move skills/ to repo root and add .claude-plugin/{plugin,marketplace}.json
so the skills can be installed in other projects via a local marketplace.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: workpad
|
||||
description: Decides WHERE and WHEN to put working documents — reports, plans, goals, brainstorms, designs, journals, research, specs, tickets, bug notes. Use this skill whenever the user asks you to write a "report", "plan", "goal", "brainstorm", "design", "journal", "research note", "spec", or anything "in the workpad" — and also when another skill is about to drop a markdown file somewhere ad-hoc (e.g. a `superpowers/` subdirectory, the repo root, `/tmp`, or alongside source code). If a workpad exists, the workpad wins. This skill steers other skills toward a single, predictable place for thinking-in-markdown so the user can always find what was written and when.
|
||||
---
|
||||
|
||||
# Workpad
|
||||
|
||||
The workpad is the user's filing cabinet for thinking-in-markdown. Reports, plans, brainstorms, post-mortems — anything that is *about* the work rather than *being* the work — lives here. This skill answers two questions only: **where** does a given document go, and **when** is one kind of document the right kind versus another. It does not tell you how to write the contents.
|
||||
|
||||
Treat this skill as authoritative for placement. If another skill suggests writing a markdown artifact to its own scratch directory (a `superpowers/` folder, a sibling `notes/` dir, the repo root, etc.), prefer the workpad instead. A single predictable location is more valuable than each skill having its own.
|
||||
|
||||
## Where the workpad lives
|
||||
|
||||
Resolve the workpad base directory in this order — stop at the first hit:
|
||||
|
||||
1. **Explicit user instruction in the current conversation.** If they said "put it in `~/notes/foo`", that wins.
|
||||
2. **`WORKPAD_FOLDER` environment variable.** Reading it reliably is fiddly because Claude Code runs commands in subshells that may not inherit the user's interactive env, and the value may live in a project-local `.env` file rather than the actual environment. Try, in order:
|
||||
- `uv run --quiet --with python-dotenv python -c "from dotenv import load_dotenv; import os; load_dotenv(); print(os.environ.get('WORKPAD_FOLDER',''))"` if `uv` is available. This loads `.env` from the current working directory before reading the variable, which catches the common case where `WORKPAD_FOLDER` is set per-project in a `.env`.
|
||||
- `just workpad-folder` (or any equivalent recipe) if a `.justfile` / `justfile` is present and defines one — `just` loads `.env` automatically.
|
||||
- `printenv WORKPAD_FOLDER` as a last resort. This will only see values exported into the actual process environment, not values in `.env` files.
|
||||
If any of these prints a non-empty path, treat it as the workpad base.
|
||||
3. **Project-local ticket folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../<repo>-tickets/` or a path the user has mentioned before). If such a folder is configured for this project, prefer placing the workpad inside it (e.g. `<ticket-folder>/workpad/`). When in doubt whether one exists, ask.
|
||||
4. **`/docs/workpad`** at the project root, if a `/docs` folder already exists.
|
||||
5. **Otherwise: ask.** If there is no `/docs` folder and no other signal, do not silently create `/docs/workpad/`. Ask the user where the workpad should live, and confirm before creating any folders.
|
||||
|
||||
## Folder structure
|
||||
|
||||
The workpad always contains at least these subfolders:
|
||||
|
||||
- `brainstorm/` — open-ended exploration, options, half-formed ideas
|
||||
- `goals/` — acceptance criteria, milestones, "what we're trying to reach"
|
||||
- `designs/` — design docs, architecture sketches, RFC-style writeups
|
||||
- `plans/` — concrete sequences of steps to execute
|
||||
- `reports/` — findings, summaries, status writeups
|
||||
|
||||
It may also contain any of these, created on demand:
|
||||
|
||||
- `archive/` — superseded or completed material moved out of the way
|
||||
- `bugs/` — bug investigations and notes
|
||||
- `journals/` — append-only narratives of long-running problems
|
||||
- `research/` — external research, library evaluations, prior art
|
||||
- `specs/` — frozen, unchanging specifications
|
||||
- `tickets/` — per-ticket scratch space
|
||||
|
||||
If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively.
|
||||
|
||||
## File naming
|
||||
|
||||
Use a `YYYY-MM-DD-hh-` prefix on filenames in `reports/` and `plans/` at minimum. The hour helps when multiple artifacts land on the same day — which is common during active work — and keeps directory listings naturally sorted by recency. Apply the same prefix to `journals/`, `bugs/`, and `research/` entries; it's almost always the right call there too. For `goals/`, `designs/`, and `specs/`, the prefix is optional — these are referred to by name more than by date, so a descriptive slug alone is fine (e.g. `goals/q2-onboarding-flow.md`, `specs/event-schema.md`).
|
||||
|
||||
After the prefix, use a short kebab-case slug describing the topic: `2026-05-05-14-auth-token-leak.md`, not `2026-05-05-14-report.md`. The slug is what the user will skim for later.
|
||||
|
||||
## When to create a subfolder
|
||||
|
||||
Single artifact → single file. Don't wrap one report in a folder.
|
||||
|
||||
Create a dated subfolder when a piece of work will produce **multiple related files** — typically a research cascade, a multi-part report with appendices, or a plan with supporting design notes that belong together. The subfolder takes the date prefix and slug; files inside it can drop the date prefix since the parent already carries it.
|
||||
|
||||
Example:
|
||||
```
|
||||
reports/
|
||||
2026-05-05-14-auth-token-leak.md ← single report
|
||||
2026-05-05-15-q2-perf-audit/ ← cascade
|
||||
overview.md
|
||||
db-findings.md
|
||||
frontend-findings.md
|
||||
recommendations.md
|
||||
```
|
||||
|
||||
## Picking the right kind of document
|
||||
|
||||
The categories overlap. These are the distinctions that matter:
|
||||
|
||||
**Plan vs. spec.** A plan is a sequence of steps you intend to take. A spec encodes something that shouldn't change — an invariant, a contract, a frozen decision. Default to `plans/`. Promote to `specs/` only when the content is meant to be referenced repeatedly as a source of truth and is not expected to be revised as work progresses.
|
||||
|
||||
**Goal vs. plan.** A goal says *what we're trying to reach* — acceptance criteria, a milestone, a story-level outcome. A plan says *how we'll get there*. If you find yourself writing "and then I'll…", you're writing a plan, not a goal.
|
||||
|
||||
**Report vs. journal.** A report is a snapshot — it can be revised as new information arrives, and the latest version is the version that matters. A journal is append-only and tells the story of a problem, including missteps, dead ends, and course corrections. Post-mortems, multi-day bug hunts, and architectural-correction narratives are journals. If the historical sequence is itself part of the value, it's a journal. If only the current conclusion matters, it's a report.
|
||||
|
||||
**Brainstorm vs. design.** A brainstorm is divergent — multiple options, tradeoffs, no commitment. A design is convergent — one approach, fleshed out enough to build from.
|
||||
|
||||
## Lifecycles
|
||||
|
||||
Most work follows one of these flows. Use them as a guide for what to create next, not as a mandatory pipeline — skip stages when they wouldn't earn their keep.
|
||||
|
||||
**Feature work:** `brainstorm → goal → design → plan`. Start with options, settle on what success looks like, design the approach, then break it into steps.
|
||||
|
||||
**Investigative or reactive work:** `report → design → plan`, or `report → plan`, or just `plan`. You usually start by reporting on what's there or what's broken; a design is only needed if the fix is non-trivial.
|
||||
|
||||
When moving between stages, create a new file in the next folder rather than mutating the previous one. The earlier artifact stays as a record of how thinking evolved.
|
||||
|
||||
## What "write a report" means by default
|
||||
|
||||
When the user says "write a report on X" without further direction:
|
||||
|
||||
1. Create a markdown file in `<workpad>/reports/` with the `YYYY-MM-DD-hh-<slug>.md` naming.
|
||||
2. Put the actual findings in the file.
|
||||
3. In your reply to the user, **summarize directly** — don't restate the whole report. Mention the file path so they can open it.
|
||||
|
||||
The same default applies to "write a plan", "draft a brainstorm", etc. — the user wants a file in the right folder plus a short verbal summary, not the file's contents pasted back into chat.
|
||||
|
||||
## Steering other skills
|
||||
|
||||
If you're operating under another skill that wants to write a markdown artifact (a research note, a design sketch, a status report), and a workpad exists or is reasonable to create, route the artifact through the workpad rather than that skill's default location. The other skill governs **what goes in the file**; this skill governs **where the file lives and what it's called**. They compose cleanly.
|
||||
|
||||
## What this skill deliberately does not cover
|
||||
|
||||
- The internal structure or formatting of reports, plans, designs, etc. That's up to the user, the project's conventions, or another skill.
|
||||
- Git workflow for workpad files (whether to commit them, branch them, etc.).
|
||||
- Tooling for searching or indexing the workpad.
|
||||
|
||||
If the user asks for help with any of those, treat it as a separate concern.
|
||||
Reference in New Issue
Block a user