diff --git a/.changeset/prototype-model-invoked.md b/.changeset/prototype-model-invoked.md new file mode 100644 index 0000000..be6c3cd --- /dev/null +++ b/.changeset/prototype-model-invoked.md @@ -0,0 +1,5 @@ +--- +"mattpocock-skills": minor +--- + +Make the **`prototype`** skill model-invoked, so the agent can reach for it autonomously (and other skills can too). Its description is rewritten around the leading word _prototype_ — throwaway code that answers a design question — with one trigger per branch (state/logic sanity-check, or UI exploration). diff --git a/README.md b/README.md index 0ba0078..ecdc99c 100644 --- a/README.md +++ b/README.md @@ -156,10 +156,10 @@ Skills I use daily for code work. - **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills. - **[to-issues](./skills/engineering/to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. - **[to-prd](./skills/engineering/to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. No interview — just synthesizes what you've already discussed. -- **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. **Model-invoked** +- **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to answer a design question — a runnable terminal app for state/logic questions, or several radically different UI variations toggleable from one route. - **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 76d6416..2dadc97 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -13,12 +13,13 @@ Reachable only when you type them (`disable-model-invocation: true`). - **[setup-matt-pocock-skills](./setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo. - **[to-issues](./to-issues/SKILL.md)** — Break any plan, spec, or PRD into independently-grabbable issues using vertical slices. - **[to-prd](./to-prd/SKILL.md)** — Turn the current conversation into a PRD and publish it to the issue tracker. -- **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype — a runnable terminal app for state/logic questions, or several toggleable UI variations. ## Model-invoked Model- or user-reachable (rich trigger phrasing so the model can reach for them). +- **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype to answer a design question: a runnable terminal app for state/logic, or several toggleable UI variations. + - **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. diff --git a/skills/engineering/prototype/SKILL.md b/skills/engineering/prototype/SKILL.md index ddebc18..9425f7d 100644 --- a/skills/engineering/prototype/SKILL.md +++ b/skills/engineering/prototype/SKILL.md @@ -1,7 +1,6 @@ --- name: prototype -description: Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. -disable-model-invocation: true +description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like. --- # Prototype diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 169809f..857f2b9 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -4,6 +4,7 @@ Skills that are still being developed. They're not ready to ship — expect roug - **[decision-mapping](./decision-mapping/SKILL.md)** — Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time. User-invoked. - **[review](./review/SKILL.md)** — Review changes since a fixed point along two parallel axes: **Standards** (does the diff follow the repo's coding standards?) and **Spec** (does the diff faithfully implement the originating issue/PRD?). +- **[wizard](./wizard/SKILL.md)** — Generate an interactive bash wizard that walks a human through a manual procedure (setup, a one-off migration, a state transition) — opening URLs, capturing values, writing `.env` and GitHub Actions secrets. User-invoked. - **[writing-beats](./writing-beats/SKILL.md)** — Shape an article as a journey of beats, choose-your-own-adventure style. Pick a starting beat, write only that beat, then pivot to the next, until the article reaches a natural end. - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step. diff --git a/skills/in-progress/decision-mapping/SKILL.md b/skills/in-progress/decision-mapping/SKILL.md index 0c42714..263c3c3 100644 --- a/skills/in-progress/decision-mapping/SKILL.md +++ b/skills/in-progress/decision-mapping/SKILL.md @@ -4,7 +4,7 @@ description: Turn a loose idea into a sequenced map of investigation tickets, th disable-model-invocation: true --- -This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or discussion. +This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or grilling. ## The Decision Map @@ -20,7 +20,8 @@ Numbered entries ("tickets"), each its own section keyed by its number: ## #1: Relational Or Non-Relational Database? Blocked by: #, # -Type: Research | Prototype | Discuss +Status: open | in-progress | resolved +Type: Research | Prototype | Grilling ### Question @@ -31,6 +32,8 @@ Type: Research | Prototype | Discuss ``` +A ticket is **unblocked** when every ticket in its `Blocked by` list is `resolved`. A session **claims** its ticket by setting `Status: in-progress` and saving the map before any work, so concurrent sessions skip it. + Each ticket must be sized to one 100K token agent session. ## Ticket Types @@ -39,46 +42,56 @@ There are three types of tickets: - **Research**: Reading documentation, third-party API's, or local resources like knowledge bases. Creates a markdown summary as an asset. Use this when knowledge outside the current working directory is required. - **Prototype**: Writing UI or logic code to test a hypothesis, or to explore a design space. Uses the /prototype skill. Creates a prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question. -- **Discuss**: Conversation with the agent. Uses the /grilling and /domain-modelling skills. The default case. +- **Grilling**: Conversation with the agent. Uses the /grilling and /domain-modelling skills. The default case. ## Fog of war -The map is _deliberately_ incomplete beyond the frontier. Your job is to investigate the frontier, and to resolve tickets in order to push the frontier forward. Push back the fog of war, one node at a time. - -At some point, the fog of war should have been pushed back far enough that the path to the finish line is clear. At that point, no more tickets will be required and the decision map can be considered 'done'. +The map is _deliberately_ incomplete beyond the frontier. Your job is to investigate the frontier, and to resolve tickets in order to push the frontier forward. Push back the fog of war, one node at a time — until the path to the finish line is clear and no tickets remain. ## Invocation -There are two ways this skill can be invoked: **bootstrap** and **resume**. +Two branches. Either way, **every session ends with a [Handoff](#handoff)** — never resolve more than one ticket per session. -### Bootstrap +### Create the map User invokes with a loose idea. -1. Run a /grilling and /domain-modelling session to surface the open decisions. +1. Run a `/grilling` and `/domain-modelling` session to surface the open decisions. 2. Write a new decision map — mostly fog, frontier identified, trivially-decidable entries resolved inline. -3. Stop. Map-building is one session's work; do not also resolve tickets. +3. Handoff. Map-building is one session's work; do not also resolve tickets. -### Resume +### Work through the map -User invokes with a path to an existing map and a ticket number. +User invokes with a path to an existing map. A ticket number is **optional** — without one, you pick the next decision, not the user. 1. Load the **whole map** as context. -2. Run a session to resolve the ticket, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modelling`. -3. Record what the session resolved in the ticket's body. -4. Add newly-discovered tickets (with correct `blocked_by` edges). -5. Stop. +2. Choose the ticket. If the user named one, use it. Otherwise pick the lowest-numbered `open` ticket that is [unblocked](#structure). [Claim it](#structure): set `Status: in-progress` and save before any work. +3. Resolve it, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modelling`. +4. Record the answer in the ticket's body and set `Status: resolved`. +5. Add newly-discovered tickets with correct `Blocked by` edges. If the decisions made invalidate other parts of the map, update or delete those nodes. +6. Handoff. -If the decisions made invalidate other parts of the map, update or delete those nodes. +The user may run unblocked tickets in parallel, so expect other agents to be editing the map in their own sessions. -## Parallelism +## Handoff -The user may choose to run tickets in parallel, so expect other agents to make changes to the map. +End every session by clearing the context and opening one or more fresh sessions. Close with a **Next steps** block the user can copy-paste. Two cases: -## Skipping The Decision Map +**Open tickets remain.** List the currently-unblocked tickets, then give two copy-paste options: a bare command for one session (you pick the next ticket), and one pinned command per unblocked ticket for running them in parallel. Paste one line per fresh window — opening one, some, or all of them. -Many times, the initial grilling will result in no fog of war. No unresolved tickets. Nothing to do, except implement. +> **Next steps** — 3 tickets unblocked: #4, #5, #6. +> Clear the context, then open fresh sessions. +> +> **One session** — resolves the next unblocked ticket: +> ``` +> Invoke /decision-mapping with the map at . +> ``` +> +> **Parallel** — paste one line per window, up to all 3: +> ``` +> Invoke /decision-mapping with the map at , ticket #4. +> Invoke /decision-mapping with the map at , ticket #5. +> Invoke /decision-mapping with the map at , ticket #6. +> ``` -In those situations, you should offer the user the chance to skip the decision map - since the decision map is only needed if multi-session decisions need to be made. - -If they skip it, you should recommend either implementing directly or using `/to-prd` to schedule a multi-session implementation. +**No open tickets remain.** The fog is pushed back far enough that the path to the finish line is clear — the map is done. (The initial grilling may also surface no fog at all, in which case there was never a map to build.) Recommend implementing directly, or using `/to-prd` to schedule a multi-session implementation. diff --git a/skills/in-progress/wizard/SKILL.md b/skills/in-progress/wizard/SKILL.md new file mode 100644 index 0000000..a754784 --- /dev/null +++ b/skills/in-progress/wizard/SKILL.md @@ -0,0 +1,45 @@ +--- +name: wizard +description: Generate an interactive bash wizard that walks a human through a manual procedure — third-party setup, a one-off migration, an A→B state transition — opening URLs, capturing values, confirming each step, and writing .env files and GitHub Actions secrets. +disable-model-invocation: true +--- + +# Wizard + +A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets), confirms at every stage, and shows how much is left. It might configure third-party services, run a one-off migration, or move the project from one state to another. + +The delightful UX is already solved by [template.sh](template.sh) — progress with time-remaining, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point — never hand-edit it. + +A wizard is ephemeral by default — built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo. + +## Process + +### 1. Scope the procedure + +Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold: + +- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce). +- For a migration or transition: the current state, the target state, and the irreversible actions between them. + +Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder. + +**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) where it's written (`.env`, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public. + +### 2. Map each stage's journey + +For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist. + +**Done when:** every stage traces to concrete instructions a stranger could follow. + +### 3. Author the wizard + +Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — and set `TOTAL_STAGES` and `TOTAL_MINUTES` to honest estimates (this drives the time-remaining display). + +Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every persisted value, `set_secret` only the values CI actually needs, and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker. + +### 4. Verify and hand off + +- `bash -n