reliquary/plugins/spire/skills/workpad/SKILL.md

name, description

name

description

workpad

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.