chore(template): clean-slate template snapshot from bb4a0c7
Curated, product-agnostic snapshot of the post-story-04 tree: demo content deleted, auth-only reference feature, web-next shell, all gates green. Product-specific docs, ADRs 027-029, PRDs/epics/archive, editor library traces, and product naming are curated out; generic template repairs (coverage provider devDeps, root test:coverage script, live lint fixes, root-only release-please) are kept. See TEMPLATE.md for provenance, curation list, and usage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
This commit is contained in:
681
docs/architecture/agent-first-workflow-and-conformance.md
Normal file
681
docs/architecture/agent-first-workflow-and-conformance.md
Normal file
@@ -0,0 +1,681 @@
|
||||
---
|
||||
title: Agent-first development workflow + feature conformance
|
||||
status: design
|
||||
created: 2026-05-12
|
||||
authors: [danijel, claude]
|
||||
related:
|
||||
- docs/architecture/feature-conformance-explainer.html
|
||||
- docs/architecture/vertical-feature-spec.md
|
||||
- docs/guides/tdd-workflow.md
|
||||
- docs/guides/scaffolding-a-feature.md
|
||||
- CLAUDE.md
|
||||
---
|
||||
|
||||
# Agent-first development workflow + feature conformance
|
||||
|
||||
## Why this document exists
|
||||
|
||||
`template-vertical` is being shaped around the assumption that **AI coding agents will author most feature work**. Humans set direction, write PRDs (with agent help), review diffs, and intervene when escalation is needed; agents do the bulk of the coding. This document defines:
|
||||
|
||||
1. The **feature-conformance enforcement system** that gives agents tight, layered, machine-readable feedback on architectural drift.
|
||||
2. The **agent-first workflow** — manifest → contracts → tests → code — that the conformance system enforces.
|
||||
3. The **local task system** at `docs/work/` that holds PRDs, epics, stories, and tasks as markdown, parseable by both humans and agents.
|
||||
4. The **sandcastle orchestrator** that dispatches implementer and reviewer agents per task, respecting a dependency DAG.
|
||||
|
||||
These four pillars are co-designed. The conformance system is the enforcement substrate; the workflow is the shape of work; the task system is the address space; sandcastle is the dispatch loop.
|
||||
|
||||
The conformance design is illustrated separately at [`docs/architecture/feature-conformance-explainer.html`](./feature-conformance-explainer.html). This document complements that with the surrounding workflow + tooling.
|
||||
|
||||
## Mental model
|
||||
|
||||
| Pillar | What it is | Primary artifact |
|
||||
| --------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| **Conformance engine** | manifest + TS brands + ESLint + boot-time assertion + CI gate | `feature.manifest.ts` per feature; `_state.json` snapshot of compliance |
|
||||
| **Agent workflow** | PRD → Epic → Story → Task; manifest-first ordering; TDD-per-slice | `docs/work/**/*.md` |
|
||||
| **Local task system** | filesystem markdown, single state file, dispatchable | `docs/work/` |
|
||||
| **Sandcastle orchestrator** | implementer + reviewer agents per task, DAG-respecting, retry-capped | `.sandcastle/` config + `scripts/work-*.ts` |
|
||||
|
||||
The same artifacts are read by humans, AI implementers, AI reviewers, the orchestrator, and the pre-commit hooks. There is no separate "process layer."
|
||||
|
||||
## Hierarchy
|
||||
|
||||
```
|
||||
PRD (initiative — one .prd.md)
|
||||
└── Epic (large body of work — one folder + _epic.md)
|
||||
└── Story (one use case OR one technical capability)
|
||||
└── Task (one vertical slice = one PR = one commit)
|
||||
└── Subtask (rare; only for unexpectedly complex slices)
|
||||
```
|
||||
|
||||
**Feature is metadata, not a hierarchy level.** The use-case identifier (`auth.signUp`) already encodes the feature. ClickUp/Linear/etc. tags can carry it; in this system it sits in frontmatter.
|
||||
|
||||
**Story type is metadata** — `user-story` or `technical-story` — same hierarchy slot, different body template:
|
||||
|
||||
- **User story:** `As a <role>, I want <action>, so that <outcome>`
|
||||
- **Technical story:** `Goal / Why / Done when`
|
||||
|
||||
## File system
|
||||
|
||||
```
|
||||
docs/work/
|
||||
├── README.md # how this folder is used
|
||||
├── _state.json # derived, committed, orchestrator-managed
|
||||
├── _templates/
|
||||
│ ├── prd.template.md
|
||||
│ ├── epic.template.md
|
||||
│ ├── user-story.template.md
|
||||
│ ├── technical-story.template.md
|
||||
│ └── task.template.md
|
||||
├── prds/
|
||||
│ ├── 2026-05-12-conformance-system.prd.md
|
||||
│ └── ...
|
||||
├── conformance-system-v1/ # one folder per epic
|
||||
│ ├── _epic.md
|
||||
│ ├── 01-define-feature-helper/ # one folder per story
|
||||
│ │ ├── _story.md
|
||||
│ │ ├── 01-define-feature-helper-exists.task.md
|
||||
│ │ ├── 02-instrumented-brand-attached.task.md
|
||||
│ │ └── ...
|
||||
│ └── ...
|
||||
└── work-system-v1/
|
||||
└── ...
|
||||
|
||||
.sandcastle/
|
||||
├── Dockerfile # extends existing CI image
|
||||
├── implementer.prompt.md
|
||||
├── reviewer.prompt.md
|
||||
├── decomposer.prompt.md
|
||||
├── prd-eliciter.prompt.md
|
||||
└── .env.example
|
||||
|
||||
scripts/
|
||||
├── work-prd-new.ts # invokes PRD elicitation skill
|
||||
├── work-decompose.ts # PRD → epic + stories
|
||||
├── work-decompose-tasks.ts # story → tasks
|
||||
├── work-dispatch.ts # orchestrator loop
|
||||
├── work-status.ts # human-readable status tree
|
||||
└── work-rebuild-state.ts # regen _state.json from markdown
|
||||
```
|
||||
|
||||
### Naming conventions
|
||||
|
||||
- **Underscored system files** (`_epic.md`, `_story.md`, `_state.json`, `_templates/`) — orchestrator-managed indexes or templates
|
||||
- **Numeric prefix on filenames** (`01-`, `02-`) — execution order; doubles as sort key
|
||||
- **`<slug>.task.md`** — individual tasks
|
||||
- **`<date>-<slug>.prd.md`** — PRDs date-prefixed for chronological sort
|
||||
|
||||
## File formats
|
||||
|
||||
### PRD — `docs/work/prds/<date>-<slug>.prd.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 2026-05-12-conformance-system
|
||||
title: Feature Conformance System
|
||||
type: prd
|
||||
status: draft | in-review | approved | superseded
|
||||
author: danijel
|
||||
elicitation-session: <agent-session-id>
|
||||
created: 2026-05-12
|
||||
---
|
||||
|
||||
## Problem
|
||||
|
||||
What's broken or missing today? Who hurts because of it?
|
||||
|
||||
## Goal
|
||||
|
||||
What state are we trying to reach?
|
||||
|
||||
## In scope
|
||||
|
||||
- ...
|
||||
|
||||
## Out of scope
|
||||
|
||||
- ...
|
||||
|
||||
## Constraints
|
||||
|
||||
- ...
|
||||
|
||||
## Success criteria
|
||||
|
||||
- ...
|
||||
|
||||
## Requirements
|
||||
|
||||
- R1: ...
|
||||
- R2: ...
|
||||
|
||||
## Open questions
|
||||
|
||||
- Q1: ...
|
||||
```
|
||||
|
||||
**Authoring flow:**
|
||||
|
||||
1. Human runs `pnpm work prd-new "<one-line idea>"`
|
||||
2. Agent invokes the **PRD elicitation skill** — runs a question-driven interview with the human (similar in shape to `superpowers:brainstorming`) until it has enough context across Problem / Goal / Scope / Constraints / Success / Requirements
|
||||
3. Agent drafts PRD with `status: draft`
|
||||
4. Human reviews, edits, flips to `status: approved`
|
||||
5. **Decomposer refuses to run on `draft` PRDs.**
|
||||
|
||||
### Epic — `<epic-slug>/_epic.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: conformance-system-v1
|
||||
prd: 2026-05-12-conformance-system
|
||||
title: Conformance system v1
|
||||
type: epic
|
||||
status: todo | in-progress | done | cancelled
|
||||
features: [cross-cutting]
|
||||
created: 2026-05-12
|
||||
target: 2026-Q3
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Build the feature-conformance enforcement system so AI agents get
|
||||
layered, sub-second feedback on drift between manifest and code.
|
||||
|
||||
## Why
|
||||
|
||||
(brief — link to PRD for detail)
|
||||
|
||||
## In scope
|
||||
|
||||
- ...
|
||||
|
||||
## Out of scope
|
||||
|
||||
- ...
|
||||
|
||||
## Stories
|
||||
|
||||
- [ ] [01 — defineFeature helper + Instrumented brand](01-define-feature-helper/_story.md)
|
||||
- [ ] [02 — Boot assertions](02-boot-assertions/_story.md)
|
||||
- ...
|
||||
```
|
||||
|
||||
### Story (technical) — `<epic>/<story>/_story.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 01-define-feature-helper
|
||||
epic: conformance-system-v1
|
||||
title: defineFeature helper + Instrumented brand
|
||||
type: technical-story
|
||||
status: todo | in-progress | done
|
||||
feature: core-shared
|
||||
depends-on: []
|
||||
blocks: [02-boot-assertions, 05-generator-updates]
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Manifest helper + brand types enable type-level enforcement that every
|
||||
use-case binding is wrapped with `withSpan` + `withCapture`
|
||||
(and `withAudit` when mutating).
|
||||
|
||||
## Why
|
||||
|
||||
Compile-time feedback is the cheapest layer and the foundation every other
|
||||
milestone reads.
|
||||
|
||||
## Done when
|
||||
|
||||
Compile-time TS2322 fires at the IDE when an unwrapped factory is bound
|
||||
through `ProductionUseCase<...>`.
|
||||
|
||||
## In scope
|
||||
|
||||
- `defineFeature` helper signature + tests
|
||||
- Brand types: `Instrumented<F>`, `Captured<F>`, `Audited<F>`
|
||||
- Wiring brands into existing wrappers (no API changes)
|
||||
- `auth` as the reference feature using the new pattern
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Migration of other features (each is its own story)
|
||||
- Boot-time `assertConformance` (story 02)
|
||||
- ESLint rules consuming the brands (story 03)
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] [01 — defineFeature helper exists](01-define-feature-helper-exists.task.md)
|
||||
- [ ] [02 — Instrumented brand attached via withSpan](02-instrumented-brand-attached.task.md)
|
||||
- ...
|
||||
```
|
||||
|
||||
### Story (user) — same skeleton, body uses As a / I want / So that
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 01-sign-up
|
||||
epic: auth-v1
|
||||
title: Sign up with email and password
|
||||
type: user-story
|
||||
status: todo
|
||||
feature: auth
|
||||
depends-on: []
|
||||
---
|
||||
|
||||
## As a / I want / So that
|
||||
|
||||
**As a** visitor
|
||||
**I want** to create an account with email and password
|
||||
**So that** I can access member-only content
|
||||
|
||||
## In scope
|
||||
|
||||
- Email/password sign-up flow
|
||||
- Password hashing
|
||||
- Audit + event emission on success
|
||||
- tRPC procedure exposure
|
||||
|
||||
## Out of scope
|
||||
|
||||
- OAuth sign-up (separate story)
|
||||
- Email verification (separate story)
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] [01 — reject invalid email format + scaffold](01-reject-invalid-email-format.task.md)
|
||||
- [ ] [02 — reject duplicate email](02-reject-duplicate-email.task.md)
|
||||
- ...
|
||||
```
|
||||
|
||||
### Task — `<epic>/<story>/<slug>.task.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
id: 02-instrumented-brand-attached
|
||||
story: 01-define-feature-helper
|
||||
epic: conformance-system-v1
|
||||
title: Attach Instrumented<F> brand via withSpan
|
||||
type: task
|
||||
status: todo | ready | in-progress | done | escalated
|
||||
depends-on: [01-define-feature-helper-exists]
|
||||
blocks: [06-signin-rebound-via-branded-slot]
|
||||
sandbox: default
|
||||
max-attempts: 3 # default; override per task
|
||||
attempts: { implementer: 0, reviewer: 0 }
|
||||
---
|
||||
|
||||
## Goal
|
||||
|
||||
Attach the `Instrumented<F>` brand to functions returned by `withSpan`.
|
||||
|
||||
## Why this matters
|
||||
|
||||
The brand is the type-level seam the binding signature checks. Without it,
|
||||
the compiler can't tell a wrapped factory from an unwrapped one.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `Instrumented<F>` = `F & { readonly __instrumented: true }`
|
||||
- [ ] `withSpan` return type is `Instrumented<typeof fn>`
|
||||
- [ ] Brand re-exported from `@repo/core-shared/conformance`
|
||||
- [ ] Test asserts wrapped function carries brand at the type level
|
||||
- [ ] All existing tests still pass
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Updating `with-capture` and `with-audit` (separate tasks)
|
||||
- Refactoring `withSpan`'s existing signature beyond adding the brand
|
||||
- Adding runtime brand markers (type-only)
|
||||
- Renaming existing types or symbols
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `packages/core-shared/src/instrumentation/with-span.ts`
|
||||
- `packages/core-shared/src/instrumentation/with-span.test.ts`
|
||||
- `packages/core-shared/src/conformance/index.ts`
|
||||
|
||||
## Reviewer notes
|
||||
|
||||
Reject if brand is implemented with runtime tag rather than pure type.
|
||||
```
|
||||
|
||||
## State file — `docs/work/_system/_state.json`
|
||||
|
||||
A derived, committed, orchestrator-written index. Markdown is source of truth; `_state.json` is a fast-to-query mirror.
|
||||
|
||||
```json
|
||||
{
|
||||
"updated_at": "2026-05-12T16:42:00Z",
|
||||
"ready": ["02-instrumented-brand-attached"],
|
||||
"in_progress": [],
|
||||
"blocked": [],
|
||||
"escalated": [],
|
||||
"epics": {
|
||||
"conformance-system-v1": {
|
||||
"status": "in-progress",
|
||||
"ac_total": 47,
|
||||
"ac_completed": 8,
|
||||
"stories": {
|
||||
"01-define-feature-helper": {
|
||||
"status": "in-progress",
|
||||
"ac_total": 9,
|
||||
"ac_completed": 4,
|
||||
"tasks": {
|
||||
"01-define-feature-helper-exists": {
|
||||
"status": "done",
|
||||
"depends_on": [],
|
||||
"blocks": ["02-instrumented-brand-attached"],
|
||||
"ac_total": 4,
|
||||
"ac_completed": 4,
|
||||
"attempts": { "implementer": 1, "reviewer": 1 },
|
||||
"branch": "task/01-define-feature-helper-exists",
|
||||
"completed_at": "2026-05-12T14:23:00Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rules for `_state.json`
|
||||
|
||||
1. **Committed to git.** Audit trail visible in PRs.
|
||||
2. **Single writer:** orchestrator + pre-commit hook only. No agent writes it directly.
|
||||
3. **Derived from markdown.** Regenerable any time via `pnpm work rebuild-state`.
|
||||
4. **Canonical formatting.** Sorted keys, stable indentation, no trailing whitespace. Pre-commit normalizes via Prettier.
|
||||
5. **Merges serialized.** Orchestrator merges PRs one at a time. Parallel implementation in sandboxes is fine; only merge step is sequential.
|
||||
6. **Pre-commit regen.** When any `.task.md` / `.story.md` / `_epic.md` is staged, the hook regenerates `_state.json` from the markdown, re-stages it, and lets the commit proceed. The hook only blocks the commit if regeneration itself fails (e.g. malformed frontmatter, broken `depends-on` reference). This makes the markdown the unambiguous source of truth: if humans edit checkboxes directly, the JSON quietly catches up.
|
||||
|
||||
## Scope guards
|
||||
|
||||
| Level | In scope | Out of scope |
|
||||
| ----- | -------------------- | --------------------------- |
|
||||
| PRD | **required** | **required** |
|
||||
| Story | **required** | **required** |
|
||||
| Task | implicit (= AC list) | **optional but encouraged** |
|
||||
|
||||
The reviewer agent **explicitly checks the task's `Out of scope` section against the diff**. Rejects if the diff touches anything declared out of scope. This is the cheapest possible enforcement of "don't over-engineer" — pure text match, no AST needed.
|
||||
|
||||
## Conformance system integration
|
||||
|
||||
The five enforcement layers (detailed in [`feature-conformance-explainer.html`](./feature-conformance-explainer.html)):
|
||||
|
||||
| Layer | Latency | Catches |
|
||||
| ------------------------------------ | ------- | ------------------------------------------------------------------------------------------------- |
|
||||
| TypeScript brands | 0s | forgotten `withSpan` / `withAudit`; manifest ↔ binding-slot type mismatch |
|
||||
| AST-aware ESLint | <1s | manifest ↔ code drift; undeclared `bus.publish` / `auditLogger.log`; required cores not installed |
|
||||
| Boot assertion (`assertConformance`) | ~3s | binding type-casts that hid unwrapped factories; manifests edited without rebinding |
|
||||
| CI drift gate (`pnpm conformance`) | ~120s | orphan event consumers; scaffold drift from generator; required-cores ↔ workspace mismatch |
|
||||
| Fallow audit (`pnpm fallow`) | ~30–60s | whole-codebase — dead exports, duplicate code, circular deps, complexity hotspots |
|
||||
|
||||
### How conformance interacts with tasks
|
||||
|
||||
When a task adds an audit emission (e.g. `audits: ["user.created"]`):
|
||||
|
||||
1. Agent edits `feature.manifest.ts`
|
||||
2. The binding's branded slot type _now_ demands `Audited<F>` — TS2322 if the wrapper is missing
|
||||
3. Agent adds `withAudit(...)` in `bind-production.ts` → TS goes quiet
|
||||
4. Agent adds `auditLogger.log(...)` in the use-case factory → ESLint goes quiet
|
||||
5. Pre-commit `pnpm conformance` confirms all five layers pass
|
||||
6. PR submitted
|
||||
|
||||
Each step gives sub-second feedback. The agent's iteration loop is dominated by think + write, not by waiting for feedback.
|
||||
|
||||
## Workflow ordering (per task)
|
||||
|
||||
For any new use case or new behavior:
|
||||
|
||||
1. **Manifest** — declare the use case (or update audits/publishes/consumes if the task adds them). Pure declaration.
|
||||
2. **Contracts** — `xInputSchema`, `xOutputSchema`, `IXUseCase` type alias in the use-case file. Factory body throws `"not implemented"` if not yet written.
|
||||
3. **Tests (red)** — import contracts; write failing assertions that match the AC bullet.
|
||||
4. **Implementation (green)** — fill factory body, repository, binding, until tests pass.
|
||||
|
||||
For incremental work on an existing use case, step 1 is often a no-op (manifest already declared). For the first slice of a new use case, all four steps happen in one commit.
|
||||
|
||||
## Work shapes
|
||||
|
||||
The Epic / Story / Task hierarchy holds for everything; the **inner workflow shape varies** with the kind of work. Three shapes are recognised:
|
||||
|
||||
| Shape | Default home | Manifest involvement | Test gates |
|
||||
| ------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
|
||||
| **Backend** | feature packages | full (use cases, audits, publishes, consumes, jobs, realtime) | type-check + lint + conformance + unit/integration |
|
||||
| **Frontend** | `@repo/core-ui` and `features/<feature>/src/ui/` | partial — pages consume use cases via controllers | type-check + lint + component tests + Playwright screenshot (CI) |
|
||||
| **Infrastructure** | core packages, `apps/*/server/`, `docker-compose.yml`, `.github/`, ADRs | declarative — `requiredCores`, bind context | type-check + lint + conformance + ADR review |
|
||||
|
||||
The default shape is **backend** — what the rest of this doc describes. The two adapted shapes are summarised below; operational detail lives in their guides.
|
||||
|
||||
### Frontend (see `docs/guides/frontend-work-shape.md`)
|
||||
|
||||
- **Atomic design tiers** — atoms / molecules / organisms / templates / pages, generated via `pnpm turbo gen core-ui-component`. Tier-direction enforced by a new ESLint rule (`atomic-tier-import-direction`).
|
||||
- **Storybook is the spec.** Each AC bullet on a UI task maps to a story variant or a Storybook `play` function. Story files become the shared visual contract between human, implementer, and reviewer.
|
||||
- **Two test layers:**
|
||||
- **Component tests** (Vitest + Testing Library, or `play` on stories) — pre-commit gate, <5s
|
||||
- **Visual regression** via **Playwright screenshot tests** — CI gate, 30–120s, blocks PR merge on unapproved visual diffs
|
||||
- **Adapted four-step ordering for a pure UI slice:**
|
||||
1. **Story file** (the visual spec — analogous to the manifest entry for backend work)
|
||||
2. **Contracts** — props interface, variant types
|
||||
3. **Tests (red)** — component test + a default story
|
||||
4. **Implementation (green)** — make the component render and pass tests
|
||||
- **Reviewer agent** uses the existing Storybook MCP at `http://localhost:6006/mcp` to read existing components, list variants, and verify story coverage against the task's AC. Visual diff verdicts come from the Playwright screenshot CI step.
|
||||
- **Story split for page-level features:**
|
||||
```
|
||||
Epic: auth-v1
|
||||
├── Story (user): auth.signUp use case ← backend slices
|
||||
├── Story (technical): SignUpForm component(s) ← depends-on: signUp use case
|
||||
└── Story (technical): /sign-up page composition + E2E ← depends-on: SignUpForm
|
||||
```
|
||||
Each `depends-on` edge enforces sequential dispatch by the orchestrator.
|
||||
|
||||
### Infrastructure (see `docs/guides/infrastructure-work-shape.md`)
|
||||
|
||||
- **ADRs precede infrastructure work** the same way PRDs precede feature work — decision first, code second. ADRs live at `docs/adr/NNN-<slug>.md`.
|
||||
- **Two categories:**
|
||||
- **New optional core package** — `pnpm turbo gen core-package <name>`. Generator + conformance already accommodate (via `requiredCores` in manifests). No conformance extensions required.
|
||||
- **New infrastructure layer** (Redis, CDN, alternative CMS, additional message bus, …) — ADR + integration PRD + multiple stories.
|
||||
- **ADR authoring flow:**
|
||||
1. Human runs `pnpm work adr-new "<one-line proposal>"`
|
||||
2. **Dedicated ADR elicitation skill** interviews the human on Context / Drivers / Considered options / Trade-offs / Decision / Consequences (similar shape to the PRD elicitation skill but distinct template + heuristics)
|
||||
3. Agent drafts ADR at `docs/adr/NNN-<slug>.md` with `status: proposed`
|
||||
4. Human reviews, flips to `status: accepted` (or `rejected` / `superseded`)
|
||||
5. Accepted ADR(s) trigger integration PRD(s); the PRD flow proceeds normally
|
||||
- **Conformance extensions for infra:**
|
||||
- `core-package-shape-conforms-to-generator` — extends milestone iv's scaffold-drift check to core packages
|
||||
- `required-cores-in-workspace` — manifest declarations must match `pnpm-workspace.yaml` (already in milestone iv)
|
||||
|
||||
Two elicitation skills now sit at the funnel mouth — one for PRDs, one for ADRs. Same interview-style intake; different templates and decision frameworks.
|
||||
|
||||
## Pre-commit gates
|
||||
|
||||
When a commit lands in the sandbox or locally:
|
||||
|
||||
1. **Type-check** — brand satisfaction, manifest typing
|
||||
2. **Lint** — manifest ↔ code rules, in-file shape rules, pattern restrictions
|
||||
3. **Conformance script** — `pnpm conformance` (boot-style assertion at static scope)
|
||||
4. **Tests for changed feature** — `pnpm test --filter @repo/<feature>` passes
|
||||
5. **`_state.json` ↔ markdown sync** — pre-commit regen verifies consistency
|
||||
|
||||
Tests for _all_ features are NOT required to pass at pre-commit (that's CI's job). The gate enforces local soundness without blocking work in unaffected areas.
|
||||
|
||||
## Agent roles
|
||||
|
||||
### PRD eliciter agent
|
||||
|
||||
- Skill: dedicated PRD elicitation (interview-style, similar shape to `superpowers:brainstorming`)
|
||||
- Inputs: short brief from human (`pnpm work prd-new "<idea>"`)
|
||||
- Behavior: asks questions one at a time, builds shared understanding across Problem / Goal / Scope / Constraints / Success / Requirements
|
||||
- Output: `<date>-<slug>.prd.md` with `status: draft`
|
||||
- Hand-off: human reviews, flips to `status: approved`
|
||||
|
||||
### ADR eliciter agent
|
||||
|
||||
- Skill: dedicated ADR elicitation (interview-style; distinct from PRD elicitation)
|
||||
- Inputs: short brief from human (`pnpm work adr-new "<proposal>"`)
|
||||
- Behavior: drives the conversation across Context / Drivers / Considered options / Trade-offs / Decision / Consequences. Pushes the human to articulate alternatives explicitly before settling on a decision.
|
||||
- Output: `docs/adr/NNN-<slug>.md` with `status: proposed`
|
||||
- Hand-off: human reviews, flips to `status: accepted` (or `rejected` / `superseded`)
|
||||
- Accepted ADRs are the trigger for downstream integration PRDs
|
||||
|
||||
### Decomposer agent
|
||||
|
||||
- Skill: structured PRD-to-epic-and-stories decomposition
|
||||
- Inputs: a PRD file with `status: approved`
|
||||
- Behavior: produces `_epic.md` and one `_story.md` per requirement, with story-level AC bullets that hint at task decomposition
|
||||
- **Default scope: stories only.** Task-level decomposition is a second pass: `pnpm work decompose-tasks <story>`
|
||||
- Does NOT write `_state.json` directly (orchestrator does that on next dispatch tick)
|
||||
|
||||
### Implementer agent
|
||||
|
||||
- Sandcastle dispatch with `implementer.prompt.md`
|
||||
- Inputs: a single task markdown file (full context)
|
||||
- Behavior: writes code + tests to satisfy the AC; runs `pnpm test --filter` and `pnpm conformance` locally; commits; pushes the sandbox branch
|
||||
- **Read-only on task markdown.** Returns structured output via sandcastle:
|
||||
```json
|
||||
{
|
||||
"status": "complete" | "blocked" | "needs-clarification",
|
||||
"ac_satisfied": [0, 1, 2, 3],
|
||||
"files_changed": ["packages/.../with-span.ts", "..."],
|
||||
"commit_sha": "abc123",
|
||||
"notes": "..."
|
||||
}
|
||||
```
|
||||
- Does NOT edit `.task.md`, `.story.md`, `_epic.md`, or `_state.json`. The orchestrator translates the structured output into markdown checkbox flips and JSON state updates in a single post-merge commit.
|
||||
|
||||
### Reviewer agent
|
||||
|
||||
- Sandcastle dispatch with `reviewer.prompt.md`
|
||||
- Inputs: task markdown + diff from implementer
|
||||
- Behavior: verifies each AC bullet against the diff; checks `Out of scope` is respected; verifies tests cover AC bullets; runs `pnpm conformance` and `pnpm test --filter`
|
||||
- Returns structured output:
|
||||
```json
|
||||
{
|
||||
"decision": "approve" | "reject",
|
||||
"ac_verified": [0, 1, 2, 3],
|
||||
"scope_violations": [],
|
||||
"notes": "..."
|
||||
}
|
||||
```
|
||||
- Does NOT edit anything in the repo.
|
||||
- **For frontend tasks**, the reviewer additionally:
|
||||
- Queries the Storybook MCP (`http://localhost:6006/mcp`) to verify story coverage and inspect rendered output
|
||||
- Treats the Playwright screenshot CI step's verdict as a required input — unapproved visual diffs trigger `reject`
|
||||
|
||||
### Orchestrator
|
||||
|
||||
- Plain TypeScript script (`scripts/work-dispatch.ts`)
|
||||
- Reads `_state.json` to find ready tasks (all deps `done`)
|
||||
- For each ready task:
|
||||
1. Marks task `status: in-progress`, regenerates `_state.json`, commits the marker
|
||||
2. Dispatches sandcastle implementer
|
||||
3. On implementer return: dispatches sandcastle reviewer with task + diff
|
||||
4. On reviewer `approve`: serial-merges to `main`, in one commit flips task checkbox, increments parent story checkbox if all tasks done, increments parent epic checkbox if all stories done, regenerates `_state.json`
|
||||
5. On reviewer `reject`: appends reviewer notes to the task's "Reviewer notes" section, increments `attempts.implementer`, re-dispatches (subject to `max-attempts`)
|
||||
6. On `attempts.implementer >= max-attempts`: marks `status: escalated`, posts a summary, stops dispatching
|
||||
- Continues until no ready tasks remain
|
||||
|
||||
## Sandcastle config
|
||||
|
||||
`.sandcastle/Dockerfile` **extends the existing CI image**. To be identified during the work-system-v1 epic. Must include:
|
||||
|
||||
- Node + pnpm at repo's pinned versions
|
||||
- `pnpm install --frozen-lockfile` baked in
|
||||
- Access to `pnpm conformance`, `pnpm test`, `pnpm lint`, `pnpm typecheck`
|
||||
- Git config for agent commits
|
||||
|
||||
Prompt templates use sandcastle's `{{VAR}}` substitution + `` !`cmd` `` injection:
|
||||
|
||||
- `implementer.prompt.md` uses `{{TASK_FILE_CONTENT}}` and `` !`git log -1 --oneline` `` for context
|
||||
- `reviewer.prompt.md` uses `{{TASK_FILE_CONTENT}}` + `{{DIFF}}`
|
||||
- `decomposer.prompt.md` uses `{{PRD_FILE_CONTENT}}`
|
||||
- `prd-eliciter.prompt.md` uses `{{INITIAL_BRIEF}}` and runs the interview loop
|
||||
|
||||
Branch strategy: per-task feature branch (`task/<task-id>`), merged sequentially to `main` by the orchestrator.
|
||||
|
||||
## Bootstrap order — conformance first
|
||||
|
||||
### Tier 1 — Conformance system (human-driven)
|
||||
|
||||
Build the conformance system manually. `docs/work/conformance-system-v1/` markdown files capture the work (practising the task format on real work) but no `_state.json`, no sandcastle dispatch, no orchestrator.
|
||||
|
||||
Stories in order (each itself a vertical slice — system code + generator update + doc update + applied to one feature):
|
||||
|
||||
1. **defineFeature helper + Instrumented brand** — applied to `auth.signIn`
|
||||
2. **Captured + Audited brands** — wrappers updated
|
||||
3. **`assertConformance` + boot wiring** — rolled to all three apps
|
||||
4. **AST-aware ESLint rules** — 5–6 new type-aware rules
|
||||
5. **CI drift gate** (`pnpm conformance`)
|
||||
6. **Generator emits manifest + contracts + test stubs**
|
||||
7. **Documentation rewrite** — agent-workflow.md, CLAUDE.md, AGENTS.md, tdd-workflow.md
|
||||
8. **Migrate auth feature** to the new pattern (reference)
|
||||
|
||||
### Tier 2 — Work system (human-driven, bootstraps automation)
|
||||
|
||||
Once conformance is in place, build the dispatch substrate:
|
||||
|
||||
1. `docs/work/` skeleton, README, templates
|
||||
2. `_state.json` schema + `pnpm work rebuild-state`
|
||||
3. Orchestrator script + DAG + retry-cap logic
|
||||
4. `.sandcastle/` config (extends existing CI image)
|
||||
5. PRD elicitation skill
|
||||
6. ADR elicitation skill (separate skill, similar interview shape)
|
||||
7. Decomposer agent + prompts
|
||||
8. Implementer + reviewer prompts (with Storybook MCP wiring for frontend reviewer)
|
||||
9. `pnpm work` CLI surface (including `work adr-new`)
|
||||
10. Pre-commit hooks (state regen, conformance gate)
|
||||
11. Playwright screenshot test infrastructure (CI gate for frontend tasks)
|
||||
|
||||
### Tier 3 — Migration + future work (dispatch-driven)
|
||||
|
||||
With both systems in place, remaining feature migrations and all future work flows through sandcastle:
|
||||
|
||||
- Migrate `blog`, `media`, `navigation`, `marketing-pages` (one story each)
|
||||
- All new features authored via PRD → decompose → dispatch loop
|
||||
|
||||
## Deferred decisions
|
||||
|
||||
These are explicitly deferred until the tier that needs them:
|
||||
|
||||
1. **Existing `task-create` skill (ClickUp mirror)** — coexist or retire. Decide once the work system is in place. Frontmatter is open-ended so `clickup-id` can be added later if needed.
|
||||
2. **Existing CI Docker image identity** — identify and document during the `.sandcastle/Dockerfile` story.
|
||||
3. **Per-epic state files vs. one global** — start with one global `_state.json`. Move to per-epic only if serialized merges become a throughput bottleneck.
|
||||
4. **Custom git merge driver for `_state.json`** — start without; serialized merges should suffice. Add if needed.
|
||||
|
||||
## Open questions (to revisit during implementation)
|
||||
|
||||
- **Q1: Single manifest registry per app, or per-feature?** (From the explainer §10.) Lean: per-feature, with a tiny app-side aggregator.
|
||||
- **Q2: How much of the manifest is generated vs hand-written?** Lean: humans edit; ESLint flags mismatches without auto-fixing.
|
||||
- **Q3: Inline symbol declaration in manifest, or registry mapping?** Lean: registry holds the mapping, manifest stays content-only.
|
||||
- **Q4: What happens when an optional core is absent?** Lean: typed surface gates the field — `audits: readonly never[]` when `core-audit` is unbound.
|
||||
- **Q5: Escape hatch for legitimate exceptions?** Lean: `// @conformance-skip: <rule> — <reason>` comment honoured by ESLint + boot assertion, with allowlist growth gated in CI.
|
||||
|
||||
## Acceptance criteria (for this whole design)
|
||||
|
||||
This design is "done" when:
|
||||
|
||||
- [ ] `docs/work/` exists with templates, `_state.json` schema, README
|
||||
- [ ] Conformance system v1 is implemented through all five enforcement layers
|
||||
- [ ] All five feature packages have manifests
|
||||
- [ ] All three apps run `assertConformance` at boot
|
||||
- [ ] `pnpm conformance` is a CI gate
|
||||
- [ ] `turbo gen feature` emits manifest + contracts + test stubs
|
||||
- [ ] `.sandcastle/` config exists with implementer/reviewer/decomposer/eliciter prompts
|
||||
- [ ] PRD elicitation skill exists and is invocable
|
||||
- [ ] ADR elicitation skill exists and is invocable
|
||||
- [ ] Orchestrator (`pnpm work dispatch`) runs end-to-end on a real task
|
||||
- [ ] Frontend ESLint rules cover atomic-tier direction and story/test sibling presence
|
||||
- [ ] Playwright screenshot tests run as a CI gate for frontend work
|
||||
- [ ] Documentation reflects the manifest-first workflow (CLAUDE.md, AGENTS.md, `docs/guides/`)
|
||||
- [ ] Frontend + infrastructure work-shape guides exist at `docs/guides/`
|
||||
|
||||
## References
|
||||
|
||||
- [Feature conformance explainer (interactive)](./feature-conformance-explainer.html)
|
||||
- [Vertical feature spec](./vertical-feature-spec.md)
|
||||
- [Template tiers](./template-tiers.md)
|
||||
- [Frontend work shape guide](../guides/frontend-work-shape.md)
|
||||
- [Infrastructure work shape guide](../guides/infrastructure-work-shape.md)
|
||||
- [TDD workflow guide](../guides/tdd-workflow.md)
|
||||
- [Scaffolding a feature guide](../guides/scaffolding-a-feature.md)
|
||||
- [Adding a feature guide](../guides/adding-a-feature.md)
|
||||
- [Sandcastle (orchestration library)](https://github.com/mattpocock/sandcastle)
|
||||
Reference in New Issue
Block a user