fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: add canonical glossary + install mattpocock skills adapted for repo

Browse Source 
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>
This commit is contained in:
Danijel Martinek
2026-05-13 13:04:42 +02:00
parent 2edc76002a
commit a372eeda86
8 changed files with 587 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
.claude/skills/to-prd/SKILL.md Normal file
View File

@@ -0,0 +1,108 @@
---
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`.