Merge pull request #734 from mattpocock/chore/purge-prd-references

docs: finish the to-prd → to-spec rename in shipped text
2026-09-13 02:48:06 +07:00 · 2026-08-04 07:18:55 +01:00 · 2026-08-03 17:37:30 +01:00 · 2026-07-31 18:04:40 +01:00 · 2026-07-31 18:04:40 +01:00 · 2026-07-31 18:04:40 +01:00
12 changed files with 65 additions and 40 deletions
@@ -0,0 +1,12 @@
+---
+"mattpocock-skills": patch
+---
+
+Finish the `to-prd` → `to-spec` rename: "spec" is now the only term in the shipped text.
+
+- **`to-spec`** no longer opens with "you may know this document as a PRD" — the parenthetical is dropped from the skill and its docs page. The local-markdown tracker template drops the same hedge.
+- **`code-review`** talks about the originating issue/spec rather than issue/PRD, in its frontmatter description, its two-axis summary, and the spec-source search order. Both READMEs re-synced.
+- **The GitHub and GitLab tracker templates** now say "Issues and specs for this repo live as GitHub/GitLab issues" — they had been left on "PRDs" when the local template was updated, so the stale term propagated into every repo they were written into.
+- **`docs/engineering/research.md`** pointed at `https://aihero.dev/skills-to-prd`, a dead slug for the renamed skill; it now links `to-spec` like the other nineteen docs pages do.
+
+The CHANGELOG and existing changesets still name PRDs where they document the rename itself, which is correct.
@@ -22,49 +22,64 @@ If you want to keep up with changes to these skills, and any new ones I create,

 [Sign Up To The Newsletter](https://www.aihero.dev/s/skills-newsletter)

-## Quickstart (30-second setup)
+## Installation (30-second setup)

-1. Run the skills.sh installer:
+Two ways in, two philosophies. **The [Claude Code plugin](https://code.claude.com/docs/en/plugins)** installs the whole set as a managed, read-only bundle that updates when I ship — you subscribe rather than fork. **[skills.sh](https://skills.sh/mattpocock/skills)** copies editable skill files into your project, so you can hack on them and make them your own. Pick one — installing both leaves you with every skill twice.
+
+### 1. Get the skills
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude plugins install mattpocock-skills
+```
+
+Or, from inside a session:
+
+```
+/plugin install mattpocock-skills
+```
+
+It's in Claude Code's official marketplace, so there's nothing to add first, and updates arrive automatically.
+
+</details>
+
+<details>
+<summary><strong>Codex, and other agents</strong></summary>

 ```bash
 npx skills@latest add mattpocock/skills
 ```

-2. Pick the skills you want, and which coding agents you want to install them on. **Make sure you select `/setup-matt-pocock-skills`**.
+Pick the skills you want, and which coding agents to install them on. **The installer lets you choose which skills to take — make sure `setup-matt-pocock-skills` is one of them.**

-3. Run `/setup-matt-pocock-skills` in your agent. It will:
-   - Ask you which issue tracker you want to use (GitHub, Linear, or local files)
-   - Ask you what labels you apply to tickets when you triage them (`/triage` uses labels)
-   - Ask you where you want to save any docs we create
+A native Codex plugin is on the roadmap — see [`.agents/adr/0002-ship-as-a-claude-code-plugin.md`](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).

-4. Bam - you're ready to go.
+</details>

-## Install as a Claude Code plugin
+<details>
+<summary><strong>For tinkerers</strong></summary>

-Prefer a plug-and-play install you don't maintain by hand? These skills also ship as a native [Claude Code plugin](https://code.claude.com/docs/en/plugins). Instead of copying editable files into your repo, the plugin installs the whole skill set as a managed bundle that updates when I ship a new version — you subscribe rather than fork.
-
-Inside Claude Code:
-
-```
-/plugin marketplace add mattpocock/skills
-/plugin install mattpocock-skills@mattpocock
-```
-
-Or from your shell:
+Use the same installer, on any agent — including Claude Code:

 ```bash
-claude plugin marketplace add mattpocock/skills
-claude plugin install mattpocock-skills@mattpocock
+npx skills@latest add mattpocock/skills
 ```

-Then run `/setup-matt-pocock-skills` once per repo, exactly as in the quickstart above.
+It writes the skills into your repo as ordinary files you own and can edit. Nothing updates behind your back; pull my latest changes when you want them with `npx skills update`.

-Two ways to install, two philosophies:
+</details>

- **[skills.sh](https://skills.sh/mattpocock/skills)** copies the skills into your project so you can hack on them and make them your own.
- **The plugin** keeps them as a read-only, always-current bundle you don't edit — best when you just want my set to work and follow along as it evolves.
+### 2. Run `/setup-matt-pocock-skills`

-> Using Codex or another agent? The [skills.sh installer](https://skills.sh/mattpocock/skills) already installs these skills into Codex and other Agent-Skills-standard harnesses today. A native Codex plugin is on the roadmap — see [`.agents/adr/0002-ship-as-a-claude-code-plugin.md`](./.agents/adr/0002-ship-as-a-claude-code-plugin.md).
+In your agent, run it once per repo. It will:
+
+- Ask you which issue tracker you want to use (GitHub, Linear, or local files)
+- Ask you what labels you apply to tickets when you triage them (`/triage` uses labels)
+- Ask you where you want to save any docs we create
+
+### 3. Bam - you're ready to go.

 ## Why These Skills Exist

@@ -194,7 +209,7 @@ Skills I use daily for code work.
 - **[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.
 - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
- **[code-review](./skills/engineering/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/PRD?), run as parallel sub-agents so neither pollutes the other.
+- **[code-review](./skills/engineering/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents so neither pollutes the other.
 - **[resolving-merge-conflicts](./skills/engineering/resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`.

 ### Productivity
@@ -26,4 +26,4 @@ The defining move is that the reading runs as a **background agent**. You keep w

 ## Where it fits

-A reach-for-it-anytime standalone that feeds the thinking skills: the file it produces is something to grill, plan, or design against, so it sits upstream of work like [grilling](https://aihero.dev/skills-grilling) and [to-prd](https://aihero.dev/skills-to-prd) rather than in the build chain. For the whole map, see [ask-matt](https://aihero.dev/skills-ask-matt).
+A reach-for-it-anytime standalone that feeds the thinking skills: the file it produces is something to grill, plan, or design against, so it sits upstream of work like [grilling](https://aihero.dev/skills-grilling) and [to-spec](https://aihero.dev/skills-to-spec) rather than in the build chain. For the whole map, see [ask-matt](https://aihero.dev/skills-ask-matt).
@@ -12,7 +12,7 @@ npx skills update to-spec

 ## What it does

-`to-spec` turns the current conversation and your codebase understanding into a spec (you may know this document as a PRD), then publishes it to your issue tracker.
+`to-spec` turns the current conversation and your codebase understanding into a spec, then publishes it to your issue tracker.

 It does **not** interview you again. By the time you reach for it, the alignment work is done — `to-spec` synthesises what is already known rather than asking a fresh round of questions.

@@ -27,5 +27,5 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them)
 - **[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.
 - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface.
- **[code-review](./code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/PRD?), run as parallel sub-agents.
+- **[code-review](./code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents.
 - **[resolving-merge-conflicts](./resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`.
@@ -1,12 +1,12 @@
 ---
 name: code-review
-description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
 ---

 Two-axis review of the diff between `HEAD` and a fixed point the user supplies:

 - **Standards** — does the code conform to this repo's documented coding standards?
- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+- **Spec** — does the code faithfully implement the originating issue / spec?

 Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.

@@ -28,7 +28,7 @@ Look for the originating spec, in this order:

 1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
 2. A path the user passed as an argument.
-3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".

 ### 3. Identify the standards sources
@@ -1,6 +1,6 @@
 # Issue tracker: GitHub

-Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.

 ## Conventions

@@ -1,6 +1,6 @@
 # Issue tracker: GitLab

-Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.

 ## Conventions

@@ -1,6 +1,6 @@
 # Issue tracker: Local Markdown

-Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
+Issues and specs for this repo live as markdown files in `.scratch/`.

 ## Conventions

@@ -4,7 +4,7 @@ description: Turn the current conversation into a spec and publish it to the pro
 disable-model-invocation: true
 ---

-This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.

 The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.

@@ -103,5 +103,3 @@ The end-to-end behaviour this ticket makes work, from the user's perspective —
 </issue-template>

 In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
-
-Work the frontier one ticket at a time with `/implement`, clearing context between tickets.
@@ -11,7 +11,7 @@ Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"`

 Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke.

-Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.

 Redact any sensitive information, such as API keys, passwords, or personally identifiable information — the summary becomes the agent's prompt.
Author	SHA1	Message	Date
Matt Pocock	d53cabc383	Merge pull request #734 from mattpocock/chore/purge-prd-references docs: finish the to-prd → to-spec rename in shipped text	2026-08-04 07:18:55 +01:00
Matt PocockandClaude Opus 5	a2f9333669	docs: finish the to-prd → to-spec rename in shipped text Drop the "you may know this document as a PRD" hedge from to-spec and the local tracker template, switch code-review to issue/spec, bring the GitHub and GitLab tracker templates in line with the local one, and fix research.md's dead skills-to-prd link. CHANGELOG and existing changesets keep the old term where they document the rename itself. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-03 17:37:30 +01:00
Matt PocockandClaude Opus 5	bfdaef8e98	docs: describe grilling as round-by-round everywhere The round-by-round rework left the wrappers and callers still promising a one-question-at-a-time interview. Sync grill-me, grill-with-docs and triage (docs + skill step), plus grilling's Codex short_description and the loop-me draft. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	1495d01430	feat(grilling): bold the question title The title now carries its own bold alongside the bold Q-number, so the question line reads as a heading. Sync the docs page and changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	5626acd11a	feat(grilling): lead each question with a question-mark emoji Prefix the numbered question line with ❓ so questions and their ➡️ recommendations are both scannable. Sync the docs page and changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	32af39b277	docs(grilling): drop the Recommendation label from the question format The recommendation now stands alone on its arrow line. Sync the docs page and changeset to match. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	294a2c97c5	docs(grilling): pin the question format and document it Add the fixed per-question shape (numbered title, body, recommendation line) to grilling's SKILL.md, sync the docs page, and add a changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	f054defc3f	feat(writing-for-agents): add the cache leading word for environment truth Single source of truth now reaches past the document into the environment. package.json scripts, config files, directory layout and --help output are authoritative already, so a doc restating them is a cache of a lookup that earns its load only when the lookup is expensive. Co-authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt Pocock	38d62e71ed	fix: correct formatting in SKILL.md for clarity and consistency	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 5	0f2bdbdb06	feat: graduate to-questionnaire into the productivity bucket Move `to-questionnaire` out of in-progress into `productivity/` and wire it up as a promoted skill: plugin.json entry, top-level + Productivity READMEs under User-invoked, a docs page at docs/productivity/to-questionnaire.md, and a Standalone route in ask-matt framing it as the inverse of /grill-me. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 4.8	1fc6573e0e	feat!: rename writing-great-skills to writing-for-agents and restructure The reference now covers any document an agent consumes — skills, AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into SKILL.md as a dedup (Avoid-lists and the standalone Predictability definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md; the skill is now model-invoked. Clean rename, no alias. Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 4.8	6bcbcb09e2	feat(prototype): logic branch produces a shareable HTML demo Reshape the logic branch from a terminal app into a single self-contained HTML file a non-developer can drive: a labelled state panel, free-play buttons, and tabbed guided walkthroughs (scenarios) with the ordered buttons to press underneath each. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway primary source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt PocockandClaude Opus 4.8	a4b2009a1a	feat(grilling): round-by-round frontier interview Rework grilling from one-question-at-a-time to asking the whole frontier each round, with background sub-agents for fact-finding so research never blocks the round. Fold the batch-grill-me experiment into grilling and delete it. Re-sync the docs page, including how to opt back into one-at-a-time via global CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-31 18:04:40 +01:00
Matt Pocock	2ab958093e	Merge pull request #681 from mattpocock/docs/install-instructions-split docs: split install instructions by audience	2026-07-28 10:18:17 +01:00
Matt PocockandClaude Opus 5	369c264e23	docs: split install instructions by audience Collapse the skills.sh Quickstart and the "Install as a Claude Code plugin" section into one Installation section, ordered Claude Code → Codex/other agents → tinkerers, each in a collapsed details block. Claude Code now leads with the one-liner `claude plugins install mattpocock-skills` — the plugin ships in Claude Code's official marketplace, so the old two-step `marketplace add` → `install` dance is gone. `/setup-matt-pocock-skills` is promoted to a shared step 2, since every install path needs it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 10:17:03 +01:00
Matt Pocock	ed37663cc5	refactor(to-tickets): remove redundant instructions for ticket implementation	2026-07-21 11:28:51 +01:00