From e92a8f4be0c14ee2a9ba69cf855efa2ce2d6f6b2 Mon Sep 17 00:00:00 2001
From: Alex Dunmow <alex.dunmow@millcrest.com.au>
Date: Fri, 12 Jun 2026 13:51:20 +0800
Subject: [PATCH] first commit

---
 README.md                              |  25 ++
 developing-blockninja-plugins/SKILL.md |  60 +++
 fleet/SKILL.md                         |  39 ++
 grill-with-docs/ADR-FORMAT.md          |  35 ++
 grill-with-docs/CONTEXT-FORMAT.md      |  30 ++
 grill-with-docs/SKILL.md               |  88 +++++
 shipit/SKILL.md                        |  32 ++
 star-response-builder/SKILL.md         | 509 +++++++++++++++++++++++++
 workorder/SKILL.md                     |  61 +++
 9 files changed, 879 insertions(+)
 create mode 100644 README.md
 create mode 100644 developing-blockninja-plugins/SKILL.md
 create mode 100644 fleet/SKILL.md
 create mode 100644 grill-with-docs/ADR-FORMAT.md
 create mode 100644 grill-with-docs/CONTEXT-FORMAT.md
 create mode 100644 grill-with-docs/SKILL.md
 create mode 100644 shipit/SKILL.md
 create mode 100644 star-response-builder/SKILL.md
 create mode 100644 workorder/SKILL.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..137d268
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# skills
+
+Personal Claude Code skills, source of truth for `~/.claude/skills/`.
+
+Each skill directory here is symlinked back into place:
+
+```
+~/.claude/skills/<name> -> ../../src/skills/<name>
+```
+
+## Skills
+
+- **developing-blockninja-plugins** — creating, building, and publishing BlockNinja CMS plugins/themes
+- **fleet** — apply a change across many BlockNinja repos with per-repo verification
+- **grill-with-docs** — stress-test a plan against the domain model and update docs inline
+- **shipit** — full BlockNinja plugin/theme pre-publish pipeline
+- **star-response-builder** — turn experience/achievements into STAR-style responses
+- **workorder** — generate numbered work-order documents (WO-NNN)
+
+## Adding a skill
+
+```sh
+mkdir ~/src/skills/<name>          # write SKILL.md inside
+ln -s ../../src/skills/<name> ~/.claude/skills/<name>
+```
diff --git a/developing-blockninja-plugins/SKILL.md b/developing-blockninja-plugins/SKILL.md
new file mode 100644
index 0000000..76ce00a
--- /dev/null
+++ b/developing-blockninja-plugins/SKILL.md
@@ -0,0 +1,60 @@
+---
+name: developing-blockninja-plugins
+description: Use when creating, modifying, building, or publishing BlockNinja CMS plugins or themes — work in plugins/* repos, plugin registration, blocks, templates, plugin Connect services, migrations, ninja plugin commands, check-safety for plugins, or block/core SDK usage in standalone plugin repos.
+---
+
+# Developing BlockNinja Plugins
+
+## Overview
+
+Never write plugin code from memory — every SDK symbol is locally verifiable. Truth lives at:
+
+- **SDK source:** `~/src/blockninja/core` — import prefix `git.dev.alexdunmow.com/block/core/...` is the ONLY one allowed; never `block/cms/...`
+- **Canonical guide:** `~/src/blockninja/cms/docs/PLUGIN_DEVELOPMENT.md`
+- **Publish workflow + hard rules:** `~/src/blockninja/plugins/CLAUDE.md`
+- **Exemplars:** `plugins/messenger` (compact), `plugins/symposium` (service-heavy: RPC, jobs, AI, embeddings)
+
+Core-vs-plugin: platform-wide behavior → core; domain-specific or owns its own data/UI → plugin (decision table in PLUGIN_DEVELOPMENT.md).
+
+## Doc routing
+
+| Working on | Read first (under `cms/docs/`) |
+|---|---|
+| Scaffold, registration, blocks, `CoreServices` | PLUGIN_DEVELOPMENT.md |
+| Public HTTP routes (webhooks, widgets) | PLUGIN_HTTP_HANDLERS.md |
+| Load/Unload, runtime state, goroutines | PLUGIN_LIFECYCLE_HOOKS.md |
+| Themes, templates, master pages, CSS | TEMPLATE_PLUGINS.md |
+| Block editor / settings UI (Module Federation) | PLUGIN_EDITOR_SDK.md |
+| .so build pipeline, loader internals | compiled-plugin-architecture.md |
+| Release, registry, install | `plugins/CLAUDE.md` (not cms/docs) |
+
+## Verifying SDK symbols
+
+Before using an unfamiliar SDK call, check: (1) the pinned SDK the build compiles against — `go doc git.dev.alexdunmow.com/block/core/plugin CoreServices` from the plugin dir; (2) nearest exemplar usage in messenger/symposium; (3) the CMS-side implementation in `cms/backend` for semantics.
+
+**Missing capability** ⇒ two sanctioned paths only: extend `block/core` (long-term; needs SDK release + re-pin + image rebuild), or vendor the cms-internal package into the plugin's `internal/` with a provenance header (established convention — check-safety vendors cms `internal/theme` this way). NEVER `replace` directives; NEVER `block/cms` imports.
+
+**Version pinning:** `go.mod` pins `block/core` to exactly what the CMS uses:
+`grep 'block/core ' ~/src/blockninja/cms/backend/go.mod`
+
+## Gates — run before commit / bump / publish
+
+```bash
+make                          # CGO build; templ/sqlc drift surfaces here
+cd ~/src/blockninja/check-safety && go run . <plugin-path>   # MUST exit 0
+make archive-check            # proves `git archive HEAD` (= what publish ships) compiles
+```
+
+check-safety traps: plugin `web/` lint extends `../../../cms/web/eslint.config.js`, so it only runs from the canonical sibling layout; raw `<button>` in plugin UI fails (use `@block-ninja/ui` Button); `any` usage warns.
+
+## Release traps
+
+```bash
+ninja plugin bump patch       # commits plugin.mod — does NOT git-tag
+git tag vX.Y.Z                # manual; must equal plugin.mod version (hard rule 6)
+git push origin main vX.Y.Z   # explicit — --follow-tags skips lightweight tags
+ninja plugin publish          # ships `git archive HEAD`: untracked files DON'T ship;
+                              # web/dist and ALL generated Go must be committed
+```
+
+New plugin: `ninja plugin init`, minimal files per PLUGIN_DEVELOPMENT.md §Minimal Layout, copy the Makefile from messenger. First publish lands `private`; review via orchestrator dashboard.
diff --git a/fleet/SKILL.md b/fleet/SKILL.md
new file mode 100644
index 0000000..25cfd4a
--- /dev/null
+++ b/fleet/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: fleet
+description: Apply a change across many BlockNinja repos at once (plugins/*, sites/*, themes/*, optionally cms/core/orchestrator) with per-repo build + check-safety verification, committing only green repos and reporting only red lanes. Use for core version bumps, fleet-wide migrations, mass mechanical edits, or any "do X in every repo" request.
+---
+
+# Fleet Runner
+
+Multi-repo batch executor for the BlockNinja workspace. Turns "migrate all N repos" into: enumerate → confirm → fan out → verify per repo → commit green → report red.
+
+## Process
+
+1. **Enumerate targets.** Default fleet: every git repo under `~/src/blockninja/plugins/`, `~/src/blockninja/sites/`, `~/src/blockninja/themes/` (skip non-repos), plus any explicitly named (cms, core, orchestrator, app). Print the list with current branch + dirty/clean state and **confirm with the user before touching anything** — especially flag dirty repos (their in-flight work must be preserved, never stashed or reset).
+2. **Define the per-repo recipe** from the instruction. A recipe is: the edit (e.g. bump `block/core` in go.mod + `go mod tidy`), the verify chain, and the commit message template. State the recipe and the 2-3 key assumptions before fanning out.
+3. **Fan out one subagent per repo** — `model: "sonnet"` (house rule for mechanical fan-outs), parallel batches. Each agent must:
+   - Read that repo's `CLAUDE.md` first and obey it (build commands differ per repo).
+   - Apply the change. Grep for leftover old names/versions across the WHOLE repo (frontend AND backend) — partial migrations are the #1 fleet failure mode.
+   - Verify: `make` (or `go build ./...` if no Makefile), then `cd ~/src/blockninja/check-safety && go run . <repo>` for cms/plugins/sites/themes repos — must exit 0.
+   - Hard rules: no `replace` directives in go.mod, ever; sqlc only (no raw SQL); stage explicit paths only.
+   - Commit ONLY if everything is green, in that repo alone (never cross-repo commits). Re-check `git branch --show-current` first. Do not push unless the instruction says to.
+   - Return: repo, green|red, evidence (exact command + last lines of output), and for red: root cause + proposed fix.
+4. **Consolidated report**: one line per green repo (commit hash + evidence ref); full detail ONLY for red lanes. Never claim fleet success while any lane is red or unverified.
+5. **Red-lane remediation**: offer to fix red lanes serially (these usually need real debugging, not mechanical edits).
+
+## Headless alternative
+
+For very large or repeatable sweeps, generate a script the user can run instead:
+
+```bash
+for repo in $(ls -d ~/src/blockninja/plugins/*/ ~/src/blockninja/sites/*/); do
+  (cd "$repo" && claude -p "<recipe>. Verify with make + check-safety; commit only if green." \
+     --allowedTools "Edit,Read,Bash,Grep,Glob")
+done
+```
+
+## Never
+
+- Never stash/reset a dirty repo to make the migration apply. Report it as skipped-dirty instead.
+- Never bundle multiple repos into one commit.
+- Never report "all done" from build success alone when the instruction implies runtime behavior — label runtime claims verified/unverified explicitly.
diff --git a/grill-with-docs/ADR-FORMAT.md b/grill-with-docs/ADR-FORMAT.md
new file mode 100644
index 0000000..b91baa8
--- /dev/null
+++ b/grill-with-docs/ADR-FORMAT.md
@@ -0,0 +1,35 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
diff --git a/grill-with-docs/CONTEXT-FORMAT.md b/grill-with-docs/CONTEXT-FORMAT.md
new file mode 100644
index 0000000..a9225b7
--- /dev/null
+++ b/grill-with-docs/CONTEXT-FORMAT.md
@@ -0,0 +1,30 @@
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A one or two sentence description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others under `_Avoid_`.
+- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does.
+- **Only include terms specific to this project's context.** General programming concepts don't belong.
+- **Group terms under subheadings** when natural clusters emerge.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts.
diff --git a/grill-with-docs/SKILL.md b/grill-with-docs/SKILL.md
new file mode 100644
index 0000000..94b79dd
--- /dev/null
+++ b/grill-with-docs/SKILL.md
@@ -0,0 +1,88 @@
+---
+name: grill-with-docs
+description: Grilling session that challenges your plan against the existing domain model, sharpens terminology, and updates documentation (CONTEXT.md, ADRs) inline as decisions crystallise. Use when user wants to stress-test a plan against their project's language and documented decisions.
+---
+
+## <what-to-do>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each question before continuing.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
+
+## </what-to-do>
+
+## <supporting-info>
+
+### Domain awareness
+
+During codebase exploration, also look for existing documentation:
+
+#### File structure
+
+Most repos have a single context:
+
+```
+/
+├── CONTEXT.md
+├── docs/
+│   └── adr/
+│       ├── 0001-event-sourced-orders.md
+│       └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+If a `CONTEXT-MAP.md` exists at the root, the repo has multiple contexts. The map points to where each one lives:
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/
+│   └── adr/                          ← system-wide decisions
+├── src/
+│   ├── ordering/
+│   │   ├── CONTEXT.md
+│   │   └── docs/adr/                 ← context-specific decisions
+│   └── billing/
+│       ├── CONTEXT.md
+│       └── docs/adr/
+```
+
+Create files lazily — only when you have something to write. If no `CONTEXT.md` exists, create one when the first term is resolved. If no `docs/adr/` exists, create it when the first ADR is needed.
+
+### During the session
+
+#### Challenge against the glossary
+
+When the user uses a term that conflicts with the existing language in `CONTEXT.md`, call it out immediately. "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+#### Sharpen fuzzy language
+
+When the user uses vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User? Those are different things."
+
+#### Discuss concrete scenarios
+
+When domain relationships are being discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
+
+#### Cross-reference with code
+
+When the user states how something works, check whether the code agrees. If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?"
+
+#### Update CONTEXT.md inline
+
+When a term is resolved, update `CONTEXT.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
+
+`CONTEXT.md` should be totally devoid of implementation details. Do not treat `CONTEXT.md` as a spec, a scratch pad, or a repository for implementation decisions. It is a glossary and nothing else.
+
+#### Offer ADRs sparingly
+
+Only offer to create an ADR when all three are true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will wonder "why did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
+
+## </supporting-info>
diff --git a/shipit/SKILL.md b/shipit/SKILL.md
new file mode 100644
index 0000000..9df8434
--- /dev/null
+++ b/shipit/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: shipit
+description: Run the full BlockNinja plugin/theme pre-publish pipeline — clean-tree check, make, archive-check, check-safety, version bump, tag, push, ninja plugin publish, registry verification — halting at the first failure with evidence. Use when publishing a plugin or theme version, or when asked to "ship" or "release" a plugin.
+args: "[patch|minor|major] (default: patch)"
+---
+
+# Ship It — Plugin Publish Pipeline
+
+Executes the mandatory pre-publish checklist from `plugins/CLAUDE.md` as a single halting pipeline. Run from (or pointed at) a plugin/theme repo under `~/src/blockninja/plugins/` or `~/src/blockninja/themes/`.
+
+## Pipeline (halt at first failure; report each step verified-with-evidence)
+
+1. **Clean tree**: `git status --porcelain` must be empty (untracked files won't ship — `ninja plugin publish` ships `git archive HEAD`). If dirty: stop and show what's uncommitted; never auto-stage.
+2. **Branch check**: `git branch --show-current` — must be `main`.
+3. **Build**: `make` — the `.so` must compile (CGO). Stale `*_templ.go` is the usual failure: run `make templ`, commit, retry once.
+4. **Archive check**: `make archive-check` must exit 0 (proves a clean `git archive HEAD` compiles — exactly what publish ships). If the Makefile lacks the target, flag it instead of skipping.
+5. **Safety**: `cd ~/src/blockninja/check-safety && go run . <plugin-path>` must exit 0. Fix violations; never baseline, skip, or defer.
+6. **Generated-files policy spot-check**: confirm committed `web/dist` (if the plugin has one) is fresh — rebuilt this session or newer than the newest `web/src` file. A stale tracked dist gets silently embedded.
+7. **Bump**: `ninja plugin bump <patch|minor|major>` (from args; default patch). This edits plugin.mod and commits but does NOT tag.
+8. **Tag + push**: `git tag vX.Y.Z` matching the new plugin.mod version, then `git push origin main vX.Y.Z` (push the tag explicitly — `--follow-tags` skips lightweight tags).
+9. **Publish**: `ninja plugin publish` (add `--channel <c>` or `--private` if the user said so).
+10. **Verify**: `ninja plugin version` must show the new version in the registry. This is the runtime evidence — without it the publish is **unverified**.
+
+## Report format
+
+One line per step: `✓ <step> — <evidence (exact command + key output line)>` or `✗ <step> — <failure + root cause + what to fix>`. Stop at ✗; everything after is "not run".
+
+## Notes
+
+- Theme repos: `kind = "theme"` in plugin.mod (DB CHECK constraint rejects "plugin").
+- Version source of truth is plugin.mod; tag must match exactly.
+- First-ever publish of a new plugin needs `ninja plugin init` + registry review flow — see `plugins/CLAUDE.md`; this skill covers subsequent versions.
diff --git a/star-response-builder/SKILL.md b/star-response-builder/SKILL.md
new file mode 100644
index 0000000..2556aa0
--- /dev/null
+++ b/star-response-builder/SKILL.md
@@ -0,0 +1,509 @@
+---
+name: star-response-builder
+description: Use when turning the user's experience, achievements, incidents, project examples, or interview notes into STAR-style responses — job applications, public sector/APS selection criteria, two-page pitches, capability statements, cover letters, behavioural interview answers, promotion applications, performance reviews, or resume bullet points.
+---
+
+# STAR Response Builder
+
+## Purpose
+
+Use this skill to help the user turn experience, achievements, incidents, project examples, interview notes, or job application material into clear STAR-style responses.
+
+STAR means:
+
+* **Situation**: The context, challenge, or opportunity.
+* **Task**: The user's specific responsibility or objective.
+* **Action**: What the user personally did.
+* **Result**: What changed because of the user's work.
+
+STAR is not just a template. It is a way of presenting credible evidence: context, accountability, action, and impact.
+
+This skill is especially useful for:
+
+* job applications
+* public sector selection criteria
+* APS/state government pitches
+* cover letters
+* behavioural interview answers
+* promotion applications
+* performance reviews
+* resumes
+* leadership examples
+* capability statements
+* stakeholder, delivery, conflict, initiative, communication, problem-solving, resilience, and accountability examples
+
+## Core Rule
+
+Always produce a usable draft first.
+
+Do not stop because information is incomplete. Make a reasonable draft using what the user has provided, then briefly identify what details would strengthen it.
+
+## STAR Structure
+
+When given raw information, separate the material into:
+
+### Situation
+
+Set the scene briefly.
+
+Identify:
+
+* where the example occurred
+* when it happened
+* what was happening
+* what problem, risk, pressure, or opportunity existed
+
+Keep this short. The Situation should not become a project briefing.
+
+### Task
+
+Clarify the user's specific responsibility.
+
+Identify:
+
+* what the user was accountable for
+* what needed to be delivered, fixed, improved, resolved, or decided
+* whether the user led, coordinated, advised, challenged, delivered, or supported the work
+
+The Task should distinguish the user's personal role from the broader team objective.
+
+### Action
+
+Describe what the user personally did.
+
+This is the most important section.
+
+Identify:
+
+* the steps the user took
+* the decisions they made
+* the stakeholders they engaged
+* the analysis, planning, negotiation, escalation, governance, or delivery work they performed
+* the judgement they applied
+* the methods, frameworks, tools, policies, or processes they used
+
+Use first-person active verbs:
+
+* I led
+* I clarified
+* I designed
+* I rebuilt
+* I negotiated
+* I coordinated
+* I challenged
+* I simplified
+* I prioritised
+* I resolved
+* I delivered
+* I identified
+* I escalated
+* I implemented
+* I improved
+* I reduced
+* I prevented
+* I drafted
+* I presented
+* I facilitated
+* I reviewed
+
+Avoid weak phrasing unless the user's role was genuinely minor:
+
+* helped with
+* was involved in
+* worked on
+* assisted in
+* participated in
+* contributed to
+
+Replace weak phrasing with clearer ownership wherever the facts support it.
+
+### Result
+
+Show what changed because of the user's work.
+
+Identify:
+
+* what was delivered
+* what improved
+* what risk was reduced
+* what decision was enabled
+* what process was adopted
+* what was approved, implemented, reused, or recognised
+* what became clearer, faster, safer, more reliable, or more accountable
+
+Use metrics where they are real and defensible.
+
+Good result evidence includes:
+
+* cost savings
+* time reductions
+* service improvements
+* compliance outcomes
+* reduced ambiguity
+* increased stakeholder confidence
+* faster decision-making
+* approval by senior stakeholders
+* adoption of a process
+* repeat use of the work
+* formal feedback
+* ministerial, executive, board, or panel endorsement
+
+Avoid vague endings such as:
+
+* successful outcome
+* positive feedback
+* stakeholders were happy
+* the project went well
+* this was well received
+
+If no metric exists, describe the concrete impact honestly.
+
+## STAR Proportions
+
+For selection criteria, behavioural examples, and public sector responses, use these rough proportions:
+
+* **Situation:** 15%
+* **Task:** 10%
+* **Action:** 50%
+* **Result:** 25%
+
+The Action should do most of the work.
+
+Most weak responses spend too long explaining the background and not enough time showing what the applicant personally did.
+
+For a 250-word response, aim roughly for:
+
+* 35–40 words of Situation
+* 20–30 words of Task
+* 120–130 words of Action
+* 55–65 words of Result
+
+For a 500-word response, scale the same proportions.
+
+Use these proportions as a guide, not a rigid formula.
+
+If the Situation is more than a quarter of the answer, it is probably too long.
+
+## Public Sector and Job Advert Responses
+
+When writing a job advert response, selection criterion, capability statement, cover letter, two-page pitch, or public sector application, do **not** use visible STAR headings unless the user explicitly asks for them.
+
+Do not write:
+
+**Situation:**
+**Task:**
+**Action:**
+**Result:**
+
+Instead, use STAR as the hidden structure underneath the response and weave it into polished prose.
+
+The response should still contain:
+
+* brief context
+* clear personal accountability
+* specific actions
+* concrete result or impact
+
+But it should read like a natural application response, not a template.
+
+### Public Sector Default
+
+For public sector applications:
+
+1. Write in first person.
+2. Use "I", not "we", when describing the user's contribution.
+3. Keep the context brief.
+4. Make the user's responsibility obvious.
+5. Spend most of the word count on Action.
+6. Show judgement, not just activity.
+7. Name decisions, deliverables, risks, processes, stakeholders, governance steps, or outcomes where useful.
+8. Finish with a specific and credible result.
+9. Avoid inflated or suspiciously precise metrics.
+10. Do not expose STAR headings unless requested.
+
+### Public Sector Tone
+
+The tone should be:
+
+* professional
+* specific
+* credible
+* active
+* plain English
+* evidence-based
+* calm and competent
+
+Avoid:
+
+* buzzwords
+* overblown claims
+* fake metrics
+* corporate sludge
+* generic capability language
+* vague claims about teamwork
+* language that makes the user sound passive
+
+Bad:
+
+> I worked with stakeholders to achieve a successful outcome.
+
+Better:
+
+> I convened weekly meetings with operational, technical, and executive stakeholders, clarified the decision points, documented the risks, and prepared a recommended approach for endorsement.
+
+## Individual Selection Criteria
+
+For individual selection criteria responses, use one clear example per criterion unless the user asks for a broader summary.
+
+Default length:
+
+* 250–500 words
+* first person
+* no visible STAR headings unless requested
+* action-heavy
+* specific result
+
+Each criterion should show a different capability where possible. Avoid reusing the same example for every criterion unless the user has limited material.
+
+## Two-Page Pitches
+
+For two-page public sector pitches, STAR examples should be woven into body paragraphs.
+
+Do not separate the response into STAR headings.
+
+Use a structure like:
+
+1. Short opening alignment with the role.
+2. Two to four evidence-based paragraphs, each using compressed STAR logic.
+3. Short closing paragraph reinforcing fit, motivation, and value.
+
+In a pitch, STAR often compresses into CAR:
+
+* **Context**
+* **Action**
+* **Result**
+
+The pitch should feel like a coherent argument for suitability, not a list of disconnected examples.
+
+## Behavioural Interviews
+
+For behavioural interview answers, visible STAR structure is acceptable if useful, but the spoken answer should still sound natural.
+
+Default structure:
+
+1. Brief context.
+2. Clear statement of responsibility.
+3. Step-by-step explanation of what the user did.
+4. Specific result.
+5. Optional reflection or lesson learned.
+
+For interviews, prepare:
+
+### Short Version
+
+45–60 seconds.
+
+### Standard Version
+
+Around 90 seconds.
+
+### Detailed Version
+
+2–3 minutes for senior roles, panels, or complex examples.
+
+The same example can be reused across:
+
+* written application
+* pitch paragraph
+* interview answer
+
+But it should be calibrated to the format, word limit, and tone.
+
+## STAR Variants
+
+Use the structure that best fits the length and purpose.
+
+### STAR
+
+Situation, Task, Action, Result.
+
+Best for:
+
+* 250–500 word selection criteria
+* behavioural interview answers
+* detailed written examples
+
+### CAR
+
+Context, Action, Result.
+
+Best for:
+
+* shorter 150–250 word responses
+* pitch paragraphs
+* cover letters
+* cases where Situation and Task naturally merge
+
+### CAO
+
+Context, Action, Outcome.
+
+Best for:
+
+* tight application paragraphs
+* softer outcome language
+* short statements where "Result" feels too rigid
+
+### STAR-L
+
+Situation, Task, Action, Result, Learning.
+
+Best for:
+
+* senior roles
+* leadership examples
+* reflective practice questions
+* EL2/SES-style responses
+* examples where the result was mixed and the learning matters
+
+Use one structure consistently across a single application. Mixing structures can make the response feel disorganised.
+
+## Handling Missing Information
+
+If details are missing, make a cautious draft.
+
+Do not invent:
+
+* agencies
+* dates
+* dollar figures
+* percentages
+* senior endorsements
+* formal recognition
+* project values
+* team sizes
+* outcomes that were not provided
+
+Use placeholders only when necessary.
+
+Acceptable cautious result language:
+
+* "This improved visibility over…"
+* "This reduced ambiguity around…"
+* "This gave stakeholders a clearer basis for…"
+* "This helped prevent…"
+* "This created a repeatable process for…"
+* "This supported more consistent decision-making…"
+* "This gave the team a clearer view of…"
+* "This improved confidence in…"
+
+After the draft, add:
+
+### Useful Details to Add
+
+Include only details that would materially improve the answer, such as:
+
+* specific dates or timeframe
+* agency, branch, or team
+* role level
+* stakeholder groups
+* number of people affected
+* value, scale, or risk
+* measurable improvement
+* senior feedback
+* adoption or reuse
+* final decision or approval
+
+## Default Output Formats
+
+### If the user asks for a STAR breakdown
+
+Use:
+
+**Situation:**
+[Brief context.]
+
+**Task:**
+[The user's responsibility.]
+
+**Action:**
+[What the user specifically did.]
+
+**Result:**
+[Outcome and impact.]
+
+Then provide:
+
+### Polished Version
+
+A natural first-person response suitable for use in an interview or application.
+
+### If the user asks for a job application response
+
+Do **not** use STAR headings by default.
+
+Use:
+
+### Draft Response
+
+[Polished first-person prose using STAR internally.]
+
+### Useful Details to Add
+
+[Only if needed.]
+
+### If the user asks for a public sector pitch
+
+Use:
+
+### Draft Pitch
+
+[Integrated prose, no STAR headings.]
+
+### Notes
+
+[Optional short explanation of evidence, gaps, or strengthening opportunities.]
+
+## Quality Checklist
+
+Before finalising, check that the answer:
+
+* has clear context
+* identifies the user's personal responsibility
+* uses "I" rather than hiding behind "we"
+* spends most of the space on Action
+* shows judgement and decision-making
+* avoids vague claims
+* includes a result or impact
+* uses real numbers only where defensible
+* matches the seniority of the role
+* sounds natural and credible
+* avoids visible STAR headings for job advert/application responses unless requested
+
+## Example: Visible STAR Breakdown
+
+Use this format only when the user asks for STAR explicitly.
+
+**Situation:**
+The organisation was relying on a dashboard that was difficult to interpret and was creating confusion for stakeholders.
+
+**Task:**
+I was responsible for improving the reporting so users could understand the key information quickly and make decisions with more confidence.
+
+**Action:**
+I reviewed the existing dashboard, identified the areas causing confusion, and worked with stakeholders to clarify what information they actually needed. I simplified the layout, removed unnecessary elements, standardised the metrics, and rebuilt the reporting view around the decisions users needed to make.
+
+**Result:**
+The revised dashboard gave stakeholders a clearer and more consistent view of performance. It reduced confusion, improved confidence in the reporting, and created a more usable basis for operational discussion.
+
+## Example: Same Content Woven Into a Job Application Response
+
+Use this format for job adverts, selection criteria, public sector applications, and pitches unless visible STAR headings are requested.
+
+In my role at [organisation], I identified that stakeholders were relying on reporting that was difficult to interpret and was creating confusion around operational priorities. I was responsible for improving the reporting so decision-makers could understand the key information more quickly and use it with greater confidence. I reviewed the existing dashboard, clarified stakeholder requirements, removed unnecessary detail, standardised the metrics, and rebuilt the report around the decisions it needed to support. This improved visibility, reduced ambiguity, and gave stakeholders a clearer basis for operational discussion.
+
+## Final Instruction
+
+Always make the user sound specific, credible, and personally accountable.
+
+For job applications, STAR should usually be invisible scaffolding, not visible headings.
diff --git a/workorder/SKILL.md b/workorder/SKILL.md
new file mode 100644
index 0000000..54097e8
--- /dev/null
+++ b/workorder/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: workorder
+description: Generate numbered work-order documents (WO-NNN) for a goal or program of work — the BlockNinja works/ convention with phases, dependencies, task checklists, acceptance criteria, and evidence requirements. Use when the user asks for work orders, a WO set, or to break a spec/goal into trackable execution units.
+---
+
+# Work Order Generator
+
+Produce work-order markdown files matching the established convention (see `sites/bidmasters/docs/works/` for canon). One WO per coherent unit of work; a program is a numbered series.
+
+## Process
+
+1. **Locate context**: find the governing spec (`docs/superpowers/specs/`) and any existing `works/` directory. Continue the existing WO numbering (`ls works/ | sort` — next number). If no works/ dir exists, ask where to put it (default: `docs/works/`).
+2. **Decompose the goal** into WOs sized so each is independently completable and verifiable. Order by dependency; assign phases.
+3. **Write each WO** using the exact format below.
+4. **Update or create `works/README.md`** index: table of WO number, title, phase, status, dependencies.
+5. Commit the documents (house rule: plan/work docs are always committed, never left untracked).
+
+## WO Format (exact)
+
+```markdown
+# WO-NNN: <Title>
+
+**Phase:** <N>
+**Status:** TODO | IN PROGRESS | BLOCKED | DONE
+**Spec:** [<relative link>](<relative link>)
+**Repos:** <repo names touched>
+**Depends on:** <WO-NNN list or "—">
+
+## Overview
+
+<2-4 sentences: what this delivers and why. Name the user-visible outcome.>
+
+## Tasks
+
+### <Subsystem / file-area heading>
+
+- [ ] <concrete task with file paths where known>
+- [ ] <...>
+
+### <Next subsystem>
+
+- [ ] <...>
+
+## Acceptance Criteria
+
+- [ ] <observable behavior, stated so a reviewer can check it without reading code>
+- [ ] <...>
+
+## Evidence Required
+
+- <exact command(s) to run and the expected output — build, test, check-safety, curl, screenshot>
+- <runtime proof required before Status may be set to DONE; "verified" means evidence captured in the WO or commit message, not asserted>
+```
+
+## Rules
+
+- Tasks reference real file paths (verify they exist; mark new files "(new)").
+- Every WO ends with check-safety in Evidence Required when it touches cms, plugins/*, sites/*, or themes/* (mandated gate).
+- Acceptance criteria are behaviors, not task restatements.
+- Status changes to DONE only with evidence captured — claims without runtime proof stay IN PROGRESS.
+- Keep WOs small enough that one agent session can complete one WO with margin.