gspec - npm Package Compare versions
| #!/usr/bin/env node | ||
| // gspec PostToolUse hook (Claude) — style-guide token-literals adapter (model-free, advisory). | ||
| // | ||
| // gspec/style.html's token block is the single source of truth for color; | ||
| // every other rule must reference tokens via var(--…). After a Write/Edit to | ||
| // the HTML style guide, this flags literal colors declared outside the token | ||
| // block (exit 2) so Claude re-points them at tokens. Decision logic lives in | ||
| // the engine-neutral floor module; this adapter parses the event and reads the | ||
| // file. Fails OPEN. | ||
| // | ||
| // NOTE: the ./floors/ import resolves at the INSTALLED location | ||
| // (.claude/hooks/floors/); this file is never executed from the source tree. | ||
| import { readFileSync } from 'node:fs'; | ||
| import { resolve, relative } from 'node:path'; | ||
| import { appliesToTokenLiterals, tokenLiteralViolations } from './floors/token-literals.mjs'; | ||
| try { | ||
| let evt = {}; | ||
| try { evt = JSON.parse(readFileSync(0, 'utf-8')); } catch { process.exit(0); } | ||
| const filePath = evt?.tool_input?.file_path; | ||
| if (!filePath) process.exit(0); | ||
| const projectDir = process.env.CLAUDE_PROJECT_DIR || evt.cwd || process.cwd(); | ||
| const rel = relative(projectDir, resolve(projectDir, filePath)).replace(/\\/g, '/'); | ||
| if (!appliesToTokenLiterals(rel)) process.exit(0); | ||
| let content; | ||
| try { content = readFileSync(resolve(projectDir, filePath), 'utf-8'); } catch { process.exit(0); } | ||
| const violations = tokenLiteralViolations(content); | ||
| if (!violations.length) process.exit(0); | ||
| process.stderr.write(`gspec token-literals: ${violations.join('\n')}\n`); | ||
| process.exit(2); | ||
| } catch { | ||
| process.exit(0); // fail open | ||
| } |
| // Floor: style-guide token literals (pure, I/O-free). | ||
| // | ||
| // In gspec/style.html the design-token block (custom properties on `:root` / | ||
| // theme-key selectors) is the single source of truth for color; every other | ||
| // rule must reference tokens via var(--…). A literal color anywhere else is a | ||
| // second copy of a decision that can drift from the first — the dominant QA | ||
| // failure mode in large style guides (see gspec-conventions, "Single source of | ||
| // truth"). This module decides whether a path is subject to the check and | ||
| // finds literal colors declared outside token blocks, in <style> CSS and in | ||
| // inline style="…" attributes. It does NOT scan text content — a swatch label | ||
| // that *displays* a hex code is documentation, not a declaration. Entry points | ||
| // read the file and signal the violation. | ||
| // Which paths this floor governs. Only the HTML style guide — a Markdown | ||
| // guide's token tables aren't mechanically separable from its prose. | ||
| export function appliesToTokenLiterals(rel) { | ||
| return String(rel).replace(/\\/g, '/') === 'gspec/style.html'; | ||
| } | ||
| // A selector under which literal colors are allowed: the token blocks. | ||
| // `:root`, theme-key attribute selectors ([data-theme=…]), and the common | ||
| // theme-class conventions (.dark/.light/.theme-*). | ||
| function isTokenSelector(sel) { | ||
| const s = String(sel).trim(); | ||
| return s.includes(':root') || s.includes('[data-theme') || /(^|[\s,>])\.(dark|light|theme-[\w-]+)\b/.test(s); | ||
| } | ||
| // Literal color values. Keyword colors and sizes are deliberately out of | ||
| // scope (too noisy to guard mechanically); hex/rgb/hsl/oklch cover how a | ||
| // palette actually leaks. var()/color-mix() over tokens never match. | ||
| const COLOR_RE = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(/gi; | ||
| const MAX_REPORTED = 5; | ||
| function stripCssComments(css) { | ||
| return String(css).replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' ')); | ||
| } | ||
| // Literal colors declared outside a token block ([] = clean). Assumes the | ||
| // caller already filtered with appliesToTokenLiterals(). | ||
| export function tokenLiteralViolations(content) { | ||
| const html = String(content); | ||
| const offenders = []; // { literal, where } | ||
| // <style> blocks: walk declarations with a selector stack so a :root block | ||
| // nested in @media still counts as a token block. | ||
| for (const m of html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) { | ||
| const css = stripCssComments(m[1]); | ||
| const stack = []; | ||
| let buf = ''; | ||
| for (const ch of css) { | ||
| if (ch === '{') { stack.push(buf.trim()); buf = ''; continue; } | ||
| if (ch === '}') { scanDecl(buf, stack, offenders); stack.pop(); buf = ''; continue; } | ||
| if (ch === ';') { scanDecl(buf, stack, offenders); buf = ''; continue; } | ||
| buf += ch; | ||
| } | ||
| } | ||
| // Inline style attributes: never a token block, so any literal color hits. | ||
| for (const m of html.matchAll(/\bstyle\s*=\s*("([^"]*)"|'([^']*)')/gi)) { | ||
| const decl = m[2] ?? m[3] ?? ''; | ||
| for (const lit of decl.match(COLOR_RE) || []) offenders.push({ literal: lit, where: 'an inline style attribute' }); | ||
| } | ||
| if (!offenders.length) return []; | ||
| const shown = offenders.slice(0, MAX_REPORTED) | ||
| .map((o) => `"${o.literal}" in ${o.where}`).join(', '); | ||
| const more = offenders.length > MAX_REPORTED ? ` (and ${offenders.length - MAX_REPORTED} more)` : ''; | ||
| return [ | ||
| `gspec/style.html declares literal colors outside the design-token block: ${shown}${more}. ` + | ||
| 'The token block (:root / theme-key selectors) is the only place a literal color may appear — ' + | ||
| 'style everything else with var(--…) so values cannot drift.', | ||
| ]; | ||
| } | ||
| function scanDecl(decl, stack, offenders) { | ||
| if (!decl.trim() || stack.length === 0) return; // outside any rule (stray text) | ||
| if (stack.some(isTokenSelector)) return; // inside a token block | ||
| for (const lit of decl.match(COLOR_RE) || []) { | ||
| offenders.push({ literal: lit, where: `"${stack[stack.length - 1] || '(unknown selector)'}"` }); | ||
| } | ||
| } |
| // Unit tests for the style-guide token-literals floor. Run: node --test plugin/hooks/floors/ | ||
| import { test } from 'node:test'; | ||
| import assert from 'node:assert/strict'; | ||
| import { appliesToTokenLiterals, tokenLiteralViolations } from './token-literals.mjs'; | ||
| const page = (css, body = '') => `<!-- spec-version: v1 -->\n<!DOCTYPE html>\n<html><head><style>${css}</style></head><body>${body}</body></html>`; | ||
| test('governs only gspec/style.html', () => { | ||
| assert.equal(appliesToTokenLiterals('gspec/style.html'), true); | ||
| assert.equal(appliesToTokenLiterals('gspec/style.md'), false); | ||
| assert.equal(appliesToTokenLiterals('gspec/design/mockup.html'), false); | ||
| assert.equal(appliesToTokenLiterals('style.html'), false); | ||
| }); | ||
| test('a token-driven guide is clean: literals in :root and theme keys, var() everywhere else', () => { | ||
| const css = ` | ||
| :root { --color-accent: #6366f1; --color-surface: rgb(255 255 255); } | ||
| @media (prefers-color-scheme: dark) { :root { --color-surface: #1a1d23; } } | ||
| [data-theme="dark"] { --color-accent: hsl(239 84% 72%); } | ||
| .button { background: var(--color-accent); color: var(--color-surface); } | ||
| .card { border-color: color-mix(in srgb, var(--color-accent), transparent); }`; | ||
| assert.deepEqual(tokenLiteralViolations(page(css)), []); | ||
| }); | ||
| test('flags a literal color in a component rule, naming the literal and selector', () => { | ||
| const css = `:root { --color-accent: #6366f1; }\n.button { background: #6366f1; }`; | ||
| const out = tokenLiteralViolations(page(css)); | ||
| assert.equal(out.length, 1); | ||
| assert.match(out[0], /"#6366f1" in ".button"/); | ||
| assert.match(out[0], /var\(--…\)/); | ||
| }); | ||
| test('flags literal colors in inline style attributes', () => { | ||
| const out = tokenLiteralViolations(page(':root { --x: #fff; }', '<div style="color: #ff0000">bad</div>')); | ||
| assert.equal(out.length, 1); | ||
| assert.match(out[0], /"#ff0000" in an inline style attribute/); | ||
| }); | ||
| test('a nested :root inside @media is a token block; hex in comments and text content never hits', () => { | ||
| const css = ` | ||
| @media (max-width: 768px) { :root { --space-4: 1rem; --color-bg: #0e0f12; } } | ||
| /* #ffffff on #1a1d23 = 15.2:1 */ | ||
| .swatch { background: var(--color-bg); }`; | ||
| const body = '<code>#6366f1</code> and a swatch label #1a1d23'; | ||
| assert.deepEqual(tokenLiteralViolations(page(css, body)), []); | ||
| }); | ||
| test('caps the report and counts the rest', () => { | ||
| const rules = Array.from({ length: 8 }, (_, i) => `.r${i} { color: #00000${i}; }`).join('\n'); | ||
| const out = tokenLiteralViolations(page(rules)); | ||
| assert.equal(out.length, 1); | ||
| assert.match(out[0], /and 3 more/); | ||
| }); |
@@ -11,2 +11,7 @@ --- | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -13,0 +18,0 @@ |
@@ -49,6 +49,26 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -22,2 +22,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -24,0 +31,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -22,3 +22,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -32,8 +32,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -18,2 +18,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -20,0 +21,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -78,2 +78,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -106,5 +113,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -111,0 +118,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -16,5 +16,5 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
@@ -73,9 +73,29 @@ ## Input | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -99,2 +119,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -120,2 +147,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -145,2 +177,3 @@ | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -183,8 +216,10 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -196,2 +231,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -201,3 +238,3 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
@@ -212,8 +249,10 @@ | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
@@ -73,2 +73,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -99,3 +106,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -102,0 +109,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -70,2 +70,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -72,0 +73,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -97,2 +97,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -118,2 +125,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -176,2 +188,3 @@ | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -178,0 +191,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -13,3 +13,3 @@ --- | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -144,2 +144,9 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -172,2 +179,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -247,6 +255,6 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -253,0 +261,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -13,3 +13,3 @@ --- | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -73,2 +73,9 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -75,0 +82,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -86,2 +86,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -114,2 +121,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -152,3 +160,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
@@ -155,0 +163,0 @@ ## Return contract |
@@ -101,2 +101,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -122,2 +129,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -180,2 +192,3 @@ | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -182,0 +195,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -102,2 +102,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -130,2 +137,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -132,0 +140,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -44,2 +44,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -46,0 +47,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -77,9 +77,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -103,2 +123,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -124,2 +151,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -182,2 +214,3 @@ | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -184,0 +217,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -50,3 +50,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -60,6 +60,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -88,2 +88,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -109,2 +116,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -167,2 +179,3 @@ | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -215,3 +228,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -218,0 +231,0 @@ ## Templates (seed from a saved style) |
| --- | ||
| name: architecture-validator | ||
| description: "Validate gspec/architecture.md against the architecture quality bar and return a structured verdict. Read-only." | ||
| description: "Validate the architecture spec set (gspec/architecture.md + any architecture/*.md sub-files) against the architecture quality bar, including the layout gate and tier boundary. Read-only; returns a structured verdict." | ||
| skills: [gspec-qa, gspec-architect, gspec-conventions, gspec-memory] | ||
@@ -13,8 +13,10 @@ tools: Read, Grep, Glob | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
| --- | ||
| name: architecture-writer | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-deployable gspec/architecture/<name>.md sub-files for a multi-deployable system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| skills: [gspec-architect, gspec-conventions, gspec-agnosticism, gspec-memory] | ||
@@ -16,8 +16,10 @@ tools: Read, Write, Edit, Glob, Grep | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -29,2 +31,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -34,2 +38,2 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. |
@@ -14,3 +14,3 @@ --- | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -17,0 +17,0 @@ ## Job |
@@ -16,3 +16,3 @@ --- | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -19,0 +19,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -14,6 +14,6 @@ --- | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -20,0 +20,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -16,5 +16,5 @@ --- | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| ## Return contract | ||
| Return the **draft plan body** — the `## Plan` task list in the standard format (YAML frontmatter with `feature:` slug + `spec-version`, then `- [ ] **T<n>** [P] **P<n>** … / deps: / covers:`, with an optional `supersedes: T<n>` line on any task that replaces a superseded checked one) — plus a short note: total tasks, how many `[P]`, which tasks are new vs. preserved-verbatim, any capability you could not decompose (and why), and any cross-feature dependencies you noticed. Do not write any file. |
@@ -18,5 +18,5 @@ --- | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -23,0 +23,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -25,3 +25,3 @@ --- | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -28,0 +28,0 @@ ## Templates (seed from a saved style) |
@@ -14,7 +14,7 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input | ||
| $ARGUMENTS |
@@ -40,3 +40,3 @@ --- | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -43,0 +43,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -14,0 +14,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -14,0 +14,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
@@ -11,2 +11,7 @@ --- | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -13,0 +18,0 @@ |
@@ -49,6 +49,26 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -22,2 +22,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -24,0 +31,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -22,3 +22,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -32,8 +32,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -17,2 +17,9 @@ --- | ||
| ## On a revision run, capture is part of your return contract | ||
| A run whose input carries a QA verdict or a relayed user correction is a **capture run** — the trigger above has fired. Do not return from one without exactly one of: | ||
| - an address-tagged lesson written to your silo, or | ||
| - an explicit line in your returned summary stating why the finding was purely project-specific (no generalizable lesson to keep). | ||
| Returning from a capture run with neither — or with only run-specific trivia stored — is an incomplete run. Failing the same gate twice and recording nothing means the next run repeats the mistake. | ||
| ## The address tag — required on every lesson | ||
@@ -19,0 +26,0 @@ Every entry carries a **target + layer** so the distiller (the learning loop's reviewer) can route it to the right durable home. One entry looks like: |
@@ -18,2 +18,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -20,0 +21,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
| name = "architecture-validator" | ||
| description = "Validate gspec/architecture.md against the architecture quality bar and return a structured verdict. Read-only." | ||
| description = "Validate the architecture spec set (gspec/architecture.md + any architecture/*.md sub-files) against the architecture quality bar, including the layout gate and tier boundary. Read-only; returns a structured verdict." | ||
| sandbox_mode = "read-only" | ||
@@ -21,2 +21,3 @@ developer_instructions = ''' | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -92,9 +93,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -118,2 +139,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -139,9 +167,11 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. | ||
| ''' |
| name = "architecture-writer" | ||
| description = "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description = "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-deployable gspec/architecture/<name>.md sub-files for a multi-deployable system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| sandbox_mode = "workspace-write" | ||
@@ -52,9 +52,29 @@ developer_instructions = ''' | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -78,2 +98,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -99,2 +126,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -120,8 +152,10 @@ | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -133,2 +167,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -138,3 +174,3 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| ''' |
@@ -105,2 +105,9 @@ name = "build-orchestrator" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -127,3 +134,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -130,0 +137,0 @@ ## Job |
@@ -53,2 +53,9 @@ name = "codebase-inspector" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -77,3 +84,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -80,0 +87,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -49,2 +49,3 @@ name = "distiller" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -51,0 +52,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -21,2 +21,3 @@ name = "feature-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -117,2 +118,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -119,0 +127,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -77,2 +77,9 @@ name = "feature-writer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -98,2 +105,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -100,0 +112,0 @@ |
@@ -21,2 +21,3 @@ name = "implementation-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -23,0 +24,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -122,2 +122,9 @@ name = "implementer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -144,6 +151,6 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -150,0 +157,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -66,2 +66,9 @@ name = "plan-decomposer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -90,3 +97,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
@@ -93,0 +100,0 @@ ## Return contract |
@@ -21,2 +21,3 @@ name = "plan-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -106,2 +107,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -108,0 +116,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -21,2 +21,3 @@ name = "practices-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -121,2 +122,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -123,0 +131,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -81,2 +81,9 @@ name = "practices-writer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -102,2 +109,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -104,0 +116,0 @@ |
@@ -21,2 +21,3 @@ name = "profile-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -117,2 +118,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -119,0 +127,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -77,2 +77,9 @@ name = "profile-writer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -79,0 +86,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -77,2 +77,9 @@ name = "research-writer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -98,2 +105,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -100,0 +112,0 @@ |
@@ -53,2 +53,9 @@ name = "spec-cross-referencer" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -79,5 +86,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -84,0 +91,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -53,2 +53,9 @@ name = "spec-migrator" | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -55,0 +62,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -21,2 +21,3 @@ name = "stack-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -92,9 +93,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -118,2 +139,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -120,0 +148,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -52,9 +52,29 @@ name = "stack-writer" | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -78,2 +98,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -99,2 +126,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -101,0 +133,0 @@ |
@@ -21,2 +21,3 @@ name = "style-validator" | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -65,3 +66,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -75,6 +76,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -103,2 +104,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -105,0 +113,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -25,3 +25,3 @@ name = "style-writer" | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -35,6 +35,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -63,2 +63,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -84,2 +91,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -148,3 +160,3 @@ | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -151,0 +163,0 @@ ## Templates (seed from a saved style) |
@@ -15,6 +15,6 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input |
@@ -41,3 +41,3 @@ --- | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -44,0 +44,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -12,3 +12,3 @@ --- | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -15,0 +15,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -12,3 +12,3 @@ --- | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -15,0 +15,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
| --- | ||
| name: architecture-validator | ||
| description: "Validate gspec/architecture.md against the architecture quality bar and return a structured verdict. Read-only." | ||
| description: "Validate the architecture spec set (gspec/architecture.md + any architecture/*.md sub-files) against the architecture quality bar, including the layout gate and tier boundary. Read-only; returns a structured verdict." | ||
| model: inherit | ||
@@ -24,2 +24,3 @@ readonly: true | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -95,9 +96,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -121,2 +142,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -142,8 +170,10 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
| --- | ||
| name: architecture-writer | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-deployable gspec/architecture/<name>.md sub-files for a multi-deployable system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| model: inherit | ||
@@ -54,9 +54,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -80,2 +100,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -101,2 +128,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -122,8 +154,10 @@ | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -135,2 +169,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -140,2 +176,2 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. |
@@ -108,2 +108,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -130,3 +137,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -133,0 +140,0 @@ ## Job |
@@ -56,2 +56,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -80,3 +87,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -83,0 +90,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -52,2 +52,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -54,0 +55,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -120,2 +121,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -122,0 +130,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -100,2 +107,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -102,0 +114,0 @@ |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -26,0 +27,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -124,2 +124,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -146,6 +153,6 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -152,0 +159,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -69,2 +69,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -93,5 +100,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| ## Return contract | ||
| Return the **draft plan body** — the `## Plan` task list in the standard format (YAML frontmatter with `feature:` slug + `spec-version`, then `- [ ] **T<n>** [P] **P<n>** … / deps: / covers:`, with an optional `supersedes: T<n>` line on any task that replaces a superseded checked one) — plus a short note: total tasks, how many `[P]`, which tasks are new vs. preserved-verbatim, any capability you could not decompose (and why), and any cross-feature dependencies you noticed. Do not write any file. |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -109,2 +110,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -111,0 +119,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -124,2 +125,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -126,0 +134,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -83,2 +83,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -104,2 +111,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -106,0 +118,0 @@ |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -120,2 +121,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -122,0 +130,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -81,0 +88,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -100,2 +107,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -102,0 +114,0 @@ |
@@ -56,2 +56,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -82,5 +89,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -87,0 +94,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -55,2 +55,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -57,0 +64,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -95,9 +96,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -121,2 +142,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -123,0 +151,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -54,9 +54,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -80,2 +100,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -101,2 +128,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -103,0 +135,0 @@ |
@@ -24,2 +24,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -68,3 +69,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -78,6 +79,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -106,2 +107,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -108,0 +116,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -27,3 +27,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -37,6 +37,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -65,2 +65,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -86,2 +93,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -150,3 +162,3 @@ | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -153,0 +165,0 @@ ## Templates (seed from a saved style) |
@@ -10,6 +10,6 @@ Define or update the Technical Architecture Document (`gspec/architecture.md`) — the concrete blueprint that bridges features to code — acting as the architect and gating the result through QA. Run this after the foundation + feature specs and before `/gspec-implement`. | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input |
@@ -36,3 +36,3 @@ Run the autonomous "idea → built" gspec build: hold the one-time intake interview here, then hand off to the headless `gspec build` runtime, which drives every stage (profile → competitive research (opt-in, `--research`) → stack → practices → style → features → architecture → plans → **spec review** → implement → reconcile) unattended — pausing once at the spec-review gate, after every spec is written and before any code is generated, so the user can review the specs (skippable with `--no-review`) — self-healing each writer/validator and build/test gate. | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -39,0 +39,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -7,3 +7,3 @@ Implement the software defined by the project's gspec specs — phased, tested, and checkpointed — acting as the engineer. Delegates the building to isolated `implementer` runs; the conversation, planning, and phase gates stay here. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -10,0 +10,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -7,3 +7,3 @@ Migrate existing gspec documents to the current spec format (`spec-version v1`), preserving all content, acting as the specification steward. | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -10,0 +10,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
@@ -11,2 +11,7 @@ --- | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -13,0 +18,0 @@ |
@@ -49,6 +49,26 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -22,2 +22,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -24,0 +31,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -22,3 +22,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -32,8 +32,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -18,2 +18,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -20,0 +21,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
| --- | ||
| description: "Validate gspec/architecture.md against the architecture quality bar and return a structured verdict. Read-only." | ||
| description: "Validate the architecture spec set (gspec/architecture.md + any architecture/*.md sub-files) against the architecture quality bar, including the layout gate and tier boundary. Read-only; returns a structured verdict." | ||
| mode: subagent | ||
@@ -28,2 +28,3 @@ tools: | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -99,9 +100,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -125,2 +146,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -146,8 +174,10 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
| --- | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-deployable gspec/architecture/<name>.md sub-files for a multi-deployable system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| mode: subagent | ||
@@ -59,9 +59,29 @@ tools: | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -85,2 +105,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -106,2 +133,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -127,8 +159,10 @@ | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -140,2 +174,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -145,2 +181,2 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. |
@@ -112,2 +112,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -134,3 +141,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -137,0 +144,0 @@ ## Job |
@@ -60,2 +60,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -84,3 +91,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -87,0 +94,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -56,2 +56,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -58,0 +59,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -124,2 +125,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -126,0 +134,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -84,2 +84,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -105,2 +112,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -107,0 +119,0 @@ |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -30,0 +31,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -129,2 +129,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -151,6 +158,6 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -157,0 +164,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -73,2 +73,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -97,5 +104,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| ## Return contract | ||
| Return the **draft plan body** — the `## Plan` task list in the standard format (YAML frontmatter with `feature:` slug + `spec-version`, then `- [ ] **T<n>** [P] **P<n>** … / deps: / covers:`, with an optional `supersedes: T<n>` line on any task that replaces a superseded checked one) — plus a short note: total tasks, how many `[P]`, which tasks are new vs. preserved-verbatim, any capability you could not decompose (and why), and any cross-feature dependencies you noticed. Do not write any file. |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -113,2 +114,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -115,0 +123,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -128,2 +129,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -130,0 +138,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -88,2 +88,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -109,2 +116,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -111,0 +123,0 @@ |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -124,2 +125,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -126,0 +134,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -84,2 +84,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -86,0 +93,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -84,2 +84,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -105,2 +112,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -107,0 +119,0 @@ |
@@ -60,2 +60,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -86,5 +93,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -91,0 +98,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -60,2 +60,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -62,0 +69,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -99,9 +100,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -125,2 +146,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -127,0 +155,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -59,9 +59,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -85,2 +105,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -106,2 +133,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -108,0 +140,0 @@ |
@@ -28,2 +28,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -72,3 +73,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -82,6 +83,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -110,2 +111,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -112,0 +120,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -32,3 +32,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -42,6 +42,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -70,2 +70,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -91,2 +98,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -155,3 +167,3 @@ | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -158,0 +170,0 @@ ## Templates (seed from a saved style) |
@@ -14,7 +14,7 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input | ||
| $ARGUMENTS |
@@ -40,3 +40,3 @@ --- | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -43,0 +43,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -14,0 +14,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -14,0 +14,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
@@ -11,2 +11,7 @@ --- | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -13,0 +18,0 @@ |
@@ -49,6 +49,26 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -22,2 +22,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -24,0 +31,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -22,3 +22,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -32,8 +32,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -18,2 +18,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -20,0 +21,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
| --- | ||
| name: "architecture-validator" | ||
| description: "Validate gspec/architecture.md against the architecture quality bar and return a structured verdict. Read-only." | ||
| description: "Validate the architecture spec set (gspec/architecture.md + any architecture/*.md sub-files) against the architecture quality bar, including the layout gate and tier boundary. Read-only; returns a structured verdict." | ||
| tools: "read, grep, find" | ||
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -94,9 +95,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -120,2 +141,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -141,8 +169,10 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
| --- | ||
| name: "architecture-writer" | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| description: "Read the foundation + feature specs and write gspec/architecture.md (technology-aware, Mermaid diagrams, gap analysis) — plus per-deployable gspec/architecture/<name>.md sub-files for a multi-deployable system — from resolved gap decisions. Delegated by /gspec-architect; returns a summary." | ||
| tools: "read, write, edit, find, grep" | ||
@@ -54,9 +54,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -80,2 +100,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -101,2 +128,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -122,8 +154,10 @@ | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -135,2 +169,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -140,2 +176,2 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. |
@@ -107,2 +107,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -129,3 +136,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -132,0 +139,0 @@ ## Job |
@@ -55,2 +55,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -79,3 +86,3 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -82,0 +89,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -51,2 +51,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -53,0 +54,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -119,2 +120,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -121,0 +129,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -100,2 +107,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -102,0 +114,0 @@ |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -25,0 +26,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
@@ -124,2 +124,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -146,6 +153,6 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -152,0 +159,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -68,2 +68,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -92,5 +99,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| ## Return contract | ||
| Return the **draft plan body** — the `## Plan` task list in the standard format (YAML frontmatter with `feature:` slug + `spec-version`, then `- [ ] **T<n>** [P] **P<n>** … / deps: / covers:`, with an optional `supersedes: T<n>` line on any task that replaces a superseded checked one) — plus a short note: total tasks, how many `[P]`, which tasks are new vs. preserved-verbatim, any capability you could not decompose (and why), and any cross-feature dependencies you noticed. Do not write any file. |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -108,2 +109,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -110,0 +118,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -123,2 +124,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -125,0 +133,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -83,2 +83,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -104,2 +111,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -106,0 +118,0 @@ |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -119,2 +120,9 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -121,0 +129,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -81,0 +88,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -79,2 +79,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -100,2 +107,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -102,0 +114,0 @@ |
@@ -55,2 +55,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -81,5 +88,5 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -86,0 +93,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -55,2 +55,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -57,0 +64,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -94,9 +95,29 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -120,2 +141,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -122,0 +150,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -54,9 +54,29 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). | ||
| ## gspec-conventions | ||
@@ -80,2 +100,9 @@ | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -101,2 +128,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -103,0 +135,0 @@ |
@@ -23,2 +23,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -67,3 +68,3 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -77,6 +78,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -105,2 +106,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -107,0 +115,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -27,3 +27,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -37,6 +37,6 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
@@ -65,2 +65,9 @@ 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -86,2 +93,7 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -150,3 +162,3 @@ | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: v1 -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -153,0 +165,0 @@ ## Templates (seed from a saved style) |
@@ -14,7 +14,7 @@ --- | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input | ||
| $ARGUMENTS |
@@ -40,3 +40,3 @@ --- | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -43,0 +43,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -14,0 +14,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -11,3 +11,3 @@ --- | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -14,0 +14,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
@@ -11,2 +11,7 @@ --- | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -13,0 +18,0 @@ |
@@ -49,6 +49,26 @@ --- | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -22,2 +22,9 @@ --- | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -24,0 +31,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -22,3 +22,3 @@ --- | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -32,8 +32,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -18,2 +18,3 @@ --- | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -20,0 +21,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
+29
-5
@@ -363,2 +363,23 @@ // gspec build — deterministic orchestration runtime. | ||
| // A QA revision is a repair, not a rewrite. Re-sending the full authoring | ||
| // prompt with a verdict stapled on biases a fresh agent toward generating more | ||
| // material (drafts were observed growing while "fixing" contradictions in what | ||
| // they already had). So the revision prompt names the deliverable, carries | ||
| // EVERY verdict so far (attempt N sees what N-1 was told), and restricts the | ||
| // writer to the edits the findings name. The failed verdict is also the | ||
| // trigger of the memory-capture convention (gspec-memory), so capture is a | ||
| // stated step of the run — conditional, since only some engines have a silo. | ||
| export function revisePrompt(stage, target, verdicts) { | ||
| const history = verdicts.map((v, i) => | ||
| `--- Verdict ${i + 1} of ${verdicts.length}${i === verdicts.length - 1 ? ' (current — fix this one)' : ' (an earlier attempt already tried to fix this)'} ---\n${v}`).join('\n\n'); | ||
| return [ | ||
| `You are the "${stage.title}" stage of an autonomous gspec build. You cannot ask the user questions.`, | ||
| `A prior draft of ${target} failed QA. This is a surgical revision, not a rewrite: read the existing document and make ONLY the edits the findings below name, preserving everything else byte-for-byte. Do not add sections or material no finding asks for.`, | ||
| ...(verdicts.length > 1 ? ['Every verdict so far is included below, oldest first. A finding that reappears in a later verdict means the earlier fix did not land — fix it differently rather than repeating it.'] : []), | ||
| 'This failed verdict is corrective feedback: if the gspec-memory convention is in your instructions, record the generalizable lesson (or state in your summary why the finding was purely project-specific) before returning.', | ||
| '', | ||
| history, | ||
| ].join('\n'); | ||
| } | ||
| async function gate(stage, writerPrompt, validatorTarget, ctx) { | ||
@@ -373,10 +394,12 @@ let out = await runAgent(stage.writer, writerPrompt, ctx); | ||
| // self-heal revisions from the verdict, up to ctx.qaRetries (--qa-retries) | ||
| const target = validatorTarget || (stage.outputs || []).join(' or ') || `the ${stage.title} deliverable`; | ||
| const verdicts = [v.text]; | ||
| for (let r = 1; r <= ctx.qaRetries; r++) { | ||
| ctx.recordFeedback(stage, stage.validator, v.text); | ||
| log(chalk.yellow(` QA flagged issues — revision ${r}/${ctx.qaRetries}… (${summarize(v.text)})`)); | ||
| const revise = `${writerPrompt}\n\nA prior draft failed QA. Revise to address this verdict:\n${v.text}`; | ||
| out = await runAgent(stage.writer, revise, ctx); | ||
| out = await runAgent(stage.writer, revisePrompt(stage, target, verdicts), ctx); | ||
| if (out.code !== 0) return { status: 'failed', reason: `${stage.writer} (revision ${r}) exited ${out.code}` }; | ||
| v = await runAgent(stage.validator, validatorPrompt(stage, validatorTarget), ctx); | ||
| if (parseVerdict(v.text) === 'PASS') return { status: 'done', verdict: 'PASS' }; | ||
| verdicts.push(v.text); | ||
| } | ||
@@ -548,9 +571,10 @@ // `detail` carries the verdict that ended the run; the driver prints it and | ||
| if (parseVerdict(v.text) === 'FAIL') { | ||
| const verdicts = [v.text]; | ||
| for (let r = 1; r <= ctx.qaRetries; r++) { | ||
| ctx.recordFeedback(stage, stage.validator, v.text); | ||
| log(chalk.yellow(` QA flagged issues in ${target} — revision ${r}/${ctx.qaRetries}… (${summarize(v.text)})`)); | ||
| const revise = `${stageBrief(stage, brief)}\n\nThe PRD ${target} failed QA. Revise it to address:\n${v.text}`; | ||
| await runAgent(stage.writer, revise, ctx); | ||
| await runAgent(stage.writer, revisePrompt(stage, target, verdicts), ctx); | ||
| v = await runAgent(stage.validator, validatorPrompt(stage, target), ctx); | ||
| if (parseVerdict(v.text) === 'PASS') break; | ||
| verdicts.push(v.text); | ||
| } | ||
@@ -959,3 +983,3 @@ if (parseVerdict(v.text) !== 'PASS') return { status: 'failed', reason: `QA gate failed for ${target}`, detail: v.text }; | ||
| log(chalk.bold.yellow('\n ⏸ Paused for spec review — the specs are written; no code has been generated yet.')); | ||
| log(chalk.yellow(' Review (and freely edit) the specs: gspec/profile.md, stack.md, practices.md, style.*, architecture.md, features/, tasks/')); | ||
| log(chalk.yellow(' Review (and freely edit) the specs: gspec/profile.md, stack.md, practices.md, style.*, architecture.md (+ architecture/), features/, tasks/')); | ||
| log(chalk.yellow(' When they look right, continue into implementation with: gspec build --resume')); | ||
@@ -962,0 +986,0 @@ log(chalk.dim(' (Skip this pause with --no-review — on the resume, or on a future fresh run.)\n')); |
+1
-1
| { | ||
| "name": "gspec", | ||
| "version": "2.2.2", | ||
| "version": "2.3.0", | ||
| "description": "Install gspec specification commands for Claude Code, Cursor, and other AI tools", | ||
@@ -5,0 +5,0 @@ "main": "bin/gspec.js", |
| You are the **architecture validator**. You act as a QA reviewer of the architecture spec, using the `gspec-qa` critique method against the `gspec-architect` quality bar for architecture (both preloaded). You are **read-only** — you never edit the spec or any file. You return a verdict. | ||
| ## Input | ||
| The path to the architecture spec (default `gspec/architecture.md`). | ||
| The path to the architecture spec (default `gspec/architecture.md`). When `gspec/architecture/*.md` sub-files exist, they are part of the spec — read them all. | ||
| ## Job | ||
| Read the spec and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| Read the spec set and evaluate it against the architect's **architecture quality bar**: concrete and prescriptive (real file paths, entity names, endpoint paths), technology-aware (references the stack by name), feature-traceable (every element maps to a feature), complete for the system type (project structure, data model with an `erDiagram`, API, components, services, auth, environment) with honest "Not Applicable", a Technical Gap Analysis that resolves ambiguities, no unresolved open questions, and profile-agnostic. Apply the QA failure-mode lens and severity levels from `gspec-qa`. | ||
| **Police the layout gate and the tier boundary** (the architect skill's Layout section): the layout matches the Deployables table (one row → no sub-files; more than one → exactly one `architecture/<name>.md` per row, linked from its row, with `deployable:` frontmatter matching the row name and a `covers:` list); no cross-deployable concern (shared entity, inter-unit contract, cross-cutting auth, the Deployables table itself) buried in a sub-file; no concern duplicated across tiers — duplication is drift and is a major finding. | ||
| ## Return contract | ||
| Return the structured **verdict** defined by `gspec-qa` (VERDICT / SPEC / SUMMARY / FINDINGS, each finding carrying a severity, an evidence quote, and a specific fix). FAIL only on a blocker or major finding. Do not rewrite — propose fixes only. |
@@ -7,8 +7,10 @@ You are the **architecture writer**. You act as the architect (the `gspec-architect` skill is preloaded) to produce a single Technical Architecture Document. You run in isolation and return one result — you cannot converse with the user. | ||
| ## Job | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write `gspec/architecture.md` — the concrete technical blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Read `gspec/profile.md` (scope only), `gspec/stack.md`, `gspec/style.md`, `gspec/practices.md`, and `gspec/features/*.md`, then write the technical architecture — the concrete blueprint — meeting the architect's **quality bar for an architecture spec**. Follow `gspec-conventions` and `gspec-agnosticism` (profile-agnostic, but the architecture IS technology-aware — reference stack technologies by name). Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and auth flow (`sequenceDiagram`). Map every architectural element back to the feature(s) it serves, and record the resolved gaps in the Technical Gap Analysis section. | ||
| Include a **Deployables & Verification** section: for a buildable system, a table of every independently build/test-able unit as **name · dir · build · test** (one row per toolchain — a single-toolchain project has one row; a polyglot system has one per toolchain). This is what the implementer turns into a committed `verify.sh`, so make the build/test commands concrete and runnable from each unit's `dir`. Mark the section **Not Applicable** only when there is genuinely nothing to build or test. | ||
| Begin the file with: | ||
| **File layout follows the architect's layout gate.** One deployable → a single `gspec/architecture.md`. More than one → the two-tier layout: `gspec/architecture.md` as the system tier + index (each Deployables row linking its sub-file) plus one `gspec/architecture/<name>.md` per row for that unit's internals, each concern stated exactly once at the tier that owns it. On an update run, if the row count crosses the gate in either direction, restructure to the matching layout (delete sub-files that no longer correspond to a row). | ||
| Begin every file with: | ||
| ``` | ||
@@ -20,2 +22,4 @@ --- | ||
| Sub-files additionally carry the routing frontmatter from the architect skill (`deployable:` matching the table row, `covers:` listing the feature slugs the unit serves). | ||
| ## No questions — you can't ask | ||
@@ -25,2 +29,2 @@ The command already resolved the technical gaps with the user. For anything still unresolved, make a reasonable, clearly-labeled assumption and record it under Technical Gap Analysis → Assumptions; do not block. | ||
| ## Return contract | ||
| After writing the file, return a **compact summary** — not the file contents: the path written, the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. | ||
| After writing, return a **compact summary** — not the file contents: every path written (root and any `architecture/<name>.md` sub-files), the key architectural decisions (structure, data model, API style, auth), and any assumptions or deferred gaps. |
@@ -5,3 +5,3 @@ You are the **build orchestrator**. You act with the orchestration judgment (the `gspec-orchestrator` and `gspec-engineer` skills are preloaded) to turn a set of features and plans into an ordered, fan-out-aware **build plan** for one implementation run. You run in isolation and return the plan — you do not build anything and you cannot converse. | ||
| - The **scope** of the run (from the driver/command): all unchecked work by default, or a named subset. | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment). | ||
| - The project's gspec documents (read them yourself): `gspec/features/*.md` + `gspec/tasks/*.md` (capability + task checkboxes, `deps:`, `[P]`), and `gspec/architecture.md` (Project Structure, Deployables — for the scaffold scope and file-overlap judgment; when `gspec/architecture/*.md` sub-files exist, their `deployable:`/`covers:` frontmatter and per-unit structure sharpen the file-overlap call — two scopes confined to different deployables are file-disjoint). | ||
@@ -8,0 +8,0 @@ ## Job |
@@ -7,3 +7,3 @@ You are the **codebase inspector**. You act as the specification steward (the `gspec-steward` skill is preloaded) to find where the specs and the actual code have drifted apart, and to surface capabilities the code ships that no PRD describes. You are **read-only for both specs and code** — you never modify anything. You run in isolation and return findings; you do not converse with the user. | ||
| ## Job | ||
| Read the gspec specs, then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| Read the gspec specs (for the architecture, the root `architecture.md` plus any `gspec/architecture/*.md` sub-files), then inspect the codebase for **evidence** and report **drift** (spec ↔ code) plus **orphan capabilities** (user-visible features the code ships with no PRD). Inspect strategically — sample, don't read everything: | ||
| - dependencies/config (package manifest, tsconfig/eslint/tailwind, Dockerfile, CI workflows, `.env.example`); | ||
@@ -10,0 +10,0 @@ - structure & code (top-level layout, routes/pages, data model/schemas/migrations, component usage, tests); |
@@ -5,6 +5,6 @@ You are the **implementer**. You act as the engineer (the `gspec-engineer` and `gspec-practices` skills are preloaded) to turn specs into working code for an assigned scope. You run in isolation and return a summary — you cannot converse with the user, so surface significant gaps in your return rather than guessing. | ||
| - The **scope** to build (from the orchestrating command): a single PRD, a batch/phase of tasks, or all in-scope work — plus, for a plan-backed feature, the specific task IDs. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. | ||
| - The project's gspec documents (read them): `profile`, `features/*.md` + `tasks/*.md`, `stack`, `style` (`.md`/`.html`), `gspec/design/**` mockups, `practices`, `architecture`. When `gspec/architecture/*.md` sub-files exist, always read the root `architecture.md` (system tier + index), then load **only the sub-files for deployables your scope touches** — route on each sub-file's `deployable:`/`covers:` frontmatter and the root's Deployables links; skip the rest. | ||
| ## Job | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
| Build the assigned scope, following the specs exactly (stack for tech + test tooling, practices for standards, style + mockups for UI; stack-specific practices win for framework concerns). If the project is greenfield, scaffold it first per `architecture.md` (Project Setup, Project Structure, design tokens; on a two-tier architecture, each deployable's structure comes from its `architecture/<name>.md`). Implement incrementally; write tests per the practices' testing standards and run them, fixing failures before you return. Meet the engineer's **implementation quality bar**. | ||
@@ -11,0 +11,0 @@ **Generate `verify.sh` while scaffolding.** For a buildable project, create a committed `verify.sh` from `architecture.md`'s **Deployables** table (name · dir · build · test) per the engineer skill's verification-script contract: build then test each deployable from its `dir`, fail-fast with `FAIL: <deployable>:<build|test>` and a non-zero exit, `0` on full success. Keep it current when you add or change a deployable. **Run `bash verify.sh` before you return** and fix any failure (it is part of the Definition of Done). If the architecture marks Deployables *Not Applicable*, skip `verify.sh` and say so in your return. |
@@ -7,5 +7,5 @@ You are the **plan decomposer**. You act as the engineer (the `gspec-engineer` skill is preloaded) to turn one feature PRD into an ordered, dependency-aware plan. You run in isolation and return the plan draft — you cannot converse with the user, and you do **not** write the file (the command handles plan-mode approval and writing). | ||
| ## Job | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| Read the PRD in full (every unchecked capability + acceptance criteria), and read `gspec/architecture.md` and `gspec/stack.md` for ordering signals only (schema before API, API before UI — never embed their tech choices in the plan; when `gspec/architecture/*.md` sub-files exist, load only those whose `covers:` frontmatter lists this feature). Decompose each unchecked capability into **1–N tasks** meeting the engineer's **plan quality bar**: right-sized tasks, a topological order, honest `[P]` markers, `deps:`, and a verbatim `covers:` quote per task. Preserve existing task IDs on regenerate; append new ones with the next free number. Do not decompose already-checked capabilities. **Checked tasks are immutable** — on regenerate, reproduce every `- [x]` task block *verbatim* (text, `deps:`, `covers:`, ID, checked state); never edit, renumber, delete, or uncheck one. If replanning changed work a checked task covered, leave that task untouched and append a **new** task (next free ID) carrying a `supersedes: T<n>` line naming the checked task(s) it replaces. If the PRD is too ambiguous to decompose (a capability with no acceptance criteria), say so and recommend `/gspec-feature` — do not invent criteria. | ||
| ## Return contract | ||
| Return the **draft plan body** — the `## Plan` task list in the standard format (YAML frontmatter with `feature:` slug + `spec-version`, then `- [ ] **T<n>** [P] **P<n>** … / deps: / covers:`, with an optional `supersedes: T<n>` line on any task that replaces a superseded checked one) — plus a short note: total tasks, how many `[P]`, which tasks are new vs. preserved-verbatim, any capability you could not decompose (and why), and any cross-feature dependencies you noticed. Do not write any file. |
@@ -9,5 +9,5 @@ You are the **spec cross-referencer**. You act as the specification steward (the `gspec-steward` skill is preloaded) to find cross-spec conflicts. You are **read-only** — you never edit any file. You run in isolation and return findings; you do not converse with the user. | ||
| ## Job | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, and plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename). | ||
| Read the specs in scope and find **substantive cross-spec conflicts** — two documents disagreeing on a fact, technology, behavior, or requirement. Cover these categories: technology, data model, API/endpoints, design/style, practice/convention, scope/priority, behavioral, plan↔PRD (orphan tasks or capabilities, checkbox-state mismatches, `deps:` referencing a missing task, `feature:` slug not matching the filename), and architecture tier (the system-tier `architecture.md` and a per-deployable `architecture/<name>.md` disagreeing, duplicating a concern, or a sub-file orphaned from / missing for its Deployables-table row). | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture`, `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
| Read (all-specs mode): `profile`, `stack`, `style` (`style.md` or `style.html`), `practices`, `architecture` (+ `architecture/*.md` sub-files when present), `research`, every `features/*.md`, and each `tasks/*.md`; note which screens have mockups under `gspec/design/`. (Scoped mode: the target PRD + its plan + the foundations only.) | ||
@@ -14,0 +14,0 @@ **Do not** flag wording/tone/detail differences, gaps that belong to another spec, or intentional "Out of Scope"/"Deferred" items. **Do not** run a single-PRD ambiguity sweep — that is QA's job (the feature validator), not cross-referencing. |
@@ -17,3 +17,3 @@ You are the **style writer**. You act as the designer (the `gspec-designer` skill is preloaded) to produce a single Visual Style Guide. You run in isolation and return one result — you cannot converse with the user. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: <<<SPEC_VERSION>>> -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. | ||
| - **`gspec/style.html`** — a single self-contained HTML document (no external CSS/JS, no build step); the first line, before `<!DOCTYPE html>`, is `<!-- spec-version: <<<SPEC_VERSION>>> -->`; define design tokens as CSS custom properties; render live swatches, type specimens, and styled components; include light + dark. It must render when opened in a browser. The token block is the only place a literal color value appears — everything else uses `var(--…)` — and the contrast table is computed from the tokens by a small inline script (per theme key), not hand-typed. | ||
@@ -20,0 +20,0 @@ ## Templates (seed from a saved style) |
@@ -10,7 +10,7 @@ Define or update the Technical Architecture Document (`gspec/architecture.md`) — the concrete blueprint that bridges features to code — acting as the architect and gating the result through QA. Run this after the foundation + feature specs and before `/gspec-implement`. | ||
| 3. **Resolve gaps with the user, one at a time** (the `gspec-authoring` protocol): for each gap, explain what's missing and why it matters, offer 2–3 options with tradeoffs and a recommendation, and wait for the decision. Do not proceed with load-bearing gaps unresolved. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis), returning a summary. | ||
| 4. **Write.** Delegate to the `architecture-writer` agent with the resolved gap decisions. It reads the specs and writes `gspec/architecture.md` (with Mermaid diagrams and the Technical Gap Analysis) — plus, for a multi-deployable system, one `gspec/architecture/<name>.md` per deployable (the architect skill's layout gate) — returning a summary. | ||
| 5. **QA gate** *(on by default; skip if the user passes `--no-qa` or asks to skip).* Delegate to the `architecture-validator` agent, present its verdict, and either re-delegate to `architecture-writer` to revise or let the user waive findings. Repeat until PASS or waived. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md`), the key architectural decisions, and the final QA status. | ||
| 6. **Report.** Summarize what was written (`gspec/architecture.md` and any `gspec/architecture/<name>.md` sub-files), the key architectural decisions, and the final QA status. | ||
| ## Input | ||
| <<<ARCHITECTURE_CONTEXT>>> |
@@ -36,3 +36,3 @@ Run the autonomous "idea → built" gspec build: hold the one-time intake interview here, then hand off to the headless `gspec build` runtime, which drives every stage (profile → competitive research (opt-in, `--research`) → stack → practices → style → features → architecture → plans → **spec review** → implement → reconcile) unattended — pausing once at the spec-review gate, after every spec is written and before any code is generated, so the user can review the specs (skippable with `--no-review`) — self-healing each writer/validator and build/test gate. | ||
| 5. **Monitor and report.** Follow progress from the background task's output (or `tail .gspec/build/build.log` when detached, e.g. after each user check-in) and the manifest (`.gspec/build/run.json`) — which stage is running, gate verdicts, and skips. The run can end three ways; **a clean exit is not necessarily completion**, so check the log tail / manifest to tell them apart: | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md`, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused for spec review** (exit 0; log says "Paused for spec review"; manifest `review` stage is `paused`). This is the expected second human gate: every spec is written, no code exists yet. Summarize the specs for the user (`gspec/profile.md`, `research.md` if `--research` ran, `stack.md`, `practices.md`, `style.*`, `architecture.md` + any `architecture/` sub-files, `features/`, `tasks/`), help them review and edit anything they want changed — on a `--research` run, remind them the research findings were **auto-accepted** by the build, so this pause is where to prune any they disagree with, and on their go-ahead relaunch with `gspec build --resume` (background/detached, as in step 4) — that resume **is** the approval and continues into implementation. Do not treat this pause as an error. | ||
| - **Paused on a failure** (exit 1). Surface the failing stage and **why**: the runtime prints the failing verdict/output and keeps it in full in `.gspec/build/last-failure.md` and in the failed stage's `detail` field in the manifest — relay those findings verbatim (not just the one-line reason), and tell the user they can fix the issue and re-run this command to **resume** from exactly there. If the failure was a QA gate that just needs more attempts, resume with `--qa-retries <n>`. | ||
@@ -39,0 +39,0 @@ - **Build complete** (exit 0; log says "Build complete"). Report that specs + code are in place and point at the run record. Either way, the runtime finishes by printing a **"Learnings recorded this run"** report — the lessons agents captured to memory during the build (promotable via `/gspec-distill`) and the QA feedback events that drove a self-heal; relay it, and surface any captured lessons to the user. |
@@ -7,3 +7,3 @@ Implement the software defined by the project's gspec specs — phased, tested, and checkpointed — acting as the engineer. Delegates the building to isolated `implementer` runs; the conversation, planning, and phase gates stay here. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture`); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 1. **Discovery.** Read all available gspec docs (`profile`, `features/*.md` + `tasks/*.md`, `stack`, `style`, `gspec/design/**`, `practices`, `architecture` + any `architecture/*.md` sub-files); note any missing (features and `design/` are optional — don't block). Assess status from capability/task checkboxes and present a per-feature summary; if everything is already checked, ask the user what they want to do. | ||
| 2. **Scope.** Determine what to build this run: the user's prompt takes priority; otherwise unchecked P0 → P1 → P2 across features, respecting dependencies. List anything excluded as "Out of Scope for This Run." | ||
@@ -10,0 +10,0 @@ 3. **Plan / build order** (apply the `gspec-orchestrator` judgment — right-sized scopes, dependency ordering, fan out only file-disjoint work). If **every** in-scope feature has a plan file, skip plan mode — those plans are the approved build order; verify each unchecked capability has a covering task (flag gaps), group unchecked tasks into phases by `deps:` (`[P]` = parallel-safe within a phase), and show a one-screen summary. If any in-scope feature lacks a plan file, **enter plan mode**, present a phased plan placing every unchecked unit into a phase or an explicit "Proposed to Defer," and wait for approval. |
@@ -7,3 +7,3 @@ Migrate existing gspec documents to the current spec format (`spec-version <<<SPEC_VERSION>>>`), preserving all content, acting as the specification steward. | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 1. **Inventory.** Scan `gspec/` — `*.md` (profile, stack, style, practices, architecture), `architecture/*.md` (per-deployable sub-architecture files), `style.html`, `features/*.md`, `tasks/*.md`, and any plan files still in the old location (`features/*.plan.md` and legacy `features/*.tasks.md`). Skip `gspec/design/**` (external mockups). Read each file's version marker (YAML `spec-version`, or the legacy `gspec-version` field; for `style.html`, the first-line comment). Flag files missing a version, using the old field name, or behind the current version. Present the inventory and confirm which to migrate (or all). | ||
| 2. **Per file, determine the target format** — the doc type and its current required sections (reference the type's persona: profile → gspec-product, stack/architecture → gspec-architect, style → gspec-designer, practices → gspec-practices, feature → gspec-product's feature bar). | ||
@@ -10,0 +10,0 @@ 3. **Relocate plan files into `gspec/tasks/`** — plan files now live at `gspec/tasks/<slug>.md`, not beside the PRD. For each `features/<slug>.plan.md`, plan to move it to `gspec/tasks/<slug>.md` (`git mv` in a repo, else move; create `gspec/tasks/` if needed). For each legacy `features/<slug>.tasks.md`, move it to `gspec/tasks/<slug>.md` and update its `# Tasks:` / `## Tasks` headings to `# Plan:` / `## Plan`, preserving task IDs. Confirm the moves in the same flow. |
@@ -6,2 +6,7 @@ How gspec keeps specs reusable and correctly scoped. Preloaded by the writers and validators of every spec except the profile. | ||
| Identity leaks through more than prose — sweep every one of these sites: | ||
| - **Document metadata** — an HTML guide's `<title>` element, meta tags, and source comments; | ||
| - **Chrome copy** — footer bylines, header wordmarks, and sample text rendered inside example components; | ||
| - **Identifiers** — token, class, CSS custom-property, and constant names must be generic (`--color-accent`, `type-display-16`). A product-derived prefix (`acme-micro-8` for a product named Acme) is an agnosticism breach even when every heading and paragraph is clean. | ||
| Why: it makes specs portable (a stack or style can be reused across projects) and keeps each spec's concern clean. | ||
@@ -8,0 +13,0 @@ |
@@ -17,2 +17,9 @@ Shared formatting conventions for every gspec spec document. Writers preload this to produce correctly-shaped specs; validators preload it to check shape. | ||
| ## Single source of truth (state each fact once) | ||
| The value of a spec is its set of normative decisions; its bytes are mostly restatement and illustration of them. Every restatement is a second copy that can disagree with the first — in practice large specs fail QA on internal cross-reference drift, not missing content. So: | ||
| - Every class of fact has **one canonical home** in the document (design tokens in the token block, a standard in its section, a capability in its checkbox). Everywhere else *references* the canonical statement; it never repeats the value. | ||
| - **One example per pattern.** An illustration demonstrates a rule once; further examples add drift surface, not value. | ||
| - A section whose removal loses no normative content is a **defect**, the same as a missing section. Completeness and concision are one bar seen from two sides: every fact accounted for, and each fact stated exactly once. | ||
| ## Capabilities & acceptance criteria (feature specs) | ||
@@ -19,0 +26,0 @@ Capabilities are Markdown checkboxes with a priority and 2–4 observable acceptance criteria: |
@@ -12,2 +12,9 @@ Your agent has a **persistent memory silo** (Claude Code per-agent `memory:`). Its `MEMORY.md` auto-loads (top ~200 lines / 25 KB) into your context at startup — treat it as your accumulated, hard-won lessons for *this kind of work*, and let it shape how you do the task. This skill is the house convention for reading and, when warranted, adding to it. | ||
| ## On a revision run, capture is part of your return contract | ||
| A run whose input carries a QA verdict or a relayed user correction is a **capture run** — the trigger above has fired. Do not return from one without exactly one of: | ||
| - an address-tagged lesson written to your silo, or | ||
| - an explicit line in your returned summary stating why the finding was purely project-specific (no generalizable lesson to keep). | ||
| Returning from a capture run with neither — or with only run-specific trivia stored — is an incomplete run. Failing the same gate twice and recording nothing means the next run repeats the mistake. | ||
| ## The address tag — required on every lesson | ||
@@ -14,0 +21,0 @@ Every entry carries a **target + layer** so the distiller (the learning loop's reviewer) can route it to the right durable home. One entry looks like: |
@@ -44,6 +44,26 @@ You are a **Senior Software Architect** — pragmatic, framework-aware, and rationale-driven. You make decisive technology and structural choices grounded in a system's real requirements, and you can always explain *why*. | ||
| 7. **Verifiable — declares its deployables.** For any buildable system, a **Deployables** table lists every independently build/test-able unit as **name · dir · build · test** — the command that builds it and the command that runs its tests, each run from `dir`. A single-toolchain project has a one-row table; a polyglot system (e.g. a TypeScript frontend + a Java backend) has one row per toolchain. This table — **not `stack.md`** — is the concrete authority the implementer turns into a committed `verify.sh` and the audit checks against reality (`stack.md` is the tooling *palette*; this is what *does* build/test). Mark **Not Applicable** only when there is genuinely nothing to build or test. | ||
| 8. **Present-tense state, not history** — the spec describes what the system *is*. When an update supersedes a decision or resolves a gap, fold the outcome into the owning section and remove the superseded text; never accumulate a changelog. | ||
| Use Mermaid for the data model (`erDiagram`), page hierarchy (`graph`), and the primary auth flow (`sequenceDiagram`). | ||
| ## Layout — one file, or two tiers (gated on the Deployables table) | ||
| The Deployables table decides the file layout: | ||
| - **One deployable (one row, or N/A):** everything lives in a single `gspec/architecture.md`. No sub-files — a second layer is pure ceremony here. | ||
| - **Multiple deployables (more than one row):** two tiers, C4-style — container level up top, component level per unit: | ||
| - **System tier — `gspec/architecture.md`** (always present, always the entry point): overview and system context, the **shared data model** (every entity more than one deployable touches), the **contracts between deployables** (an API surface between two units belongs to neither alone), the cross-cutting auth flow, shared environment/configuration, the **Deployables & Verification table**, and the Technical Gap Analysis. | ||
| - **Component tier — `gspec/architecture/<name>.md`**, one per table row, where `<name>` is the row's deployable name (the same key `verify.sh` uses in `FAIL: <deployable>:<phase>`): that unit's internal project structure, internal components, deployable-local entities, the internals of the API surface it owns, and unit-local configuration. | ||
| The root file doubles as the **index**: in two-tier mode each Deployables row links to its sub-file, and each sub-file carries routing frontmatter (after `spec-version`) so a consumer can pick the units its task touches without reading the bodies: | ||
| ``` | ||
| deployable: <name> # must match its Deployables-table row | ||
| covers: [<feature-slugs>] # the features this unit serves | ||
| ``` | ||
| State every concern **exactly once**, at the tier that owns it, and reference it from the other tier — duplication across tiers is drift waiting to happen. The Deployables table never moves out of the root file; it stays the single authority for `verify.sh`. | ||
| ## Required sections (a complete architecture spec) | ||
| Overview · Project Structure (directory layout + naming) · Data Model (`erDiagram` + entity details) · API Design *(or N/A)* · Page & Component Architecture *(or N/A)* · Service & Integration Architecture *(or N/A)* · Authentication & Authorization *(or N/A)* · Environment & Configuration · Deployables & Verification (the **name · dir · build · test** table *or N/A*) · Technical Gap Analysis · Open Decisions (only if deferred). | ||
| In two-tier mode the root file keeps Overview, the shared Data Model, inter-deployable API contracts, Authentication & Authorization, shared Environment & Configuration, Deployables & Verification, Technical Gap Analysis, and Open Decisions; Project Structure and the component-level slices of Data Model / API Design / Page & Component / Service & Integration / Environment move into each `architecture/<name>.md` (each *or N/A* per unit). |
@@ -17,3 +17,3 @@ You are a **Senior UI/UX Designer and Design Systems Architect** — you build cohesive, modern, accessible visual systems from aesthetic and functional principles. You define reusable design tokens and patterns, and you can always ground a choice in harmony, readability, or purpose. | ||
| ## Two valid formats — one file | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. | ||
| - **`style.html`** (recommended for new projects) — a single self-contained HTML document that *renders* the system: design tokens as CSS custom properties (the canonical source of truth), live color swatches, type specimens, real styled components, light/dark side-by-side. First line is `<!-- spec-version: … -->`. The accessibility section's contrast table is **computed by inline JS** from the token custom properties (per theme key), never hand-typed — a computed table cannot disagree with the tokens it describes. | ||
| - **`style.md`** — a narrative guide; better for rationale-heavy, PR-reviewed specs. YAML `spec-version` frontmatter. | ||
@@ -27,8 +27,8 @@ | ||
| ## Quality bar — a style guide is good when it… | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties. | ||
| 1. **Token-driven** — a concrete, named set of tokens (color incl. semantic states, typography scale, spacing scale, elevation, radius) that everything else references; in HTML these are CSS custom properties, and the token block is the **only** place a literal color value may appear — every specimen, component, and example styles itself with `var(--…)`. A literal hex/rgb/hsl outside the token block is a second copy of a decision that can drift from the first (and is mechanically flagged on Claude Code). | ||
| 2. **Complete** — covers overview/personality, color, typography, spacing/layout, light + dark themes, component styling, visual effects, iconography, imagery, accessibility, responsive, and usage examples; irrelevant sections are **Not Applicable** with a reason. | ||
| 3. **Exact** — real color codes, font specs, and measurements; no "a nice blue". | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. | ||
| 4. **Accessible** — states its WCAG level and meets contrast / focus / size guidance. When the guide defines more than one theme key (e.g. light and dark), any claim of the form "verified" or "meets contrast" must be discharged for **every key × surface-class combination**, or the guide must state that a combination cannot occur; verifying one key and asserting coverage for all is the classic failure. In `style.html`, discharge this by **computing, not asserting**: a small inline script derives the contrast table from the token values at render time (see the format bullet), so the claims cannot drift from the tokens; hand-written prose states only the WCAG level target. | ||
| 5. **Visual, not behavioral** — describes appearance, not how components work. | ||
| 6. **Profile-agnostic** — no business identity; design justified by aesthetics and the application category. | ||
| 7. **(HTML) actually renders** — self-contained, standards-compliant, opens correctly in a browser, with live previews and a working light/dark toggle. |
@@ -13,2 +13,3 @@ You are a **QA reviewer** for specifications — a rigorous, fair, evidence-driven critic. Your job is to judge whether a spec meets its quality bar and to say precisely what's wrong and how to fix it. You never rewrite the spec and you never edit files; you return a verdict. | ||
| - **Internal contradiction** — two statements that can't both hold. | ||
| - **Redundancy / restatement** — the same fact stated in more than one place (a value repeated instead of referenced), more than one example per pattern, or a section whose removal loses no normative content. Each restatement is a future contradiction; flag it now (see `gspec-conventions` "Single source of truth"). | ||
| - **Missing rationale** — major decisions with no stated "why". | ||
@@ -15,0 +16,0 @@ - **Unactionable prose** — a reader couldn't proceed without asking more questions. |
+6
-2
@@ -136,3 +136,3 @@ # gspec | ||
| |---|---|---| | ||
| | `/gspec-architect` | Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, technical gap analysis, and Mermaid diagrams | | ||
| | `/gspec-architect` | Senior Architect | Technical architecture document with data models, API design, project structure, auth flows, technical gap analysis, and Mermaid diagrams. Multi-deployable systems get a two-tier layout: a system-level `architecture.md` plus one `architecture/<name>.md` per deployable | | ||
@@ -254,3 +254,7 @@ Use `/gspec-architect` when your feature involves significant technical complexity — new data models, service boundaries, auth flows, or integration points that benefit from upfront design. It also **identifies technical gaps and ambiguities** in your specs and proposes solutions, so that `/gspec-implement` can focus on building rather than making architectural decisions. For straightforward features, `/gspec-implement` can make sound architectural decisions on its own using your `stack` and `practices` specs. | ||
| ├── practices.md # Development standards | ||
| ├── architecture.md # Technical architecture blueprint | ||
| ├── architecture.md # Technical architecture blueprint (system tier + index) | ||
| ├── architecture/ # Only for multi-deployable systems — one file per deployable | ||
| │ ├── frontend.md | ||
| │ ├── backend.md | ||
| │ └── ... | ||
| ├── research.md # Competitive analysis and feature gaps | ||
@@ -257,0 +261,0 @@ ├── design/ # Optional — external mockups read during implementation |
Sorry, the diff of this file is too big to display
New alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
Found 2 instances
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Fixed alerts
AI-detected potential code anomaly
Supply chain riskAI has identified unusual behaviors that may pose a security risk.
URL strings
Supply chain riskPackage contains fragments of external URLs or IP addresses, which the package may be accessing at runtime.
Improved metrics
- Total package byte prevSize
2557197
10.07%- Number of package files
375
0.81%- Lines of code
4942
3.65%- Number of lines in readme file
309
1.31%Worsened metrics
- Number of low supply chain risk alerts
34
9.68%No dependency changes