111 lines
8.8 KiB
Markdown
111 lines
8.8 KiB
Markdown
---
|
|
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 plugin's own `docs/<plugin>/` 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 markdown documents, whichever plugin they come from.
|
|
---
|
|
|
|
# Workpad
|
|
|
|
The workpad holds markdown that is *about* the work rather than *being* the work: reports, plans, brainstorms, post-mortems. This skill decides **where** a document goes and **which kind** it is, not its contents. It is authoritative for placement: if another skill suggests its own scratch directory (a plugin-named folder, a sibling `notes/` dir, the repo root), use the workpad instead.
|
|
|
|
## 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 Agents run commands in subshells that may not inherit the user's interactive env, and the value may be injected on purpose not available to the agent:
|
|
- `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.
|
|
If any of these prints a non-empty path, treat it as the workpad base.
|
|
3. **Project-local tickets folder.** Some projects keep a sibling folder *outside* the main repo for per-ticket scratch (e.g. `../<repo>-tickets/` or a path configured via `GITEA_TICKETS_DIR`). If one is configured, the workpad base is `<tickets-folder>/workpad/` and individual ticket folders sit beside it as `<tickets-folder>/<id>/`. See "Ticket context" below for how those interact. When in doubt whether one exists, ask.
|
|
4. **`/docs/workpad`** at the project root, if a `/docs` folder already exists.
|
|
5. **`/.workpad`** at the project root.
|
|
6. **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, one subfolder per ticket id (see "Ticket context")
|
|
- `adepts/` — adept domain folders — see `spire:adepts`
|
|
|
|
If one of these optional folders is needed and doesn't exist yet, create it. Don't create folders speculatively. Treat unknown folders as owned by the user and ignore them.
|
|
|
|
## Ticket context
|
|
|
|
A **ticket folder** is `<workpad>/tickets/<id>/`, or `<tickets-folder>/<id>/` when the project configures an external tickets directory. It is created on demand once the id is known — no need to ask.
|
|
|
|
A ticket context is **active** when any of these holds:
|
|
|
|
- the user named the ticket for this session ("we're on #42", "start ticket 42", "this is for PROJ-17");
|
|
- a ticket skill opened or created the ticket folder earlier in this conversation;
|
|
- the user explicitly asked for a file to go into the ticket.
|
|
|
|
It is **not** active just because a ticket folder exists on disk, or the branch name contains a number. If the work smells ticket-shaped but nobody said so, ask once and stick with the answer. When several tickets have been mentioned, the most recently named one is active. Once active it stays active until the user switches or says otherwise. When you write into a ticket folder, name the ticket in your reply alongside the path.
|
|
|
|
With a ticket context active, route by kind:
|
|
|
|
- **Into the ticket folder:** `plans/`, `designs/`, `brainstorm/`, `reports/`, `bugs/`. These are about the ticket's work and should close with it.
|
|
- **Stay in the main workpad:** `journals/` (session-scoped — the narrative often outlives the ticket) and `goals/` (project-scoped — the ticket itself is the goal; don't duplicate it).
|
|
- **Judgment call:** `research/` and `specs/`. Ask: *would someone on a different ticket want this?* If yes, main workpad. If it only makes sense against this ticket's deliverable, ticket folder. When a ticket produces a spec that outlives it, promote it to the main workpad on close.
|
|
|
|
The ticket folder mirrors the workpad's kind subfolders, created on demand, same file naming including date prefixes. The ticket root holds only ticket-level files (`context.md`, etc.) — never loose plans or reports. The "when to create a subfolder" rules still apply within ticket folders (cascades of related files get their own dated subfolder).
|
|
|
|
For main-workpad files written under an active ticket context, put the ticket id in the slug (`2026-05-05-14-42-auth-token-leak.md`) so they stay findable from either side.
|
|
|
|
## 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
|
|
|
|
- **Plan vs. spec:** default to `plans/`. Promote to `specs/` only content meant as a source of truth that is not expected to be revised as work progresses.
|
|
- **Goal vs. plan:** a goal is what we're trying to reach (acceptance criteria, a milestone); a plan is how.
|
|
- **Report vs. journal:** a report is a snapshot, revised as information arrives; a journal is append-only. Post-mortems, multi-day bug hunts and architectural-correction narratives are journals.
|
|
- **Brainstorm vs. design:** options and tradeoffs, no commitment, versus one approach to build from.
|
|
|
|
## Lifecycles
|
|
|
|
Feature work: `brainstorm → goal → design → plan`. Investigative or reactive work: `report → design → plan`, `report → plan`, or just `plan`; a design only when the fix is non-trivial. Skip stages that wouldn't earn their keep. Moving between stages creates a new file in the next folder; the earlier one stays as the record.
|
|
|
|
## What "write a report" means by default
|
|
|
|
"Write a report / plan / brainstorm on X" without further direction means: a file in the right folder with the naming above, holding the findings, and a short summary in your reply with the file path, not the file's contents pasted back.
|
|
|
|
## Steering other skills
|
|
|
|
When another skill wants to write a markdown artifact and a workpad exists or is reasonable to create, route it through the workpad (including the ticket routing above). The other skill governs **what goes in the file**; this skill governs **where it lives and what it's called**.
|
|
|
|
Not covered here: the contents and format of documents, git workflow for workpad files, ticket lifecycle, and workpad search tooling.
|