fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 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

18
.claude/skills/grill-me/SKILL.md Normal file
View File

@@ -0,0 +1,18 @@
---
name: grill-me
description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when the user wants to stress-test a plan, get grilled, or mentions "grill me". Use grill-with-docs instead when the plan should cross-check against ADRs + glossary + manifests.
---
Interview the user relentlessly about every aspect of this plan until you 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 before continuing.
If a question can be answered by exploring the codebase, explore the codebase instead. Useful shortcuts in this repo:
- `pnpm work status` — current epics and ready stories
- `cat packages/<feature>/src/feature.manifest.ts` — declared use cases / events / audits
- `ls docs/decisions/` — ADRs by number
- `pnpm fallow` — dead exports, dupes, complexity hotspots
- grep manifests across all features: `grep -r "publishes:" packages/*/src/feature.manifest.ts`
When grilling pulls in ADR / glossary / manifest cross-checks and you want to update those docs inline, switch to `grill-with-docs` instead.

106
.claude/skills/grill-with-docs/SKILL.md Normal file
View File

@@ -0,0 +1,106 @@
---
name: grill-with-docs
description: Stress-test a plan against this repo's domain glossary, ADRs, conformance rules, and feature manifests. Update docs/glossary.md inline as terms crystallize; offer ADRs sparingly. Use when the user wants to harden a plan before it becomes a PRD.
---
<what-to-do>
Interview the user relentlessly about every aspect of this plan until you 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 before continuing.
If a question can be answered by exploring the codebase, explore the codebase instead of asking. The repo has fast feedback loops — run `pnpm work status`, grep manifests, read feature `feature.manifest.ts`, check ADRs. Speculation is a last resort.
</what-to-do>
<supporting-info>
## Repo doc map
This repo uses a **single context** with these doc locations:
```
/
├── docs/
│ ├── glossary.md ← lazy-create when first term resolves
│ ├── decisions/ ← ADRs (adr-NNN-<slug>.md, 3-digit zero-pad)
│ │ ├── adr-001-monorepo-tool.md
│ │ ├── adr-018-audit-and-compliance.md
│ │ └── ...
│ ├── architecture/ ← long-form specs + workflow design
│ ├── work/ ← PRDs, epics, stories, tasks
│ └── guides/ ← how-to runbooks
└── packages/<feature>/src/feature.manifest.ts ← per-feature contract
```
There is **no `CONTEXT.md` or `CONTEXT-MAP.md`** — this repo uses `docs/glossary.md` (create lazily) plus the per-feature `feature.manifest.ts` files for machine-readable domain shape. Don't create the multi-context layout (`CONTEXT-MAP.md`) unless this becomes a polyrepo.
## During the session
### Challenge against the glossary + manifests
When the user introduces a term that conflicts with `docs/glossary.md` (if it exists) or with a `feature.manifest.ts` entry, call it out immediately:
> "Your glossary defines `cancellation` as the act of voiding an unsent invoice, but you seem to mean the user-initiated subscription teardown — which is it?"
> "`auth.signIn` exists in `packages/auth/src/feature.manifest.ts` with that exact slug — are you adding a new use case or extending the existing one?"
### Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise canonical term:
> "You're saying `account` — do you mean a `User` (entity in `packages/auth`) or a Payload-collection record? Those are distinct."
### Discuss concrete scenarios
When domain relationships are being discussed, stress-test them with specific scenarios. Invent edge cases that force precision about boundaries between concepts. Lean on the existing feature set — auth, blog, media, marketing-pages, navigation — for grounding examples.
### Cross-reference with code
When the user states how something works, verify it against the code. Look at:
- The feature's `feature.manifest.ts` for declared use cases, audits, publishes, consumes
- `packages/<feature>/src/application/use-cases/` for the actual shape
- `packages/<feature>/src/di/bind-production.ts` for what's wired
- `docs/decisions/adr-NNN-*.md` for the decision history
If you find a contradiction, surface it:
> "You said cross-feature reactions happen through the bus, but `packages/auth/src/feature.manifest.ts` shows `publishes: []` — has this been wired yet?"
### Cross-reference with ADRs
Before recommending an approach, scan `docs/decisions/` for relevant ADRs. If your recommendation contradicts a current-status ADR, surface that explicitly:
> "You're proposing direct cross-feature imports, but `adr-006-vertical-feature-packages.md` plus rule R20 in the ESLint config forbid that — events (`core-events`) are the sanctioned path. Want to use events, or do you want to reopen the ADR?"
### Cross-reference with conformance rules
The conformance system (`docs/architecture/agent-first-workflow-and-conformance.md`) defines hard contracts:
- Every use case has a manifest entry → contracts → tests → impl (in that order)
- TS brands (`Instrumented`, `Captured`, `Audited`) attached at DI bind time
- ESLint rules enforce manifest ↔ code alignment
- `pnpm conformance` enforces cross-feature event closure
If the plan would violate any of these, flag it.
### Update `docs/glossary.md` inline
When a term is resolved during the conversation, append it to `docs/glossary.md` right then — don't batch. Lazy-create the file when the first term is resolved. Use the format in [glossary-format.md](./glossary-format.md).
Only include terms meaningful to **this repo's domain** (template / monorepo / agent-first workflow / clean architecture / vertical features). Skip general programming concepts. Skip implementation details — those belong in code or ADRs.
### 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. **Result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
If any is missing, skip the ADR. The repo's ADRs follow a long-form `Context → Decision → Alternatives considered → Consequences → Related` shape (see `docs/decisions/adr-015-events-and-jobs.md` for a representative example). Number is next-highest in `docs/decisions/` zero-padded to 3 digits (`adr-020-...`, `adr-021-...`).
If the grill produced a major refactor decision rather than a new feature, lead the user to an ADR; if it produced a feature plan, lead to a PRD via `to-prd`.
</supporting-info>

62
.claude/skills/grill-with-docs/glossary-format.md Normal file
View File

@@ -0,0 +1,62 @@
# docs/glossary.md Format
## Structure
```md
# Glossary
Domain vocabulary for `template-vertical`. Terms specific to this repo — clean architecture, vertical features, agent workflow, conformance. General programming concepts don't belong here; implementation details belong in code or ADRs.
## Architecture
**Feature**:
A vertical slice owning its Clean Architecture layers (entities → application → infrastructure → DI → integrations).
_Avoid_: module, domain, app.
**Use case**:
A single business action exposed by a feature, implemented as a factory `(deps) => async (input) => output`. Each one has a manifest entry, a Zod input/output schema pair, a colocated test, and a controller.
_Avoid_: command, action, handler.
**Manifest**:
The `feature.manifest.ts` file that declares a feature's use cases, audits, publishes, consumes, and required core packages. Source of truth for conformance gates.
**Conformance**:
The 5-gate enforcement system (TS brands → ESLint → boot assertion → `pnpm conformance` → fallow) that keeps manifest and code aligned.
## Workflow
**PRD**:
The top-level requirements doc at `docs/work/prds/<date>-<slug>.prd.md` that seeds an epic.
**Epic**:
A large body of work containing stories. Folder at `docs/work/<epic-slug>/_epic.md`.
**Story**:
One use case or technical capability. Folder under the epic, file `_story.md`.
**Task**:
One vertical slice = one PR = one commit. File `<slug>.task.md` under the story folder.
## Relationships
- A **PRD** decomposes into one or more **Epics**
- An **Epic** contains one or more **Stories**
- A **Story** is implemented by one or more **Tasks**
- A **Use case** is declared in a **Manifest** before it has code
- **Conformance** asserts that the **Manifest** and the code agree
## Flagged ambiguities
- (none yet — append here when conflicts are resolved during grilling)
```
## Rules
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
- **Flag conflicts explicitly.** When grilling surfaces ambiguity, capture both meanings under "Flagged ambiguities" with the resolution.
- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
- **Show relationships.** Use bold term names; express cardinality where obvious.
- **Only domain terms specific to this repo.** General programming concepts (timeouts, retries, errors, DI) don't belong even if used heavily. Before adding, ask: is this concept unique to template-vertical, or generic?
- **Group under subheadings** when natural clusters emerge (Architecture, Workflow, Instrumentation, etc.).
This repo is **single-context**: one `docs/glossary.md`, no `CONTEXT-MAP.md`. Don't switch to multi-context layout unless the repo splits.

36
.claude/skills/handoff/SKILL.md Normal file
View File

@@ -0,0 +1,36 @@
---
name: handoff
description: Compact the current conversation into a handoff document for another agent to pick up. Use when the user wants to transition work to a fresh session, switch worktrees, or hand off to a subagent.
argument-hint: "What will the next session be used for?"
---
Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it to a path produced by `mktemp -t handoff-XXXXXX.md` (read the file before you write to it).
Suggest the skills the next session should use, if any. In this repo, the common follow-ups are:
- `grill-with-docs` — stress-test the plan before coding
- `to-prd` — materialize the plan into `docs/work/prds/<date>-<slug>.prd.md`
- `superpowers:writing-plans` — author the implementation plan
- `superpowers:subagent-driven-development` — dispatch implementer + reviewer subagents per task
## Don't duplicate
Reference these artifacts by path or URL rather than inlining their content:
- PRDs (`docs/work/prds/*.prd.md`), epics (`docs/work/<epic>/_epic.md`), stories (`_story.md`), tasks (`*.task.md`)
- ADRs (`docs/decisions/adr-NNN-*.md`)
- AGENTS.md and CLAUDE.md (the next agent loads these automatically)
- `_state.json` (orchestrator-derived; the next agent regenerates it from markdown via `pnpm work rebuild-state`)
- Commit messages, diffs, PR descriptions — link the SHA / PR number
- Existing plans under `docs/superpowers/plans/`
## Do capture
- The active **goal** in one sentence
- **In-flight branch / worktree** and any uncommitted state (e.g. `git status` summary, dangling commits)
- **Decisions made in conversation** that haven't yet landed in a PRD or ADR
- **Blockers** and proposed next steps
- **Skills to invoke first** in the next session
- If the user passed arguments, treat them as the next session's focus and tailor the doc accordingly
Keep the document short — it's a baton, not a thesis.

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`.