Ship features without shipping regrets.
UX first, oaths second, witnesses third: brief the intent, swear what must stay true, prove it with tests, seal nothing until the proof holds.
VIGIL (Verified Invariant-Guided Implementation Layer) is a lightweight ritual for disciplined feature work. Flow: brief → oaths → edges → witnesses → rites → seal — intent first, guarantees second, proof third.
Oaths follow UX, not APIs. You derive oaths from the brief (what the user must see, do, and trust). See VIGIL.md § UX + Invariants First.
# From this repo (or copy vigil.sh + templates/ into your project)
./vigil.sh new auth-flow
# Fill templates under .vigil/vigils/auth-flow/
# brief.md — UX intent first (who, flow, success, a11y)
# oaths.md — invariants that brief commits to (not “API shape first”)
# witnesses.md — TDD: tests that prove each oath
./vigil.sh seal auth-flowOrder matters: context → qualify → brief (UX) → oaths (invariants) → edges → witnesses (TDD) → rites → contain → seal.
VIGIL forces you to:
- Brief — User-visible intent: who, flow, success, failure/recovery, a11y
- Oath — Guarantees with observable signals (invariants)
- Witness — Tests that prove each oath (integration + value assertions when needed)
- Contain — Implement in scoped rites; vertical slice: visible → state → API → storage
- Seal — Merge only when witnesses pass
| Template | Use For |
|---|---|
canon.md |
Project-wide oaths |
context.md |
Test infra, frameworks, integration points |
brief.md |
UX intent + success criteria (start here) |
story.md |
Optional: longer UX narrative if brief is crowded |
questions.md |
Optional: blocking unknowns before oaths freeze |
oaths.md |
Invariant catalog |
edges.md |
Edge cases (incl. content/value scenarios) |
witnesses.md |
Test plan |
rite.md |
Implementation packets |
seal.md |
Post-implementation verification |
lite.md |
Simplified vigil for small changes |
| Level | When Broken | Review Requirement |
|---|---|---|
| P0 | User trust, data loss, security | Rollback immediately, 2 reviewers |
| P1 | Core workflow reliability | Fix before seal, 1 reviewer |
| P2 | Quality improvement | Patch next cycle, optional review |
Claude Code: Commands in CLAUDE.md
Cursor: Rules in .cursor/rules/vigil.mdc
VIGIL.md — full spec (UX + invariants, ritual sequence, value witnesses, anti-patterns).
The Vigil watches. The Vigil remembers.
No regression ships unsealed.