Stage 3 · Temple · Build & Verify
Etapa 3 · Temple · Construye y Verifica
Build from the Mold
Construye desde el Molde
Quenching locks the shape. In GS, Temple is where code is derived from the spec and verified by the harness — you stop writing code, and you stop reading what was generated, because the harness reads it for you. Install the enforcement layer, build the first feature, then run the ongoing loop.
El temple fija la forma. En GS, el Temple es donde el código se deriva del spec y lo verifica el harness — dejas de escribir código, y dejas de leer lo que se generó, porque el harness lo lee por ti. Instala la capa de cumplimiento, construye la primera feature, luego corre el loop continuo.
Step 01 — Install the Harness
Paso 01 — Instala el Harness
Enforcement infrastructure: hooks, CI, gates
Infraestructura de cumplimiento: hooks, CI, gates
The harness is the enforcement layer. It makes the cascade rules mechanical: conventional commits are rejected at the git level, code changes without doc updates require a decision note, CI runs the full test suite on every push. Needs the sentinel to be complete first — the hooks reference the cascade rules defined in manifest.yaml.
El harness es la capa de cumplimiento. Hace que las reglas de cascada sean mecánicas: los commits que no siguen Conventional Commits son rechazados a nivel git, los cambios de código sin actualizaciones de docs requieren una nota de decisión, la CI ejecuta la suite de tests completa en cada push. Necesita que el sentinel esté completo primero — los hooks referencian las reglas de cascada definidas en manifest.yaml.
01
Paste this — Install harnessPega esto — Instala el harnessRead docs/manifest.yaml and CONSTITUTION.md.
Install the harness enforcement infrastructure.
1. .git/hooks/commit-msg — enforce Conventional Commits:
#!/usr/bin/env bash
msg=$(cat "$1")
pattern="^(feat|fix|chore|refactor|test|docs|style|ci|perf)(\(.+\))?: .{1,72}"
if ! echo "$msg" | grep -qE "$pattern"; then
echo "ERROR: Commit message must follow Conventional Commits."
echo " Format: type(scope): description"
echo " Types: feat fix chore refactor test docs style ci perf"
exit 1
fi
2. .git/hooks/pre-commit — cascade check:
#!/usr/bin/env bash
staged=$(git diff --cached --name-only)
src_changed=$(echo "$staged" | grep -E "^(src|app|lib|components|pages)/")
doc_changed=$(echo "$staged" | grep -E "^docs/")
if [ -n "$src_changed" ] && [ -z "$doc_changed" ]; then
today=$(date +%Y-%m-%d)
decision=$(ls docs/decisions/${today}-*.md 2>/dev/null | head -1)
if [ -z "$decision" ]; then
echo "⚠ Code changed without a doc update."
echo " Option A: update or create a file in docs/ in this commit."
echo " Option B: create docs/decisions/${today}-[reason].md"
exit 1
fi
fi
chmod +x .git/hooks/commit-msg .git/hooks/pre-commit
3. .github/workflows/ci.yml:
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install
run: [install command for this stack]
- name: Lint
run: [lint command]
- name: Test
run: [test command]
- name: Coverage
run: [coverage command — fail below 80%]
Confirm: "Harness installed. commit-msg hook ✓ pre-commit cascade check ✓ CI workflow ✓"Lee docs/manifest.yaml y CONSTITUTION.md.
Instala la infraestructura de cumplimiento del harness.
1. .git/hooks/commit-msg — hacer cumplir Conventional Commits:
#!/usr/bin/env bash
msg=$(cat "$1")
pattern="^(feat|fix|chore|refactor|test|docs|style|ci|perf)(\(.+\))?: .{1,72}"
if ! echo "$msg" | grep -qE "$pattern"; then
echo "ERROR: El mensaje de commit debe seguir Conventional Commits."
echo " Formato: tipo(scope): descripción"
echo " Tipos: feat fix chore refactor test docs style ci perf"
exit 1
fi
2. .git/hooks/pre-commit — verificación de cascada:
#!/usr/bin/env bash
staged=$(git diff --cached --name-only)
src_changed=$(echo "$staged" | grep -E "^(src|app|lib|components|pages)/")
doc_changed=$(echo "$staged" | grep -E "^docs/")
if [ -n "$src_changed" ] && [ -z "$doc_changed" ]; then
today=$(date +%Y-%m-%d)
decision=$(ls docs/decisions/${today}-*.md 2>/dev/null | head -1)
if [ -z "$decision" ]; then
echo "⚠ El código cambió sin actualización de docs."
echo " Opción A: actualiza o crea un archivo en docs/ en este commit."
echo " Opción B: crea docs/decisions/${today}-[motivo].md"
exit 1
fi
fi
chmod +x .git/hooks/commit-msg .git/hooks/pre-commit
3. .github/workflows/ci.yml:
name: CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Instalar
run: [comando de instalación para este stack]
- name: Lint
run: [comando de lint]
- name: Tests
run: [comando de tests]
- name: Cobertura
run: [comando de cobertura — fallar por debajo de 80%]
Confirmar: "Harness instalado. hook commit-msg ✓ pre-commit cascada ✓ CI workflow ✓"
Note on NFR gates: NFR enforcement (P-001, R-001, S-001 thresholds from SPEC.md) activates at Tier 2 — see /harden. The harness installed here covers commit discipline and test coverage only.
Nota sobre NFR gates: El cumplimiento de NFRs (umbrales P-001, R-001, S-001 de SPEC.md) se activa en Tier 2 — ver /harden. El harness instalado aquí cubre solo disciplina de commits y cobertura de tests.
Step 02 — First Feature
Paso 02 — Primera Feature
Session entry → F-NNN → tests → green
Entrada de sesión → F-NNN → tests → verde
Open a new AI session. Paste the entry prompt first — the AI reads your three files and confirms before doing anything. Then paste the first feature prompt. The AI writes the feature spec, gets your approval, then generates tests first and implementation second. The harness verifies the output.
Abre una nueva sesión de IA. Pega primero el prompt de entrada — la IA lee tus tres archivos y confirma antes de hacer nada. Luego pega el prompt de primera feature. La IA escribe el spec de la feature, obtiene tu aprobación, luego genera tests primero e implementación después. El harness verifica el output.
02
Open a new session. Paste the entry prompt, then the feature prompt.
Abre una nueva sesión. Pega el prompt de entrada, luego el prompt de feature.
Paste this first — session entryPega esto primero — entrada de sesiónRead docs/spec/SPEC.md, then CONSTITUTION.md, then STATUS.md.
Confirm you have read all three before beginning work.Lee docs/spec/SPEC.md, luego CONSTITUTION.md, luego STATUS.md.
Confirma que leíste los tres antes de comenzar a trabajar.
Paste this — first featurePega esto — primera featureImplement F-001 from SPEC.md following the doc-first cascade.
Before writing any code:
1. Write the feature spec at docs/specs/F-001-[name].md using this format:
Actor / Precondition / Flow (numbered steps) / Postcondition /
Acceptance criteria ([ ] testable format)
2. Show me the spec. Wait for my approval.
Once I approve:
3. Generate unit tests from the acceptance criteria. They must fail first (red).
4. Generate the implementation.
5. Run the tests. All must pass (green).
6. Update STATUS.md: mark F-001 as completed, set next entry point.
7. Commit: feat(scope): implement F-001 [feature name]Implementa F-001 de SPEC.md siguiendo la cascada doc-first.
Antes de escribir código:
1. Escribe el spec de la feature en docs/specs/F-001-[nombre].md con este formato:
Actor / Precondición / Flujo (pasos numerados) / Postcondición /
Criterios de aceptación (formato [ ] verificable)
2. Muéstrame el spec. Espera mi aprobación.
Una vez que apruebo:
3. Genera tests unitarios desde los criterios de aceptación. Deben fallar primero (rojo).
4. Genera la implementación.
5. Corre los tests. Todos deben pasar (verde).
6. Actualiza STATUS.md: marca F-001 como completado, establece el próximo punto de entrada.
7. Commit: feat(scope): implementar F-001 [nombre de la feature]
The green test is the signal. The spec said what correct means. The AI built it. The harness verified it. You did not read the code.
El test en verde es la señal. El spec dijo qué significa correcto. La IA lo construyó. El harness lo verificó. No leíste el código.
Step 03 — Verify (the green test)
Paso 03 — Verifica (el test en verde)
What "correct" means at Tier 1
Qué significa "correcto" en Tier 1
At Tier 1, "correct" has a precise meaning: the acceptance criteria in the spec became tests, the tests went red, the implementation made them green, and the harness ran them. The green test is not an opinion about the code — it is mechanical evidence that the postcondition the spec described actually holds. You verify the spec was satisfied, not that the code is pretty.
En Tier 1, "correcto" tiene un significado preciso: los criterios de aceptación del spec se volvieron tests, los tests pasaron a rojo, la implementación los puso en verde, y el harness los corrió. El test en verde no es una opinión sobre el código — es evidencia mecánica de que la postcondición que describió el spec efectivamente se cumple. Verificas que el spec se satisfizo, no que el código es bonito.
For anything with a visible surface — a UI, a rendered page, an end-to-end flow — the unit test is not enough. The postcondition is something a user would see. Drive the running app, reach the postcondition state, capture a screenshot, and assert the visual result. The screenshot is the green test for the things tests-in-isolation cannot reach.
Para cualquier cosa con superficie visible — una UI, una página renderizada, un flujo end-to-end — el test unitario no alcanza. La postcondición es algo que un usuario vería. Conduce la app en ejecución, alcanza el estado de postcondición, captura un screenshot y verifica el resultado visual. El screenshot es el test en verde para lo que los tests aislados no pueden alcanzar.
03
For features with a visible surface, paste this in the same session after the green unit tests.
Para features con superficie visible, pega esto en la misma sesión después de los tests unitarios en verde.
Paste this — Playwright screenshot verificationPega esto — Verificación con screenshot PlaywrightRead docs/specs/F-001-[name].md.
Add an end-to-end verification test using Playwright that proves the
postcondition is visually true.
1. Start (or attach to) the running app.
2. Drive the app through the F-001 flow exactly as the spec's numbered steps describe.
3. At the postcondition, take a screenshot to test-results/F-001-postcondition.png.
4. Assert the visual state matches the postcondition:
- assert the expected element is visible and has the expected text/role
- assert the URL / route is the one the spec expects at this point
5. Add one error-path test: drive an invalid input from the spec's preconditions,
screenshot to test-results/F-001-error.png, and assert the app shows the
expected error state (not a crash, not a blank page).
6. Run the suite. Both paths must pass (green).
7. Commit: test(scope): e2e screenshot verification for F-001
Do not change production code to make the test pass. If the postcondition does
not hold, stop and report what the screenshot shows versus what the spec requires.Lee docs/specs/F-001-[nombre].md.
Agrega un test de verificación end-to-end usando Playwright que pruebe que la
postcondición es visualmente verdadera.
1. Inicia (o conéctate a) la app en ejecución.
2. Conduce la app por el flujo de F-001 exactamente como describen los pasos numerados del spec.
3. En la postcondición, toma un screenshot a test-results/F-001-postcondition.png.
4. Verifica que el estado visual coincide con la postcondición:
- verifica que el elemento esperado es visible y tiene el texto/rol esperado
- verifica que la URL / ruta es la que el spec espera en este punto
5. Agrega un test de ruta de error: conduce un input inválido desde las precondiciones del spec,
screenshot a test-results/F-001-error.png, y verifica que la app muestra el
estado de error esperado (no un crash, no una página en blanco).
6. Corre la suite. Ambas rutas deben pasar (verde).
7. Commit: test(scope): verificación e2e con screenshot para F-001
No cambies código de producción para hacer pasar el test. Si la postcondición no
se cumple, detente y reporta qué muestra el screenshot frente a lo que pide el spec.
The screenshot is reviewed by you; the assertions are run by the harness. You look at the picture to confirm intent — you still do not read the implementation. Both layers — unit green and visual green — are the Tier 1 definition of done.
El screenshot lo revisas tú; las aserciones las corre el harness. Miras la imagen para confirmar la intención — sigues sin leer la implementación. Ambas capas — verde unitario y verde visual — son la definición de "listo" en Tier 1.
Ongoing Work
Trabajo Continuo
Three operations — feature, fix, refactor
Tres operaciones — feature, fix, refactor
Once the harness runs, all future work is one of three patterns. Each enforces the doc-first cascade at the git level — the hooks reject commits that skip the discipline.
Una vez que el harness está en ejecución, todo el trabajo futuro es uno de tres patrones. Cada uno hace cumplir la cascada doc-first a nivel git — los hooks rechazan commits que omiten la disciplina.
New Feature
Nueva Feature
Every new feature starts with a spec file. The AI reads SPEC.md first to check phase scope, then writes F-NNN before touching code. Your approval gates the implementation.
Cada nueva feature empieza con un archivo de spec. La IA lee SPEC.md primero para verificar el scope de la fase, luego escribe F-NNN antes de tocar código. Tu aprobación es el gate de la implementación.
Feature prompt — EnglishPrompt de feature — InglésRead docs/spec/SPEC.md, then CONSTITUTION.md, then STATUS.md. Confirm you have read all three.
New feature request: [describe the feature in one sentence].
Before writing any code:
1. Check if this feature fits the current phase scope in SPEC.md. If not, flag it and stop.
2. Write the feature spec at docs/specs/F-[NNN]-[slug].md:
Actor / Precondition / Flow / Postcondition / Acceptance criteria (testable, [ ] format)
3. Show me the spec. Wait for my approval before proceeding.
4. Once approved:
- Generate unit tests from the acceptance criteria (failing first)
- Generate the implementation
- Run tests — all must pass
5. Update STATUS.md.
Commit: feat(scope): [description]Lee docs/spec/SPEC.md, luego CONSTITUTION.md, luego STATUS.md. Confirma que leíste los tres.
Nueva funcionalidad: [describe la feature en una oración].
Antes de escribir código:
1. Verifica si esta feature cabe en el scope de la fase actual en SPEC.md. Si no, márcalo y detente.
2. Escribe el spec de la feature en docs/specs/F-[NNN]-[slug].md:
Actor / Precondición / Flujo / Postcondición / Criterios de aceptación (verificables, formato [ ])
3. Muéstrame el spec. Espera mi aprobación antes de continuar.
4. Una vez aprobado:
- Genera tests unitarios desde los criterios de aceptación (fallando primero)
- Genera la implementación
- Corre los tests — todos deben pasar
5. Actualiza STATUS.md.
Commit: feat(scope): [descripción]
Bug Fix
Fix de Bug
Every fix starts with a failing test that reproduces the bug. The test is committed first — this proves the bug exists and proves the fix worked. A one-paragraph decision note in docs/decisions/ explains root cause.
Cada fix empieza con un test fallido que reproduce el bug. El test se commitea primero — esto prueba que el bug existe y prueba que el fix funcionó. Una nota de decisión de un párrafo en docs/decisions/ explica la causa raíz.
Fix prompt — EnglishPrompt de fix — InglésRead CONSTITUTION.md.
Bug: [describe the bug — what happens, what should happen instead].
1. Write a failing test that reproduces the bug exactly. Commit: test(scope): reproduce [bug-slug]
2. Create docs/decisions/[YYYY-MM-DD]-fix-[bug-slug].md — one paragraph: root cause.
3. Patch the code. The failing test must now pass. No other tests may break.
4. Commit: fix(scope): [description]Lee CONSTITUTION.md.
Bug: [describe el bug — qué pasa, qué debería pasar en cambio].
1. Escribe un test fallido que reproduzca el bug exactamente. Commit: test(scope): reproduce [bug-slug]
2. Crea docs/decisions/[AAAA-MM-DD]-fix-[bug-slug].md — un párrafo: causa raíz.
3. Parchea el código. El test fallido debe pasar ahora. Ningún otro test puede fallar.
4. Commit: fix(scope): [descripción]
Refactor, Dedup, Dead Code
Refactor, Deduplicación, Código Muerto
Structural changes always start with an ADR. No behavior changes — only structural. All existing tests must pass. Dead code is removed only after confirming it's outside SPEC.md scope. The ADR moves to docs/adrs/done/ when complete.
Los cambios estructurales siempre empiezan con un ADR. Sin cambios de comportamiento — solo estructurales. Todos los tests existentes deben pasar. El código muerto se elimina solo después de confirmar que está fuera del scope de SPEC.md. El ADR se mueve a docs/adrs/done/ cuando está completo.
Refactor prompt — EnglishPrompt de refactor — InglésRead CONSTITUTION.md and docs/spec/SPEC.md.
Refactoring task: [describe what to clean up — duplication / dead code / structure / rename].
1. Write ADR at docs/adrs/active/ADR-[NNN]-[slug].md:
Context (why this refactor) / Decision (what changes) / Consequences (easier/harder)
2. Rules: no behavior changes — structural only. All existing tests must pass after.
3. If removing dead code: confirm each deletion is outside SPEC.md scope first.
4. Commit: refactor(scope): [description]
5. Move ADR to docs/adrs/done/ when complete.Lee CONSTITUTION.md y docs/spec/SPEC.md.
Tarea de refactor: [describe qué limpiar — duplicación / código muerto / estructura / renombrado].
1. Escribe ADR en docs/adrs/active/ADR-[NNN]-[slug].md:
Contexto (por qué este refactor) / Decisión (qué cambia) / Consecuencias (más fácil/difícil)
2. Reglas: sin cambios de comportamiento — solo estructurales. Todos los tests existentes deben pasar.
3. Si eliminás código muerto: confirma que cada eliminación está fuera del scope de SPEC.md.
4. Commit: refactor(scope): [descripción]
5. Mueve el ADR a docs/adrs/done/ cuando termines.
New phase = update SPEC.md (add the next phase's scope + features) then proceed with features/fixes/refactors. The three operations cover the entire ongoing lifecycle.
Nueva fase = actualiza SPEC.md (agrega el scope + features de la siguiente fase) luego procede con features/fixes/refactors. Las tres operaciones cubren todo el ciclo de vida continuo.