10-task plan for standing up the conformance ESLint plugin in
@repo/core-eslint and shipping three structural rules:
- feature-must-have-manifest (warn): use-case files require a manifest
- usecase-must-have-test-file (error): TDD sibling test enforcement
- required-cores-installed (error): manifest cores ↔ workspace.yaml
Scope deliberately excludes manifest-AST analysis (no-undeclared-event-
publish, no-undeclared-audit) — those require parsing the manifest's TS
source as JS and walking the use-case AST, deferred to plan iii.b.
Uses regex-based manifest source extraction to avoid pulling in the
TypeScript compiler API at lint time. Manifest shape is constrained by
the literal `as const` form that defineFeature enforces, so the regex
path is sufficient.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
12-task implementation plan for the runtime boot-time check of the
conformance system. Reifies the phantom-type brands from milestone i as
non-enumerable runtime markers via Object.defineProperty, and ships
assertFeatureConformance(container, manifest, symbols, ctx) which walks
the manifest, resolves each use case from the feature's container, and
throws ConformanceError synchronously when a binding is missing a
required brand.
Per-feature self-assertion: each bindProductionX(ctx) calls
assertFeatureConformance at its tail, so the boot check runs once per
feature and is forward-compatible with future apps wiring those binders.
Also bundles the two forward-looking items the milestone-i reviewer
flagged (re-export authManifest from auth root barrel; TODO breadcrumb
in withAudit for future automation).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
13-task implementation plan for the type-level seam of the conformance system.
Ships brand types (Instrumented/Captured/Audited), defineFeature helper,
ProductionUseCase branded slot, withAudit wrapper, authManifest, and rebinds
auth.signIn through the branded slot — with a negative type test asserting
unwrapped factories are rejected at the slot.
Each task is a single red→green TDD cycle with one commit. Companion
docs/work/conformance-system-v1/ epic + story records are created early in
the plan so subsequent agents have full context when picking up later
stories.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the design from the brainstorm session on agent-first development
in this template. Architecture doc covers the four interlocking pillars:
- Conformance engine (manifest + brands + ESLint + boot + CI gate)
- Agent workflow (PRD -> Epic -> Story -> Task; manifest-first ordering;
TDD per slice; in/out scope at every level)
- Local task system at docs/work/ (filesystem markdown, derived committed
_state.json, single-writer orchestrator rule)
- Sandcastle orchestrator (implementer + reviewer loop, DAG-respecting,
configurable retry cap)
Work-shape guides extend the architecture doc with operational detail for
frontend work (atomic design, Storybook-as-spec, component + Playwright
screenshot test gates, Storybook MCP reviewer integration) and
infrastructure work (ADR-first flow, dedicated ADR elicitation skill,
optional core packages vs. new infrastructure layers).
Phasing is conformance-first: build the enforcement system manually, then
build the dispatch substrate, then migrate remaining features through it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds the interactive HTML explainer for the feature-conformance enforcement
design, covering the four layers (TS brands, ESLint, boot assertion, CI gate),
manifest playground, mistake catalog, layer composition, build-order milestones,
anchor points in the repo, and an "extensions" section on sharper AST checks
and code-conventions enforcement.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The agent that produced the explainer guessed three ADR filenames
(adr-014-instrumentation-interfaces.md, adr-017-otel-migration.md,
adr-015-events-jobs.md). The actual files use different slugs.
Touches the deeper architecture surfaces the Phase 6 sweep skipped:
- overview.md: split must-have (core-shared, core-cms, core-api) from
optional (core-trpc, core-ui, core-realtime, core-events, core-audit);
add core-audit to the Five tags optional list
- dependency-flow.md: extend the bindAll diagram with resolveAudit;
add auditLog row to the BindContext table; rename the
TRACER/LOGGER/METRICS heading to include AUDIT (ADR-018); note the
R52-style boundary rule for @repo/core-audit (consume via protocol)
- vertical-feature-spec.md: target-state section now states 3 must-have
+ 5 optional cores; tag matrix includes the optional cores; bind-
production signature destructure includes auditLog
- di-explainer.html: §08 instrumentation gains an IAuditLog block + the
Wiring path tree shows resolveAudit + auditLog in ctx
- testing-strategy.md: RecordingAuditLog reference + reset() guidance
2-phase design for `pnpm turbo gen core-ui-component`. Prompts for tier
(atom/molecule/organism) + name (PascalCase) and emits the established
4-file component pattern (component.tsx, component.stories.tsx,
component.test.tsx, index.ts) into the matching `packages/core-ui/src/<tier>s/`
folder. Splices the new export into the tier barrel via `// <gen:<tier>s>`
anchors.
Phase A adds the anchors to the core-ui template's three tier barrels and
regenerates the byte-identical reconstruction snapshot. Phase B ships the
generator, templates, tests, and docs. Refuses to run if core-ui isn't
scaffolded; doesn't touch Storybook config (existing stories glob covers
new component stories).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AGENTS.md bind-production code block: shows the slim default state
(no @repo/core-events / @repo/core-realtime imports, BindProductionContext
with no generic args) with a comment pointing to the scaffold workflow.
The previous block showed a fully-wired post-scaffold state without
signaling that none of those packages exist in main.
- bind-protocols.test.ts: top-of-file comment clarifies what these tests
actually verify (protocol shapes have required methods) vs what the
spec text might suggest (full assignability of optional packages'
interfaces — that's verified by the e2e reconstruction tests, not here).
- core-package-generator.md: drops two stale "Until Phases 3-6 land"
parentheticals — the phases shipped.
- config.test.ts: extends the choices assertion to cover all 4 names
(realtime, events, trpc, ui).
- marketing-pages bind-* comments: reverse the inverted optional/required
language. queue (IJobQueue) is from core-shared and always present;
bus is the optional one (from @repo/core-events when scaffolded).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- CLAUDE.md project-overview lists must-have core packages (shared/cms/api)
separately from the four optionals (realtime/events/trpc/ui) with their
scaffold command. Read first list adds template-tiers.md and notes that
the events + realtime guides require their package to be scaffolded first.
- overview.md "Five tags" updated: core-composition is 2 must-have plus
trpc (optional); core is 1 must-have plus ui/realtime/events (optional).
- dependency-flow.md fix: replaces the stale `// in packages/core-trpc`
example with `// in packages/core-shared` (core-trpc is now optional and
may not exist in a slim template).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AGENTS.md (root): marks core-ui as optional in the package table and
boundary rules; points per-package docs to the .hbs template
- apps/storybook/AGENTS.md: rewrites around no-core-ui-by-default;
stories glob and globals.css import described as post-scaffold steps
- apps/web-next/AGENTS.md: cross-reference updated to template file
- apps/web-tanstack/AGENTS.md: cross-reference updated to template file
- docs/architecture/data-flow-explainer.html: core-ui bullet notes
optional status + generator command
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
