Danijel Martinek
a372eeda86
docs/glossary.md is the shared vocabulary source for humans and agents.
Resolves every cross-cutting term used in this repo (feature, use case,
manifest, slice, conformance, dispatch, ...) with one-sentence definitions,
relationships, and flagged ambiguities. Linked from CLAUDE.md "Read First"
and AGENTS.md preamble so every session loads it early.
.claude/skills/ installs four mattpocock skills adapted to this monorepo:
- to-prd: writes to docs/work/prds/ with the repo's PRD frontmatter +
merged user-stories/implementation/testing sections
- grill-with-docs: points at docs/decisions/ + docs/glossary.md; adds
feature.manifest.ts + conformance-rule cross-checks
- grill-me: minor — adds pnpm work / fallow / manifest shortcuts
- handoff: adds the repo's specific don't-duplicate artifacts list
Also fixes a missed "Phase-1" residual in CLAUDE.md's Read First section.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
109 lines
5.4 KiB
Markdown
109 lines
5.4 KiB
Markdown
---
|
|
name: to-prd
|
|
description: Turn the current conversation context into a PRD and write it to docs/work/prds/. Use when the user wants to materialize the discussion into a draft PRD that feeds the pnpm work pipeline.
|
|
---
|
|
|
|
This skill takes the current conversation context and codebase understanding and produces a PRD. Do NOT interview the user — just synthesize what you already know. If you need to interview first, invoke `grill-with-docs` instead.
|
|
|
|
The PRD lives on the filesystem (this repo does not use an issue tracker for work). The downstream pipeline is `pnpm work decompose` → epic + stories → tasks → sandcastle dispatch (see `docs/architecture/agent-first-workflow-and-conformance.md`).
|
|
|
|
## Process
|
|
|
|
1. **Explore the repo if you haven't already.** Use the project's domain vocabulary throughout (check `docs/glossary.md` if it exists, otherwise lift terms from `docs/architecture/vertical-feature-spec.md` §6 and the feature packages' `feature.manifest.ts`). Respect any ADRs in the area you're touching — they're at `docs/decisions/adr-NNN-<slug>.md`. Use `pnpm work status` to see in-flight epics.
|
|
|
|
2. **Sketch the major modules / packages.** Identify which existing packages (`packages/<feature>/`, `packages/core-*/`) you'll modify and which new ones — if any — you'll create. Actively look for **deep modules**: small interface, deep implementation, rarely-changing surface. The vertical-feature-package shape (entities → application → infrastructure → DI) is the default unit; resist scaffolding new core packages unless required.
|
|
|
|
Check with the user that this module sketch matches their expectations. Confirm which modules they want tests written for. (The conformance system already mandates tests for every use case + controller; this question is about extra coverage — repository contract suites, integration tests, etc.)
|
|
|
|
3. **Pick a slug + date** for the PRD filename: `docs/work/prds/<YYYY-MM-DD>-<kebab-slug>.prd.md`. Use today's date.
|
|
|
|
4. **Write the PRD using the template below**, then save it. Status starts at `draft`. The decomposer (`pnpm work decompose`) refuses to run on `draft` PRDs — the human flips it to `approved` after review.
|
|
|
|
<prd-template>
|
|
|
|
```markdown
|
|
---
|
|
id: <YYYY-MM-DD>-<kebab-slug>
|
|
title: <Human-readable title>
|
|
type: prd
|
|
status: draft
|
|
author: <user>
|
|
elicitation-session: <agent-session-id-or-omit>
|
|
created: <YYYY-MM-DD>
|
|
---
|
|
|
|
## Problem
|
|
|
|
What's broken or missing today? Who hurts because of it? Frame it from the user's perspective (where "user" may be a developer using the template, an end-user of an app built on it, or an AI agent operating in the codebase).
|
|
|
|
## Goal
|
|
|
|
What state are we trying to reach? One or two sentences.
|
|
|
|
## In scope
|
|
|
|
- Bullets of what this PRD covers.
|
|
|
|
## Out of scope
|
|
|
|
- Bullets of what's explicitly excluded. The explicit no-s are as valuable as the yes-s.
|
|
|
|
## Constraints
|
|
|
|
- Non-negotiables: existing ADRs to respect, conformance rules, performance budgets, compliance requirements, etc.
|
|
- Reference ADRs by ID: `ADR-014`, `ADR-017`, etc.
|
|
|
|
## Success criteria
|
|
|
|
- Verifiable outcomes. "Feature X passes `pnpm typecheck && pnpm test && pnpm conformance` green" is concrete; "feature X is great" is not.
|
|
|
|
## User stories
|
|
|
|
A numbered list. Cover all aspects of the feature, including edge cases.
|
|
|
|
1. As a `<actor>`, I want `<capability>`, so that `<benefit>`.
|
|
2. ...
|
|
|
|
## Implementation decisions
|
|
|
|
Decisions captured here so the decomposer (and downstream agents) don't re-litigate them. Include:
|
|
|
|
- Modules to be built / modified (by package or feature name — no file paths; those rot fast)
|
|
- Interface shapes (Zod schemas, TypeScript types, tRPC procedures) — describe in prose; inline only if a snippet encodes the decision more precisely than prose (e.g., a Zod schema, a discriminated union, a state machine)
|
|
- Architectural choices (DI factory shape, withSpan/withCapture wrapping, manifest entries, anchor placements)
|
|
- Schema changes (Payload collections, database migrations)
|
|
- Cross-feature interactions (event publish/consume pairs, realtime channels, audit emissions)
|
|
- Optional-core requirements (does this feature require `core-events`? `core-realtime`? `core-audit`?)
|
|
|
|
Do NOT include specific file paths or full code snippets — they go stale quickly. Prefer prose plus inline contracts (schemas, types) where they tighten the decision.
|
|
|
|
## Testing decisions
|
|
|
|
- What "good test" means for this feature (behavior through public interfaces, not implementation details)
|
|
- Which modules get repository contract suites (any new `IXRepository`)
|
|
- Which modules get use-case unit tests (every use case — that's a conformance rule)
|
|
- Integration / e2e coverage: which apps, which Playwright specs
|
|
- Prior art in the codebase: pointers to similar test patterns to mirror
|
|
|
|
## Open questions
|
|
|
|
- Q1: `<question>` — `<recommended answer>`
|
|
- Q2: ...
|
|
|
|
## Out of scope (deferred)
|
|
|
|
Things that are tempting to include but should be a separate PRD.
|
|
|
|
## Further notes
|
|
|
|
Anything else: stakeholders, related PRDs (`Builds on <prd-id>`, `Supersedes <prd-id>`), external references.
|
|
```
|
|
|
|
</prd-template>
|
|
|
|
## After writing
|
|
|
|
- Verify the file lives at `docs/work/prds/<date>-<slug>.prd.md`.
|
|
- Tell the user the path and remind them to review and flip `status: draft → approved` before running `pnpm work decompose`.
|
|
- If new domain terms were introduced or sharpened during synthesis, append them to `docs/glossary.md` (lazy-create if missing) — same rules as `grill-with-docs`.
|