Danijel Martinek
756e36c720
The previous layout placed epic folders directly under docs/work/
alongside prds/ and _system/. Tightening: epics now live in their
own docs/work/epics/ subfolder, peer to prds/ and _system/. Same
shape as the existing prds/ bucket.
Final docs/work/ layout:
README.md
prds/<slug>.prd.md
_system/_state.json
epics/<slug>/_epic.md + <story-folder>/_story.md
Renames (git mv preserves history):
- docs/work/binder-wrap-helper/
-> docs/work/epics/binder-wrap-helper/
- docs/work/library-evaluation-policy/
-> docs/work/epics/library-evaluation-policy/
- docs/work/ci-security-and-supply-chain/
-> docs/work/epics/ci-security-and-supply-chain/
Tooling updates:
- state-builder.mjs walks workRoot/epics/ directly; SKIP_FOLDERS
obsoleted (no more sibling folders to filter out).
- dispatch.mjs's findNextTask, tickStoryBulletInEpic, and
flipEpicDoneIfAllStoriesDone all join with "epics" segment.
- prd-ship.mjs's deriveShippingCommits walks workRoot/epics/ and
git-logs docs/work/epics/<epic>/.
- decomposer.prompt.md emits epics under docs/work/epics/<epic-id>/.
- handoff + grill-with-docs glossary references updated.
- Glossary entry for Epic updated.
Reserved future shape: when a task-tracker integration (ClickUp,
Linear) ships, the epics/ subfolder hosts <task-id>-<slug>/
folders. Today it just hosts bare slugs.
2.7 KiB
2.7 KiB
docs/glossary.md Format
Structure
# 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/epics/<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.