F3: Foundation-First Framework

your-project/
├── F3_FRAMEWORK.md      # F3 hub — start here (routes to modules)
├── F3_CORE.md           # Methodology, standards, guardrails
├── F3_PROMPTS.md        # All Claude Code prompts
├── F3_TEMPLATES.md      # Document templates (CLAUDE.md, SPEC, etc.)
├── F3_SETUP.md          # Setup guides (new & existing projects)
├── F3_CHANGELOG.md      # Version history & roadmap
├── SPEC.md              # Project requirements
├── PLAN.md              # Architecture & implementation plan
├── CLAUDE.md            # Lean bootstrap — Claude Code
├── CURSOR.md            # Lean bootstrap — Cursor
├── GEMINI.md            # Lean bootstrap — Gemini CLI
├── CONTRIBUTORS.md      # Team roles & ownership registry       ← NEW v5.0.0
├── FIRST_RUN.md         # Bootstrap — written by installer, deleted on first ES  ← gitignored
├── f3-foundation/
│   ├── tools/
│   │   ├── setup-f3.js                   # F3 installer (self-contained — all framework files embedded)
│   │   ├── f3-audit.js                   # Existing Project Protocol — deep codebase audit
│   │   ├── generate-governance-report.js # Session governance report generator
│   │   └── uninstall-f3.js               # F3 removal tool — reverses the installer's changes
│   ├── compat/                          ← NEW v5.0.0
│   │   ├── README.md                     # Index of F3 compatibility guides
│   │   └── superpowers.md                # Running F3 alongside Superpowers (obra / Jesse Vincent)
│   └── scripts/
│       ├── load-context.sh               # On-demand context loader (macOS/Linux)
│       └── load-context.js               # On-demand context loader (Windows)
├── .codex/
│   └── AGENTS.md        # Lean bootstrap — Codex
├── .f3/
│   └── session.active   # Session presence marker               ← gitignored
├── .claude/
│   ├── settings.json    # Claude Code config (hooks + permissions)
│   ├── commands/f3/     # Slash commands — one file per /project:f3:[name]
│   │   ├── ss.md               # /project:f3:ss          — Session Start
│   │   ├── es.md               # /project:f3:es          — Session End (compiles commit/)
│   │   ├── doco.md             # /project:f3:doco        — Documentation Checkpoint
│   │   ├── fd.md               # /project:f3:fd          — Feature Discovery
│   │   ├── fp.md               # /project:f3:fp          — Feature Planning
│   │   ├── fi.md               # /project:f3:fi          — Feature Implementation
│   │   ├── fc.md               # /project:f3:fc          — Feature Complete
│   │   ├── audit.md            # /project:f3:audit       — Discovery Audit Checklist
│   │   ├── gr.md               # /project:f3:gr          — Governance Report
│   │   ├── archrebuild.md      # /project:f3:archrebuild — Weekly Layer 2 rebuild (Lead)
│   │   ├── crash.md            # /project:f3:crash       — Crash Recovery
│   │   ├── thrash.md           # /project:f3:thrash      — Thrash Detection
│   │   ├── reset.md            # /project:f3:reset       — Thrash Reset
│   │   └── update.md           # /project:f3:update      — F3 Version Update
│   └── hooks/
│       ├── f3-phase-gate.sh        # Foundation check (macOS/Linux) — blocks if SPEC/PLAN missing
│       ├── f3-phase-gate.js        # Foundation check (Windows/cross)
│       ├── f3-restart-gate.sh      # Restart Gate (macOS/Linux)
│       ├── f3-restart-gate.js      # Restart Gate (Windows/cross)
│       ├── f3-commit-gate.sh       # Commit Gate — enforcement only (macOS/Linux)
│       ├── f3-commit-gate.js       # Commit Gate — enforcement only (Windows)
│       ├── f3-thrash-detector.sh    # Thrash Detector (macOS/Linux)
│       ├── f3-thrash-detector.js    # Thrash Detector (Windows/cross)
│       ├── f3-first-run-loader.sh   # First-Run Loader (macOS/Linux) — injects FIRST_RUN.md
│       └── f3-first-run-loader.js   # First-Run Loader (Windows/cross)
├── .githooks/
│   └── pre-commit       # Universal Git commit gate — all editors
├── commit/              # Permanent session record ← NEW v5.0.0 (committed)
│   └── YYYY/
│       └── MM/
│           └── YYYY-MM-DD_[developer]_[hash].md   # ES commit document
├── docs/
│   ├── architecture.md  # System design
│   ├── api.md           # API contracts
│   ├── stack.md         # Tech stack details
│   ├── decisions.md     # Architecture Decision Records
│   ├── checkpoint.md    # Session intent — written at session OPEN     ← gitignored
│   ├── devlog.md        # Session logs (append-only)                    ← gitignored
│   ├── TASKS.md         # Developer task tracking               ← gitignored
│   ├── changelog.md     # Release history
│   ├── AUDIT.md         # Discovery audit — Existing Project Protocol only
│   ├── analysis/        # Scratch analysis files                ← gitignored
│   ├── migration/       # Developer briefs + upgrade scratch    ← gitignored
│   └── governance/      # Session governance reports (JSON + Markdown)
└── [your code here]     # Organize however you want

# Create the tools folder and drop setup-f3.js into it
mkdir -p f3-foundation/tools
cp ~/Downloads/setup-f3.js f3-foundation/tools/setup-f3.js

# Run the installer — auto-detects project type
node f3-foundation/tools/setup-f3.js
claude

# Step 0 — Create the tools folder and drop setup-f3.js into it
mkdir -p f3-foundation/tools
cp ~/Downloads/setup-f3.js f3-foundation/tools/setup-f3.js

# Step 1 — Install F3 into your project folder
node f3-foundation/tools/setup-f3.js

# Step 2 — Open Claude Code (or Cursor, Codex, Gemini)
claude

# Step 3 — Send the message "first-run" as your first prompt
# The f3-first-run-loader hook injects FIRST_RUN.md into Claude's context;
# Claude acknowledges the first-run session and guides you from there.

# Create the tools folder and drop setup-f3.js into it
mkdir -p f3-foundation/tools
cp ~/Downloads/setup-f3.js f3-foundation/tools/setup-f3.js

# Install F3 — auto-detects existing codebase, runs audit, writes FIRST_RUN.md
node f3-foundation/tools/setup-f3.js

# Open Claude, then send the message "first-run" to trigger the onboarding sequence
claude
# (in Claude, type:) first-run

# f3-foundation/tools/ already exists from the previous install —
# just copy the new setup-f3.js over the old one.
cp ~/Downloads/setup-f3.js f3-foundation/tools/setup-f3.js

# Use --update — preserves your customized CLAUDE.md, docs/, and project content.
# Overwrites framework files, hooks, and settings; writes upgrade-variant FIRST_RUN.md.
node f3-foundation/tools/setup-f3.js --update

# Open Claude, then send "first-run" to trigger the v5.x upgrade sequence
claude
# (in Claude, type:) first-run

# Step 0 — Create the tools folder and drop setup-f3.js into it
mkdir -p f3-foundation/tools
cp ~/Downloads/setup-f3.js f3-foundation/tools/setup-f3.js

# Step 1 — Run the installer (auto-detects existing codebase)
node f3-foundation/tools/setup-f3.js
# Runs f3-audit.js --quiet automatically
# Writes FIRST_RUN.md with audit summary baked in
# Creates commit/YYYY/MM/, CONTRIBUTORS.md, updates .gitignore

# Step 2 — Open Claude
claude

# Step 3 — Send the message "first-run" as your first prompt
# The f3-first-run-loader hook injects FIRST_RUN.md into Claude's context.
# Claude acknowledges the first-run session and self-directs:
#   → Reviews docs/AUDIT.md findings
#   → Creates CLAUDE.md + all docs/ files from templates
#   → Builds retroactive SPEC.md + PLAN.md
#   → Seeds TASKS.md with Critical/High audit findings
#   → Pauses for your approval before Build phase begins

node f3-foundation/tools/f3-audit.js              # Full 4-phase audit
node f3-foundation/tools/f3-audit.js --phase 1    # Phase 1 only (Discovery Audit)
node f3-foundation/tools/f3-audit.js --reaudit    # Delta re-audit against existing AUDIT.md
node f3-foundation/tools/f3-audit.js --help       # Usage reference

node f3-foundation/tools/f3-audit.js --reaudit

node f3-foundation/tools/uninstall-f3.js              # Interactive uninstall
node f3-foundation/tools/uninstall-f3.js --dry-run    # Preview what would be removed
node f3-foundation/tools/uninstall-f3.js --force      # Skip per-step confirmations
node f3-foundation/tools/uninstall-f3.js --help       # Full usage reference

# Both JSON + Markdown (default)
node f3-foundation/tools/generate-governance-report.js

# Format options
node f3-foundation/tools/generate-governance-report.js --format json   # JSON only
node f3-foundation/tools/generate-governance-report.js --format md     # Markdown only

# List existing reports
node f3-foundation/tools/generate-governance-report.js --list

# In Claude Code (richer — uses full session context)
/project:f3:gr

I want to document the current state of [FUNCTIONALITY NAME] in this
project before proposing any changes.

This is Stage 1 — Architecture Reference. Understand and document
what exists today. No migration proposals, no recommendations. Facts only.

Replace [FUNCTIONALITY NAME] with the specific area you are documenting.
If you know where it lives, add: "Start your search in [path/to/area]"

---

**Step 1: System Context**
Before touching files, establish the big picture:
- What is this functionality and what business purpose does it serve?
- What triggers it? (user action, event, API call, cron, message queue)
- What systems does it touch? (databases, external APIs, internal services,
  message queues, third-party platforms)
- What does it produce or change? (state changes, records created, emails
  sent, payments processed, etc.)
- What are the system boundaries — what is inside this functionality
  vs. what it depends on?

Write a 3–5 sentence system context summary before proceeding.

**Step 2: File Inventory**
Find every file, class, function, route, model, config, migration,
and test that is part of or directly touches [FUNCTIONALITY NAME]:
- Entry points (routes, endpoints, event listeners, CLI commands)
- Core logic (services, utilities, helpers, pipelines, processors)
- Data layer (models, schema, migrations, queries, stored procedures)
- Configuration (env vars, config files, feature flags, admin settings)
- Integration points (external service clients, XML/API contracts)
- Tests (what exists — note if none)

Present as a table: File path | Role in this functionality.
Group by category (Core Logic, Configuration, UI, etc.)

**Step 3: Business Rules**
Extract the explicit business rules from the code — not the implementation,
the rules the implementation enforces:
- Calculation rules (formulas, rates, thresholds, caps, rounding)
- Conditional rules (when X apply Y, if state = Z then...)
- Validation rules (what is required, what is rejected)
- Exception rules (what bypasses normal processing)
- State rules (what triggers state changes, what states are possible)

State each rule in plain language. Reference the file that enforces it.
Flag any rules that appear to be hardcoded vs. configurable.

**Step 4: Combined Scenario**
This is the most important step. Trace a single realistic transaction
that exercises ALL sub-systems simultaneously — the most complex real-world
case this functionality handles.

For example: an order with mixed taxable and non-taxable items,
a shippable product and a non-shippable item, a discount voucher applied,
and a non-standard tax jurisdiction.

Show:
- The exact sequence of operations in order
- Intermediate values at each calculation step
- Which component produces each value
- The final output and how each number was derived

This combined scenario is the definitive test of whether the architecture
is understood. If it cannot be traced end-to-end, flag what is missing.

**Step 5: Data Model**
For every database table, schema, entity, or data structure involved:
- Field names, types, constraints, defaults
- Relationships and foreign keys
- Custom fields, dynamic properties, or key-value stores
- What each field is set by, and when
- Indexes relevant to this functionality

**Step 6: Integration Contracts**
For every external system or service this functionality touches:
- What data is sent (format, fields, timing)
- What data is received (format, fields, error handling)
- What breaks if the contract changes
- Any known versioning or compatibility constraints

**Step 7: Flags and Concerns**
Without proposing fixes, document:
- [CONCERN] — patterns that are fragile, inconsistent, or risky
- [INFERRED] — behavior read from code that cannot be fully confirmed
- [UNCLEAR] — logic that is ambiguous or hard to follow
- [UNDOCUMENTED] — behavior with no tests or comments explaining intent
- [DEPENDENCY] — non-obvious things this functionality relies on
- [HARDCODED] — values that should be configurable but are not
- [DUPLICATE] — logic that exists in more than one place

**Step 8: Open Questions**
List every question that would need to be answered before a migration
or improvement could be safely planned. Be specific — not "how does
discount work" but "which campaign award types are currently active
in the database and what are their targeting rules?"

**Step 9: Save the output**
Save to: docs/analysis/[functionality-name]-architecture-reference.md

Include at the top:
- Date
- Scope (exactly what was included and excluded)
- Status: Stage 1 — Architecture Reference. Facts only.

Present the completed document for review before Stage 2 begins.

Read docs/analysis/[functionality-name]-architecture-reference.md

This is Stage 2 — Architecture Brief. Using only the Stage 1 reference
as your source, produce a structured brief written for an architect.
The brief must be structured so sections can be lifted directly into
an FDS (Functional Design Specification) and a TDS (Technical Design
Specification) without the architect needing to re-read the codebase.

Do not re-scan the codebase. Work from Stage 1 only. If Stage 1 is
missing information required for a section, flag it explicitly rather
than going back to the code.

---

**Section 1: Executive Summary**
3–5 sentences. What does this functionality do, why does it exist,
and what is its role in the larger system? Written for someone who
has never seen this codebase. No technical jargon — business language.

**Section 2: Key Facts** (FDS input)
A scannable reference block. Each fact on one line:
- What triggers this functionality
- Who or what it affects
- What it produces or changes
- What it does NOT do (explicit scope boundary)
- Platform/framework it runs on
- Any known limitations or constraints a business stakeholder should know

**Section 3: Business Rules** (FDS input)
Every business rule from Stage 1, stated in plain language suitable
for an FDS. Group by sub-system. Each rule should be:
- Stated as a declarative sentence ("Tax is calculated on...")
- Attributed to its source ("configured in X" / "hardcoded in Y")
- Flagged if it is assumed vs. confirmed

**Section 4: User-Facing Behavior** (FDS input)
What the user experiences at each stage of this functionality:
- What they see before, during, and after
- What triggers state changes from the user's perspective
- What feedback they receive (success, error, edge cases)
- What they cannot do (blocked states, validation messages)

**Section 5: Combined Scenario** (FDS + TDS input)
Reproduce the combined scenario from Stage 1 — the single realistic
transaction that exercises all sub-systems simultaneously.
This section serves both documents:
- FDS: the scenario as a narrative ("A member adds two products...")
- TDS: the scenario as a technical trace (exact sequence, values, components)

Present both versions.

**Section 6: System Architecture** (TDS input)
- System context diagram (ASCII) — this system and everything it connects to
- Component map — what each layer owns (platform vs. custom code)
- Key architectural decisions and their rationale
- What the platform provides vs. what custom code overrides
- Upgrade and maintainability implications of the current architecture

**Section 7: Integration Contracts** (TDS input)
For every external system:
- What is sent, in what format, when
- What is received, in what format
- What breaks if the contract changes
- Migration risk rating: Low / Medium / High

**Section 8: Data Model Summary** (TDS input)
The data model at architecture level — not field-by-field, but:
- Key entities and their relationships
- Custom fields or dynamic property stores
- Data that lives outside the primary database (config files, settings)
- What must be preserved exactly in any migration

**Section 9: Risk Surface** (TDS input)
Ranked list of the top concerns from Stage 1, grouped by category:
- Data integrity risks
- Integration risks
- Performance risks
- Business logic risks (silent failures, hardcoded values, etc.)
- Testing gaps

For each: one sentence description, one sentence on migration implication.

**Section 10: Open Questions**
Carry forward the open questions from Stage 1 plus any new ones
surfaced during brief preparation. Flag which questions must be
answered before migration can be planned vs. which can be deferred.

---

**Save the output**
Save to: docs/analysis/[functionality-name]-architecture-brief.md

Include at the top:
- Date
- Source: docs/analysis/[functionality-name]-architecture-reference.md
- Status: Stage 2 — Architecture Brief. Input for FDS and TDS.

Present the completed brief for review before Stage 3 begins.

Read docs/analysis/[functionality-name]-architecture-reference.md
Read docs/analysis/[functionality-name]-architecture-brief.md

This is Stage 3 — Developer Brief. Using Stage 1 and Stage 2 as your
source, produce a task-oriented brief for a developer. This is not a
narrative document. It is a set of task lists. A developer picks up
a task, executes it, checks it off. No interpretation required.

Do not re-scan the codebase. Work from Stage 1 and Stage 2 only.

---

**Structure the output as follows:**

**1. Orientation Block**
5 lines maximum. The developer needs to know:
- What this functionality does (one sentence)
- Where it lives (primary directories/files)
- What platform/framework it runs on
- The single most important thing to understand before touching it
- Where to go if something is unclear (Stage 1 reference path)

**2. Component Map**
A flat list of every component involved, each with:
- Component name
- File path(s)
- One-line description of its role
- Dependencies (what it calls, what calls it)

No narrative. Reference only.

**3. Task Lists by Component**
For each component, a numbered task list. Each task must include:

  [ ] Task title (verb-noun: "Update", "Replace", "Remove", "Add")
      File: [exact file path]
      What: [exactly what to change — specific enough to act on]
      Why: [one sentence — the business or technical reason]
      Depends on: [task number(s) that must complete first, or "none"]
      Acceptance: [how to verify this task is complete]

Group tasks within each component in execution order.
Flag tasks that can run in parallel vs. tasks that must be sequential.

**4. Execution Order**
A numbered sequence showing which components to work on in what order,
and which tasks within each component must complete before the next
component begins. Flag any parallel tracks.

**5. Integration Checkpoints**
For every external system touched:
- What must be verified before touching integration code
- What must be tested after any change
- Who owns the external system (contact or team if known)
- Rollback procedure if integration breaks

**6. Acceptance Criteria**
The combined scenario from Stage 2, restated as a developer checklist:
- [ ] Given [condition], when [action], then [expected result]
One line per testable behavior. These are the pass/fail criteria
for the complete functionality, not individual tasks.

**7. Open Questions**
Carry forward any unresolved questions from Stage 1 and Stage 2
that a developer would need answered before starting work.
Flag which questions block specific tasks.

---

**Save the output**
Save to: docs/migration/[functionality-name]-developer-brief.md

Include at the top:
- Date
- Source: Stage 1 + Stage 2 reference paths
- Status: Stage 3 — Developer Brief. Ready for execution.

Present the completed brief for review.

Read @F3_CORE.md section "EXISTING PROJECT PROTOCOL — 4-Phase Deep Buildout" 
and @F3_TEMPLATES.md, then execute all four phases for this project.

Each phase pauses for my approval before proceeding to the next.

---

PHASE 1: Discovery Audit → docs/AUDIT.md

Analyze this codebase and produce docs/AUDIT.md using the AUDIT.md 
template from @F3_TEMPLATES.md. Cover all seven audit categories:

1. Security — hardcoded secrets, exposed endpoints, unvalidated inputs
2. Accessibility — WCAG violations, missing ARIA, inaccessible elements
3. Dead Files — unused components, orphaned routes, unreferenced assets
4. Dependencies — outdated packages, vulnerabilities, license issues
5. Docs Gaps — missing README, undocumented APIs, no architecture docs
6. Version Control — .gitignore gaps, untracked sensitive files
7. Production Standards — evidence of logging, error handling, testing

Rate every finding: Critical / High / Medium / Low.
Flag inferred findings: [INFERRED — REQUIRES CONFIRMATION]
Flag contradictions: [CONTRADICTION — REQUIRES DECISION]
Flag unknowables: [UNKNOWN — REQUIRES INVESTIGATION]

Present AUDIT.md and wait for my approval before Phase 2.

---

PHASE 2: Retroactive Foundation → SPEC.md + PLAN.md

Create SPEC.md documenting what this application DOES (not what was planned).
Create PLAN.md documenting the architecture AS IT EXISTS.
Minimum bar: 3 core features with acceptance criteria; all active API 
endpoints listed. Mark genuinely unknowable items [UNKNOWN].
Present both and wait for my approval before Phase 3.

---

PHASE 3: Documentation Build → all 8 docs/ files

Populate the full F3 documentation system from codebase analysis.
No empty templates — real content only.
Inferred decisions marked [RETROACTIVE ADR] in decisions.md.
todo.md seeded with Critical + High findings from AUDIT.md.
Present summary and wait for my approval before Phase 4.

---

PHASE 4: Risk Summary → docs/TASKS.md

Generate docs/TASKS.md from AUDIT.md findings.
Priority: Critical → High → Medium → Low.
Each task: time estimate, exact files, acceptance criteria, test step.
Present TASKS.md and wait for my approval.

---

After all four phases:
1. List all files created or updated
2. Summarize key findings from AUDIT.md
3. List all flags requiring my decision ([INFERRED], [CONTRADICTION], [UNKNOWN])
4. Recommended first 3 tasks from TASKS.md
5. Confirm project is now F3-compliant

Read @F3_CORE.md section "EXISTING PROJECT PROTOCOL" and 
@F3_TEMPLATES.md section "docs/AUDIT.md", then run a full 
Discovery Audit on this codebase.

Work through all seven audit categories:

Category 1: Security
- Hardcoded secrets, API keys, passwords, tokens in source files
- .env files committed to version control
- Unvalidated or unsanitized user inputs
- SQL queries built by string concatenation
- Missing authentication or authorization on sensitive operations
- Sensitive data logged (passwords, PII, tokens)

Category 2: Accessibility
- Interactive elements using div/span instead of button/a
- Images missing alt attributes
- Form inputs missing associated labels
- Missing ARIA landmarks (main, nav, header, footer)
- No visible focus indicators on interactive elements
- Dynamic content not announced via aria-live

Category 3: Dead Files
- Components imported nowhere
- Routes never linked to or loaded
- CSS/SCSS files never imported
- Commented-out code blocks 10+ lines
- Test files for components that no longer exist

Category 4: Dependencies
- Packages more than 2 major versions behind
- Known CVEs (from npm audit / pip-audit / composer audit)
- Duplicate packages serving the same purpose
- Dev dependencies in production bundle

Category 5: Docs Gaps
- README absent or missing setup instructions
- API endpoints with no documentation
- No architecture documentation
- No .env.example

Category 6: Version Control
- .gitignore missing or inadequate
- .env files not in .gitignore
- Large binary files committed

Category 7: Production Standards
- No logging library or logging calls present
- Raw errors returned to users
- No test files present

For each finding:
- Assign severity: Critical / High / Medium / Low
- Reference the exact file(s)
- Describe the remediation action
- Flag inferred items: [INFERRED — REQUIRES CONFIRMATION]
- Flag contradictions: [CONTRADICTION — REQUIRES DECISION]
- Flag unknowables: [UNKNOWN — REQUIRES INVESTIGATION]

Populate docs/AUDIT.md using the template from @F3_TEMPLATES.md.
Present the completed AUDIT.md for my review.
Wait for my approval before proceeding to Phase 2.

Read @F3_CORE.md section "EXISTING PROJECT PROTOCOL" and the 
existing docs/AUDIT.md, then run a Re-Audit of this codebase.

This is a delta audit — compare current state against the previous AUDIT.md.

Step 1: Establish baseline
Read docs/AUDIT.md and note:
- Previous audit date
- Finding counts by category and severity
- Items previously marked [INFERRED], [CONTRADICTION], or [UNKNOWN]
- Items in the Remediation Backlog

Step 2: Re-scan all seven categories
Run the same Discovery Audit Checklist against the current codebase:
Security · Accessibility · Dead Files · Dependencies · Docs Gaps · 
Version Control · Production Standards

Step 3: Generate delta report
For each category, produce a delta table:
| Finding | Previous Status | Current Status | Change |
- ✅ Fixed — finding resolved since last audit
- ⚠️ Unresolved — still present
- 🆕 New — not in previous audit

Step 4: Check flag resolution
For each previous [INFERRED], [CONTRADICTION], [UNKNOWN] flag:
- Confirmed? Resolved?
- Still unresolved? → Escalate to next severity level.

Step 5: Append re-audit to docs/AUDIT.md
Do NOT overwrite original. Append:
- Delta summary table
- Resolved findings list
- New findings list  
- Still-unresolved list (with escalations)
- Updated remediation backlog

Step 6: Present delta report showing:
- What improved (resolved findings)
- What regressed or is new
- What remains unresolved (with escalations)
- Whether Critical/High severity decreased, increased, or held

Rebuild the stable-reference documentation from the commit/ record.

This command rebuilds /docs/architecture.md, /docs/api.md, /docs/stack.md,
and /docs/decisions.md from scratch by synthesizing every session recorded
in the commit/ folder. Lead-role command. Run weekly.

Step 1: Inventory the commit record
Read every file in commit/ in chronological order. Build a synthesis of:
- Components added, modified, removed (architecture)
- API endpoints added, modified, removed (api)
- Dependencies added, removed, or version-changed (stack)
- Architectural and technical decisions made (decisions)

Step 2: Cross-reference with current code
For each synthesized finding, verify against current code:
- Architecture — component inventory vs src/ or app/ or lib/
- API — documented endpoints vs what the code exposes
- Stack — documented dependencies vs package.json, composer.json, requirements.txt
- Decisions — each ADR vs current implementation

Flag every discrepancy as a DOC-DRIFT item in /docs/todo.md.

Step 3: Rebuild each doc from scratch
Using the templates from @F3_TEMPLATES.md and the synthesized commit-record
findings, rebuild each of the four docs. Start from the template — not
from the existing doc. Starting from the existing doc propagates stale
content.

For each rebuilt doc:
1. Show me the current version vs the proposed new version (diff)
2. Highlight what changed and why
3. Wait for my explicit approval before overwriting

Step 4: Update devlog.md
Append an archrebuild entry:
## ARCHREBUILD - [TIMESTAMP]
**Commit range synthesized:** [first commit file] through [last commit file]
**Docs rebuilt:** [unchanged or rewritten per doc]
**DOC-DRIFT items flagged:** [count and brief description]
**Approved by:** [Lead name]

Authority
This is a Lead-role command. It overwrites Layer 2 stable-reference
documentation — the project's architectural contract.
- Do not run without Lead approval
- If a non-Lead requests it: refuse; explain it requires Lead approval

I've updated the F3 Framework files in this project. Please bring 
everything up to date.

**Step 1: Discover what changed**
- Read @F3_FRAMEWORK.md to confirm the new version number
- Read @F3_CHANGELOG.md and find every version between this project's 
  current version (check CLAUDE.md → "Current F3 Version") and the 
  new version
- List all changes: new files, updated templates, new prompts, new 
  workflow steps, breaking changes, fixes, new hooks

**Step 2: Audit the project against the new version**
- Read @F3_TEMPLATES.md and compare the CLAUDE.md template against 
  this project's actual CLAUDE.md — identify every section that is 
  missing, outdated, or differs from the current template
- Check /docs/ for any new files the updated version requires that 
  don't exist yet
- Read @F3_SETUP.md and compare .claude/settings.json against the 
  current starter config — identify missing hooks, permissions, or 
  hook events
- Check .claude/hooks/ for any new or updated hook scripts the 
  version requires
- Check .gitignore for any new entries needed
- Check for any renamed, moved, or restructured sections

**Step 3: Show me the plan**
For each change, show:
- What needs to be added, updated, or created
- For CLAUDE.md: the specific sections affected (not the whole file)
- For new /docs/ files: which template they come from
- For .claude/settings.json: the specific hooks or events to add
- For new hook scripts: which platform version to use (ask if unclear)
- Anything that looks like it conflicts with project-specific content

**Step 4: Wait for my approval**
Do NOT make changes until I approve the plan.

**Step 5: Apply approved changes**
- Update CLAUDE.md F3 framework sections (Session Protocol, Build ↔ 
  Guide Cycle, Documentation Map, Doc Update Triggers, Operational 
  Guardrails, Session Start/End checklists, Pre-Implementation 
  Checkpoint, etc.)
- Create any new /docs/ files using templates from @F3_TEMPLATES.md, 
  initialized with current project state
- Update .claude/settings.json with any new hooks or hook events
- Create any new hook scripts in .claude/hooks/ from @F3_SETUP.md
- Update .gitignore if needed
- Update the "Current F3 Version" in CLAUDE.md

**Step 6: Confirm**
- List every file created or modified
- Confirm the version number is current
- Note any manual follow-up needed (e.g., chmod +x on new .sh scripts)

Do NOT change project-specific content (Quick Context, Tech Stack, 
Current Development Phase, Critical Conventions, project-specific 
warnings, etc.) — only update F3 framework sections, hooks, and 
create new F3 files.

Let's start a new session. Please:

1. Read CLAUDE.md for project context
2. If FIRST_RUN.md exists — read it and follow its instructions first
3. Write /docs/checkpoint.md — declare starting state and what we're
   taking on this session
4. Read the most recent file in commit/ — full previous session record
5. Check /docs/TASKS.md for current priorities
6. Review the last entry in /docs/devlog.md
7. Give me a brief status: where we left off, what's next, any blockers

Then let's continue with [describe what you want to work on].

See .claude/commands/f3/es.md for the full v5.0.0 session close protocol.

Summary of what /project:f3:es does:
1. Updates devlog.md, TASKS.md, decisions.md, CLAUDE.md current phase
2. Compiles full ES commit document to commit/YYYY/MM/
3. Deletes .f3/session.active and FIRST_RUN.md if present
4. Executes git commit with session summary message
5. Renames commit document with actual hash, then amends

Run /project:f3:es to execute.

STOP - we hit a blocker that's halting progress.

Document this NOW in /docs/devlog.md:

## BLOCKER - [TIMESTAMP]

**Issue:** [Exactly what broke or what's missing]
**Impact:** [Why this stops progress completely]
**Context:** [What we were doing when this happened]
**Resolution Plan:** [Steps needed to fix this]
**Estimated Downtime:** [Your time estimate]

Then pause work until the blocker is resolved.

We just completed [FEATURE/COMPONENT NAME]. Before moving on, 
document this work NOW:

1. **devlog.md** — Add a timestamped entry:
   - What was built and why
   - Key decisions made during implementation
   - Any deviations from the original plan and rationale
   - Any gotchas or lessons learned

2. **Run the Documentation Update Triggers:**
   Check every trigger in the F3 Documentation Update Triggers table 
   and update all applicable docs:
   - API endpoints added/changed → api.md
   - Modules/services/data flow changed → architecture.md  
   - Non-trivial tech choices made → decisions.md (add ADR)
   - Dependencies changed → stack.md
   - Schema changes → architecture.md + api.md
   - Auth changes → architecture.md + api.md + decisions.md

3. **todo.md** — Mark completed items done, add any new items 
   that surfaced during implementation

4. **CLAUDE.md** — Update "Current Development Phase" if the 
   completed feature changes project status

5. **Confirm** — List which docs were updated and summarize 
   changes in 2-3 sentences.

Do NOT skip this step. Do NOT defer to session end.

DOCUMENTATION CHECKPOINT — This session has been running for a while. 
Before we continue, do a full documentation sweep NOW.

**1. Audit devlog.md**
   - Review everything we've done since the last checkpoint or 
     session start
   - Add timestamped entries for ANY work not yet documented
   - Include decisions made, problems solved, and workarounds applied
   - Flag anything that feels incomplete or uncertain

**2. Verify all docs against current code**
   Run through every Documentation Update Trigger:
   - architecture.md — Does it reflect all current components and 
     data flow?
   - api.md — Are all endpoints documented with current signatures?
   - decisions.md — Are all non-trivial tech choices captured as ADRs?
   - stack.md — Do dependencies match what's actually installed?
   - todo.md — Is the completed/pending status accurate right now?

**3. Check for doc drift**
   Compare docs against actual code. For each file:
   - If docs match code: Confirm ✓
   - If docs are behind: Update now
   - If unclear whether docs or code are correct: Log a DOC-DRIFT 
     item in todo.md and flag for my review

**4. Update CLAUDE.md**
   - "Current Development Phase" should reflect where we actually are
   - Active work items should match reality
   - Any new conventions or warnings discovered during this session

**5. Update checkpoint.md**
   Overwrite /docs/checkpoint.md with current state so crash recovery 
   is current through this point.

**6. Checkpoint marker**
   Add this to devlog.md:
   
   ## CHECKPOINT - [TIMESTAMP]
   Docs verified against code. All entries current through this point.
   Next priorities: [list what's next]

**7. Report**
   Give me a summary:
   - What was documented or updated
   - Any DOC-DRIFT items found
   - Any gaps or concerns
   - Confirmation that all F3 docs are current

Do NOT skip any file. We are continuing after this — this is not 
session end.

Resuming after [BLOCKER_TYPE] was resolved:

1. Read the last BLOCKER entry in /docs/devlog.md
2. Confirm what was fixed and how
3. Tell me exactly where we left off before the blocker
4. Verify the fix is working (run any relevant tests)
5. Continue from the precise point before interruption

We were working on [FEATURE] when [BLOCKER] stopped us.

Connection dropped. Read /docs/checkpoint.md — it has our last saved 
state.

Then:
1. Confirm: what was the last approved component?
2. Confirm: what were we working on next?
3. Check if there's any partially completed work (files modified but 
   not yet announced/approved)
4. Read the last entry in /docs/devlog.md for additional context
5. Tell me exactly where we are and what to do next

Resume from the checkpoint. Do NOT re-read the full project — 
checkpoint.md has everything you need to continue.

STOP. You've attempted this [N] times and it's not working.

Do NOT try another approach. Instead:

1. **Roll back** to the last known good state (last checkpoint 
   or last passing commit). Undo all changes from the failed 
   attempts.

2. **Generate an Issue Review Brief** using the template in 
   @F3_TEMPLATES.md. Include:
   - The EXACT original requirement from SPEC.md
   - Each approach you tried and why it failed
   - Your honest assessment of the root cause
   - The current state of the code
   - Questions you're uncertain about

3. **Save the brief** as /docs/issue-review-brief.md

4. **Present it to me** with this message:
   "I've been unable to resolve this after [N] attempts. 
   I've generated an Issue Review Brief for outside review. 
   Please share this with a fresh advisor to get an 
   unbiased approach."

5. **WAIT** — do not attempt any more fixes until I return 
   with an approved approach from the outside review.

When I return with the approved approach:
- Implement ONLY that approach
- Verify against the ORIGINAL requirement in SPEC.md
- Document the resolution in devlog.md

Reset thrash detection — I've reviewed the situation.

1. Run: echo 0 > .claude/thrash-count
2. Read /docs/issue-review-brief.md (if it exists) for 
   context on what was tried

[CHOOSE ONE:]

OPTION A — Outside advisor provided an approach:
Here's the approved approach from the review:
[PASTE THE ADVISOR'S RECOMMENDED APPROACH HERE]
Implement ONLY this approach. Do not deviate.

OPTION B — I'm providing direction:
The issue is [DESCRIBE]. Try this approach: [YOUR DIRECTION].

OPTION C — Start fresh:
Forget all previous attempts. Re-read the original requirement 
in SPEC.md and propose a completely new approach before 
implementing anything. Show me the plan first.

I need you to rebuild your understanding of this project. Please:

1. Read CLAUDE.md for the project overview
2. Read /docs/checkpoint.md for last approved state
3. Read /docs/architecture.md for system design
4. Read the last 3 entries in /docs/devlog.md for recent context
5. Check /docs/devlog.md for any unresolved BLOCKERs
6. Check /docs/todo.md for current priorities
7. Review /docs/decisions.md for key architectural choices

Then give me a summary of:
- What this project is and does
- The current development state
- Any unresolved blockers
- What we should work on next

I want to explore a new feature idea: [FEATURE_IDEA]

Before we build anything, let's run this through F3 Foundation:

**1. Explore the idea:**
- What problem does this feature solve?
- Who benefits from it?
- What's the user story? ("As a [user], I want [feature] so that [benefit]")

**2. Check fit with existing vision:**
- Read SPEC.md - how does this align with project goals?
- Does it enhance or distract from core functionality?
- Are there any conflicts with existing features?

**3. Assess implementation impact:**
- What existing components does this touch?
- What new components would be needed?
- Any database schema changes?
- Any API changes?
- Rough complexity estimate (small/medium/large)

**4. Recommend:**
- Should we add this to the spec? (Yes/No/Defer/Modify)
- If yes, draft the SPEC.md addition
- Flag any concerns or alternatives

Don't implement anything yet—just explore and recommend.

Let's add [FEATURE_NAME] to our Foundation documents.

**1. Update SPEC.md:**
- Add feature to appropriate section (Core Features, Phase 2, etc.)
- Include user story and acceptance criteria
- Note any new constraints or requirements

**2. Create implementation plan in PLAN.md:**
- Break down into components (what needs to be built)
- Define the implementation order
- Identify dependencies on existing code
- Note any architectural decisions needed

**3. Update related docs:**
- If API changes: update api.md
- If architecture changes: update architecture.md  
- If new decisions: add ADR to decisions.md
- Add to todo.md with priority

**4. Summary:**
- Show me the additions to each file
- Confirm the implementation order
- Ask if I want to proceed to implementation

Wait for my approval before making any changes to the docs.

Let's implement [FEATURE_NAME] from PLAN.md.

Following the Build ↔ Guide cycle with explicit checkpoints:

1. Build the [FIRST_COMPONENT] (backend/frontend/database)
2. When complete, STOP and announce:
   - "I've completed [COMPONENT_NAME]"
   - Show what you built (summary, files, key functionality)
   - Ask: "Would you like to review before I continue to [NEXT]?"
3. WAIT for my review and approval
4. After I approve, proceed to next component
5. Repeat: Build → Stop → Announce → Show → Ask → Wait → Approve

**Rules:**
- Complete ONE component at a time
- ALWAYS stop and announce when done
- NEVER proceed without my explicit approval
- Show me what you created before moving on
- If I give feedback, make corrections before continuing

Begin with [FIRST_COMPONENT]. Think through the implementation 
carefully, build it, then STOP and show me what you created.

**Production Standards (required for EVERY component):**
- ☐ Logging: Key actions and errors logged with context
- ☐ Error Handling: User-friendly messages, no raw errors exposed
- ☐ Security: Input validation, parameterized queries, output escaping
- ☐ Accessibility: Semantic HTML, ARIA attributes, keyboard navigation

ultrathink: Design the [COMPLEX_FEATURE] architecture.

Consider:
- How this scales to 100k+ users
- Security implications and attack vectors
- Performance bottlenecks and optimization strategies
- Error handling and recovery
- Data consistency requirements
- Integration points with existing components

Propose a complete architecture before we start coding.

Before we implement [FEATURE], let's do a quick threat check (5 minutes):

1. **Assets:** What are we protecting? (user data, credentials, money, etc.)

2. **Actors:** Who might want to abuse this? (attackers, malicious users, bots)

3. **Attack Surface:** What inputs/endpoints are exposed? What could be manipulated?

4. **Abuse Cases:** How could this feature be misused? (spam, data scraping, 
   credential stuffing, privilege escalation, injection, etc.)

5. **Mitigations:** What protections do we need? (rate limiting, validation, 
   authorization checks, logging, monitoring, etc.)

Give me a brief assessment before we proceed to implementation.

Read @F3_FRAMEWORK.md and @F3_CORE.md, then begin the Existing 
Framework Translation for this project.

Your goal is to capture my framework's DNA across all 11 translation 
categories so you can generate accurate Foundation context files.

For EACH of the 11 categories:
1. Ask me specific questions about my conventions and patterns
2. Probe for details I might not think to mention
3. Confirm your understanding before moving to the next category
4. Note the guardrail that will be enforced for that category

The 11 categories are:
01. Tech Stack Declaration
02. Folder Structure Map
03. Naming Conventions
04. Architectural Patterns
05. Component & Module Patterns
06. Styling Rules
07. State Management Approach
08. Dependency Boundaries
09. Testing Strategy
10. Environment & Deployment Context
11. "Never Do" List

After completing all categories, generate:
1. A project-context.md file with the full framework translation
2. Recommendations for what should go into CLAUDE.md
3. A summary of all guardrails that will be enforced

Let's start with Category 01: Tech Stack Declaration.

I want to build a [TYPE] application for [TARGET USERS].

The core problem: [DESCRIBE PROBLEM]

Let's create a comprehensive SPEC.md. Ask me one question at a 
time to develop a thorough specification. Each question should 
build on my previous answers.

Start by asking about the problem and users.

Read @SPEC.md thoroughly.

Before any coding, please:

1. RESEARCH:
   - Ask clarifying questions about any unclear requirements
   - Research current best practices for [TECH_STACK]
   - Identify potential technical challenges
   - Suggest optimal tech stack choices

2. CREATE PLAN.MD:
   - Development phases (MVP → Phase 2 → Phase 3)
   - Complete file structure to create
   - Component hierarchy and relationships
   - Database schema design
   - API endpoint list with methods
   - Dependencies needed
   - Estimated complexity per feature

3. WAIT FOR APPROVAL:
   Show me the plan and wait for my approval before coding.

Start with research and clarifying questions.

Stop. That's not following our pattern in CLAUDE.md.

We use [CORRECT PATTERN] not [WHAT CLAUDE DID].

Please:
1. Read @CLAUDE.md section on [PATTERN]
2. Rewrite using the correct approach
3. Explain why this pattern is better

Before you code this, explain:
1. Your approach to solving this
2. Why this is the right approach  
3. What tradeoffs you're making
4. What could go wrong

I want to validate the approach first.

That feature isn't in SPEC.md.

Let's:
1. Add it to SPEC.md as Phase 2 if important
2. Document why in decisions.md
3. Stay focused on MVP for now

Get back to [CURRENT_FEATURE].

## Scope
- [ ] Matches SPEC/PLAN requirements
- [ ] No scope creep (extra features)

## Quality
- [ ] Tests added/updated and passing
- [ ] Code follows project conventions

## Production Standards
- [ ] Logging: Key actions + errors logged
- [ ] Errors: User-safe messages only
- [ ] Security: Inputs validated, authz checked
- [ ] Accessibility: Semantic HTML, ARIA, keyboard nav

## Documentation
- [ ] Required docs updated (see triggers)

## Verification
- [ ] Commands run + outcomes captured

1. Inputs identified: [List sources + types]
2. Validation: [Schema/approach]
3. Authorization: [Who can call? How enforced?]
4. Output handling: [Escaped if rendering]
5. Logging redaction: [No secrets/PII]
6. Abuse prevention: [Rate/size limits]

1. Semantic HTML: [Correct elements — no div-buttons]
2. ARIA attributes: [Landmarks, roles, labels applied]
3. Keyboard navigation: [Tab, Enter, Escape reachable]
4. Focus management: [Visible indicators, logical order]
5. Color contrast: [4.5:1 minimum on all text]
6. Alt text: [Meaningful alt or alt="" for decorative]

#!/usr/bin/env bash
set -euo pipefail

# F3 Restart Gate — blocks server restarts
# without checkpointing.
# Reads hook input from stdin (JSON).
# Customize RESTART_PATTERN for your stack.

# Read JSON from stdin
INPUT=$(cat)

# Extract the command from JSON
COMMAND=$(echo "$INPUT" \
  | grep -oP '"command"\s*:\s*"\K[^"]*' \
  | head -1)

RESTART_PATTERN='npm run dev|npm start|node --watch'
RESTART_PATTERN+='|flask run|uvicorn|manage\.py runserver'
RESTART_PATTERN+='|docker.*(restart|up|down)'
RESTART_PATTERN+='|kill|taskkill'

if echo "$COMMAND" | grep -qiE "$RESTART_PATTERN"; then
  if ! git diff --name-only \
       | grep -q 'docs/checkpoint.md'; then
    echo "BLOCKED: F3 Restart Gate" >&2
    echo "Update docs/checkpoint.md and" >&2
    echo "docs/devlog.md before restarting." >&2
    exit 2
  fi
fi

#!/usr/bin/env node

// F3 Universal Commit Gate v5.0.0
// Standard Git pre-commit hook — runs at `git commit` time in every editor.
// Exit 1 = Git convention (differs from Claude Code hooks which use exit 2).
// Auto-installed to .git/hooks/pre-commit by setup-f3.js.
// Manual: cp .githooks/pre-commit .git/hooks/ && chmod +x .git/hooks/pre-commit
// Bypass: git commit --no-verify

'use strict';

const { execSync } = require('child_process');
const fs = require('fs');

// Skip silently if not an F3 project
const isF3 = ['CLAUDE.md','CURSOR.md','AGENTS.md','GEMINI.md','F3_CORE.md']
  .some(f => fs.existsSync(f));
if (!isF3) process.exit(0);
if (!fs.existsSync('docs')) process.exit(0);

function getModified() {
  try {
    const staged   = execSync('git diff --cached --name-only', { encoding: 'utf8' });
    const unstaged = execSync('git diff --name-only',          { encoding: 'utf8' });
    return staged + '\n' + unstaged;
  } catch { return ''; }
}

const modified = getModified();
const REQUIRED = ['docs/checkpoint.md', 'docs/devlog.md']
  .filter(f => fs.existsSync(f));
const missing  = REQUIRED.filter(f => !modified.includes(f));

if (missing.length === 0) process.exit(0);

const SEP = '─'.repeat(50);
const msg = [
  '', 'BLOCKED: F3 Commit Gate (universal)', SEP, '',
  'Update these docs before committing:', '',
  ...missing.map(f => `  • ${f}`), '',
  'Also check Doc Update Triggers:',
  '  API endpoint changed?     →  docs/api.md',
  '  Architecture changed?     →  docs/architecture.md',
  '  Tech decision made?       →  docs/decisions.md',
  '  Dependency changed?       →  docs/stack.md', '',
  'After updating, commit again.',
  'To skip: git commit --no-verify',
  '', SEP, '',
].join('\n');

process.stderr.write(msg);
process.exit(1);

#!/usr/bin/env bash
set -euo pipefail

# F3 Commit Gate v5.0.0 — Claude Code variant
# Runs as a Claude Code PreToolUse hook when Claude attempts git commit.
# Exit 2 = Claude Code blocking convention.

INPUT=$(cat)
COMMAND=$(echo "$INPUT" \
  | grep -oP '"command"\s*:\s*"\K[^"]*' \
  | head -1)

if ! echo "$COMMAND" | grep -qiE '^git commit'; then
  exit 0
fi

MISSING=""

if ! git diff --cached --name-only | grep -q 'docs/checkpoint.md'; then
  if ! git diff --name-only | grep -q 'docs/checkpoint.md'; then
    if [ -f "docs/checkpoint.md" ]; then
      MISSING+="  • docs/checkpoint.md\n"
    fi
  fi
fi

if ! git diff --cached --name-only | grep -q 'docs/devlog.md'; then
  if ! git diff --name-only | grep -q 'docs/devlog.md'; then
    if [ -f "docs/devlog.md" ]; then
      MISSING+="  • docs/devlog.md\n"
    fi
  fi
fi

if [ -n "$MISSING" ]; then
  echo "BLOCKED: F3 Commit Gate (Claude Code)" >&2
  echo "Update before committing:" >&2
  echo -e "$MISSING" >&2
  echo "Verify Doc Update Triggers:" >&2
  echo "  API changed?          →  docs/api.md" >&2
  echo "  Architecture changed? →  docs/architecture.md" >&2
  echo "  Decision made?        →  docs/decisions.md" >&2
  echo "Confirm Production Standards:" >&2
  echo "  ☐ Logging  ☐ Error handling  ☐ Security  ☐ Accessibility" >&2
  exit 2
fi

"I understand the urgency, but implementing undocumented 
architectural changes is the #1 cause of project drift. 
Feature Discovery takes 5 minutes. The cleanup from 
skipping it takes hours.

I'll run Feature Discovery now — it's fast."

#!/usr/bin/env bash
set -euo pipefail

# F3 Thrash Detector — blocks after 3 consecutive
# failures until Issue Review Brief is generated
# OR counter is reset. Allows safe commands when
# blocked so Claude can generate the brief.

COUNT_FILE=".claude/thrash-count"
BRIEF="docs/issue-review-brief.md"
MAX_FAILURES=3

INPUT=$(cat)

EVENT=$(echo "$INPUT" \
  | grep -oP '"hook_event_name"\s*:\s*"\K[^"]*' \
  | head -1)
COMMAND=$(echo "$INPUT" \
  | grep -oP '"command"\s*:\s*"\K[^"]*' \
  | head -1)

COUNT=0
if [ -f "$COUNT_FILE" ]; then
  COUNT=$(cat "$COUNT_FILE")
fi

case "$EVENT" in
  PostToolUseFailure)
    COUNT=$((COUNT + 1))
    echo "$COUNT" > "$COUNT_FILE"
    if [ "$COUNT" -ge "$MAX_FAILURES" ]; then
      echo "WARNING: $COUNT consecutive failures." >&2
      echo "Generate an Issue Review Brief." >&2
    fi
    ;;
  PostToolUse)
    echo "0" > "$COUNT_FILE"
    ;;
  PreToolUse)
    if [ "$COUNT" -ge "$MAX_FAILURES" ]; then
      if [ -f "$BRIEF" ]; then
        AGE=$(( $(date +%s) - $(stat -c %Y "$BRIEF") ))
        if [ "$AGE" -lt 300 ]; then
          echo "0" > "$COUNT_FILE"
          exit 0
        fi
      fi
      # Allow thrash-count reset
      if echo "$COMMAND" | grep -qiE 'thrash-count'; then
        exit 0
      fi
      # Allow safe commands for brief generation
      if echo "$COMMAND" | grep -qiE \
        '^(cat|head|tail|less|more|wc|grep|find|ls|pwd)(\s|$)'; then
        exit 0
      fi
      if echo "$COMMAND" | grep -qiE '^git(\s|$)'; then
        exit 0
      fi
      if echo "$COMMAND" | grep -qiE \
        'docs/|issue-review-brief|mkdir.*docs'; then
        exit 0
      fi
      echo "BLOCKED: F3 Thrash Detection" >&2
      echo "$COUNT consecutive failures." >&2
      echo "Generate Issue Review Brief or reset:" >&2
      echo "echo 0 > .claude/thrash-count" >&2
      exit 2
    fi
    ;;
esac

**Version:** 1.3
**Last Reconciled:** 2026-04-18
**Reconciled By:** Scott Rains
**Sessions Incorporated:** a1b2c3d, e4f5g6h, i7j8k9l

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": ".claude/hooks/f3-restart-gate.sh" },
          { "type": "command",
            "command": ".claude/hooks/f3-commit-gate.sh" },
          { "type": "command",
            "command": ".claude/hooks/f3-thrash-detector.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": ".claude/hooks/f3-thrash-detector.sh" }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": ".claude/hooks/f3-thrash-detector.sh" }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          { "type": "command",
            "command": ".claude/hooks/f3-first-run-loader.sh" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command",
            "command": ".claude/hooks/f3-first-run-loader.sh" }
        ]
      }
    ]
  }
}

.claude/
├── commands/
│   └── f3/
│       ├── ss.md        # /project:f3:ss → Session Start
│       ├── es.md        # /project:f3:es → Session End
│       ├── doco.md      # /project:f3:doco → Documentation Checkpoint
│       ├── fd.md        # /project:f3:fd → Feature Discovery
│       ├── fp.md        # /project:f3:fp → Feature Planning
│       ├── fi.md        # /project:f3:fi → Feature Implementation
│       ├── fc.md        # /project:f3:fc → Feature Complete
│       ├── crash.md     # /project:f3:crash → Crash Recovery
│       ├── thrash.md    # /project:f3:thrash → Thrash Detection
│       ├── reset.md     # /project:f3:reset → Thrash Reset
│       ├── update.md    # /project:f3:update → F3 Version Update
│       ├── gr.md        # /project:f3:gr → Governance Report
│       └── audit.md     # /project:f3:audit → Discovery Audit Checklist
├── hooks/
│   ├── f3-phase-gate.sh (or .js)
│   ├── f3-restart-gate.sh (or .js)
│   ├── f3-commit-gate.sh (or .js)
│   └── f3-thrash-detector.sh (or .js)
└── settings.json

# [PROJECT NAME]

> Brief one-line description

## Quick Context
[2-3 sentences: purpose, users, value proposition]

## F3 Framework Reference

This project uses F3 (Foundation-First Framework). The framework is split 
into modular files in the project root:

| Module | Contents |
|--------|----------|
| `F3_FRAMEWORK.md` | Hub — read this first, routes to all modules |
| `F3_CORE.md` | Methodology, production standards, guardrails |
| `F3_PROMPTS.md` | All Claude Code implementation prompts |
| `F3_TEMPLATES.md` | Document templates (CLAUDE.md, SPEC, docs/*) |
| `F3_SETUP.md` | Setup guides for new & existing projects |
| `F3_CHANGELOG.md` | Version history & roadmap |

**Claude: Read @F3_FRAMEWORK.md first — it routes you to the right module.**
- Need templates? → @F3_TEMPLATES.md
- Need methodology or guardrails? → @F3_CORE.md
- Need prompts? → @F3_PROMPTS.md

**Current F3 Version:** 5.0.0

## Tech Stack
- Frontend: [React, Next.js, etc.]
- Backend: [Node.js, Python, etc.]
- Database: [PostgreSQL, MongoDB, etc.]
- Infrastructure: [AWS, Vercel, etc.]

## Architecture Overview
See /docs/architecture.md for full system design.

Key Components:
- [Component 1]: [one-line description]
- [Component 2]: [one-line description]

## Current Development Phase
Phase: [MVP, Beta, Feature Development]

Active Work:
- [ ] [Current task]
- [ ] [Next priority]

Blocked By: [None or description]

Last Session: [Date] - [Brief summary]

## Critical Conventions
Code Patterns:
- [Pattern 1]: [explanation]
- [Pattern 2]: [explanation]

Git Workflow:
- Branch naming: [convention]
- Commit format: [convention]

## Operational Guardrails

### Instruction Precedence (when sources conflict)
1. System/platform constraints → 2. CLAUDE.md → 3. SPEC.md → 4. PLAN.md → 5. /docs/*

**If code conflicts with SPEC:** Treat as bug; fix code or update SPEC with approval + ADR.

### Component Sizing
- Max: ~5 files, ~300 lines per component (only tests/** and docs/** excluded)
- Risky changes (auth, billing, migrations): Single-layer only + rollback notes required

### Definition of Done (required)
- [ ] Scope matches SPEC/PLAN
- [ ] Tests passing
- [ ] Lint passes (if configured) or TODOs logged
- [ ] Logging, errors, security implemented
- [ ] Accessibility: semantic HTML, ARIA, keyboard nav
- [ ] Docs updated

### Doc Update Triggers
API change → api.md | Architecture → architecture.md | Decision → decisions.md | Schema affecting API → api.md | Component approved → checkpoint.md (overwrite) + devlog.md (append) | **Server restart → checkpoint.md + devlog.md BEFORE restart** | **Git commit → checkpoint.md + devlog.md + all docs BEFORE commit**

### Security Gate (new endpoints)
Inputs → Validate → Authorize → Escape output → Redact logs → Rate limit

### Accessibility Gate (new UI components/pages)
Semantic HTML → ARIA attributes → Keyboard nav → Focus management → Color contrast → Alt text

### Restart Gate (HARD STOP — before ANY server restart)
**⚠️ This is NOT advisory. Violation = total context loss.**
Before ANY restart command (npm run dev, flask run, docker-compose restart, kill, etc.):
1. Overwrite /docs/checkpoint.md → 2. Append to /docs/devlog.md → 3. THEN restart

### Commit Gate (before ANY git commit)
Before running `git commit`, verify:
1. /docs/checkpoint.md is updated with current state
2. /docs/devlog.md has entries for all work since last commit
3. All Doc Update Triggers satisfied (api.md, architecture.md, decisions.md, stack.md)
**If docs are stale, update them BEFORE committing.**

## Session Protocol

### F3 Methodology Reminder

This project follows F3 (Foundation-First Framework) v5.0.0:

**Area 1: Foundation** - Spec + Plan defined upfront  
**Area 2: Implementation** - Build ↔ Guide continuous cycle  
**Area 3: Documentation** - Continuous logging for persistent context
**Production Standards** - Security, logging, error handling, accessibility, and testing in every implementation

**Critical F3 Behaviors:**
- Show me each component before moving on (Build ↔ Guide cycle)
- **After completing each component: STOP, announce completion, wait for approval**
- Never proceed to next component without explicit permission
- **REFUSE to implement changes not in PLAN.md — require Feature Discovery first, even if told "just go for it"**
- Checkpoint progress to /docs/checkpoint.md after every approval
- **BEFORE any server restart: overwrite checkpoint.md + append to devlog.md FIRST (Restart Gate)**
- Document blockers immediately when they occur
- Never assume - always ask for approval before major changes
- **After 2-3 failed attempts at the same problem: STOP trying. Generate an Issue Review Brief for outside review.**
- **Before any git commit: verify checkpoint.md, devlog.md, and all Doc Update Triggers are current**
- **Include logging, error handling, security, and accessibility in EVERY component**

**⚠️ CRITICAL:** If a requested change is NOT in PLAN.md, do NOT implement it.
**REFUSE to proceed.** Say: "I cannot implement this — it's not in PLAN.md. We need to run Feature Discovery and update the plan first. This is an F3 requirement, not a suggestion."

### Pre-Implementation Checkpoint

**Before starting ANY significant work, verify:**

1. ☐ Is this feature/change in SPEC.md?
2. ☐ Is there an implementation plan in PLAN.md?
3. ☐ If NO to either: **REFUSE to proceed.** Run Feature Discovery Prompt first. Do NOT accept "just go for it" — undocumented architectural changes break the project for every future session.

**Before completing ANY component, verify Production Standards:**

4. ☐ Logging implemented for key actions and errors?
5. ☐ Error handling with user-friendly messages?
6. ☐ Security considerations addressed (input validation, auth, etc.)?
7. ☐ Accessibility: semantic HTML, ARIA attributes, keyboard navigation?

**Triggers for this checkpoint:**
- "Significant restructure" or "major refactor"
- Multi-file changes
- New components or features
- Architecture changes
- Anything described as "comprehensive" or "major"

**If you catch yourself about to implement without spec/plan:**
STOP → REFUSE: "I cannot proceed without updating PLAN.md first."

### Build ↔ Guide Cycle Protocol

**After completing EVERY component, you MUST:**

1. **STOP** - Do not continue to the next component
2. **ANNOUNCE:** "I've completed [COMPONENT_NAME]"
3. **SHOW:** Summary of what was built (files created/modified, key functionality)
4. **ASK:** "Would you like to review this before I continue to [NEXT_COMPONENT]?"
5. **WAIT:** Do not proceed until I give explicit approval
6. **CHECKPOINT:** After approval, overwrite /docs/checkpoint.md and append to /docs/devlog.md before starting the next component

## Important Warnings
⚠️ Never edit files in /legacy or /vendor
⚠️ Always run tests before committing
⚠️ Checkpoint to /docs/checkpoint.md after every approval — crashes lose context
⚠️ **NEVER restart a server without updating checkpoint.md + devlog.md FIRST**

## Documentation Map
| Document | Purpose |
|----------|---------|
| /docs/architecture.md | System design |
| /docs/decisions.md | ADRs, rationale |
| /docs/stack.md | Tech choices |
| /docs/api.md | Endpoints |
| /docs/checkpoint.md | Last approved state (crash recovery) |
| /docs/devlog.md | Session history |
| /docs/todo.md | Tasks |
| /docs/changelog.md | Releases |

## Session Start Checklist
1. Read this file (automatic)
2. Read /docs/checkpoint.md for last approved state and next task
3. Check /docs/todo.md for priorities
4. Review last /docs/devlog.md entry (including BLOCKERs)
5. Verify no unexpected shutdowns left incomplete work

## Session End Protocol
Before closing:
1. Summarize accomplishments and append to /docs/devlog.md
2. Overwrite /docs/checkpoint.md with final session state
3. Update "Current Development Phase" above
4. Update /docs/todo.md with completed/new items
5. Document any decisions in /docs/decisions.md

# Project Specification

## Vision Statement
[One paragraph: What is this application and why does it exist?]

## Problem & Solution
- **Problem:** What pain point does this solve?
- **Target Users:** Who are they?
- **Solution:** How does this solve their problem?

## Core Features (MVP)
1. **[Feature Name]**
   - User Story: As a [user], I want to [action] so that [benefit]
   - Acceptance Criteria:
     * [Criterion 1]
     * [Criterion 2]
   - Priority: [High/Medium/Low]

2. **[Feature Name]**
   - User Story: ...
   - Acceptance Criteria: ...
   - Priority: ...

## User Flows
### Primary Flow: [Name]
1. User [action]
2. System [response]
3. User [action]
4. Result: [outcome]

## Success Metrics
- User engagement: [How measured]
- Performance: [LCP < 2.5s, etc.]
- Business: [Revenue, conversions, etc.]

## Technical Constraints
- Budget: [Limitations]
- Performance requirements: [Specific targets]
- Security requirements: [Authentication, compliance]
- Accessibility: [WCAG level]

## Out of Scope (v1)
- [Features explicitly NOT in MVP]
- [Features for later phases]

## Design Requirements
- Mobile-first responsive design
- Color scheme: [Colors]
- Accessibility: WCAG 2.1 AA compliance (see Accessibility Requirements below)

## Accessibility Requirements
- [ ] Semantic HTML for all UI components (no div-buttons)
- [ ] ARIA landmark roles on all page regions
- [ ] ARIA attributes on interactive widgets (menus, modals, tabs, accordions)
- [ ] Keyboard navigation: all features accessible without a mouse
- [ ] Visible focus indicators on all interactive elements
- [ ] Color contrast: 4.5:1 minimum (normal text), 3:1 (large text)
- [ ] Alt text on all informational images
- [ ] Form labels, error messages, and required field indicators
- [ ] Skip navigation link on pages with repeated nav
- [ ] Dynamic content announced via aria-live regions
- [ ] Target compliance level: [WCAG 2.1 AA / WCAG 2.2 AA / Section 508]
- [ ] Testing approach: [Manual screen reader testing / axe-core / Lighthouse / pa11y]

# Implementation Plan

## Phase 1: Foundation (Week 1-2)
- [ ] Project initialization and configuration
- [ ] Database schema setup
- [ ] Authentication system
- [ ] Basic UI framework

## Phase 2: Core Features (Week 3-4)
- [ ] Feature 1: [Name]
  - [ ] Backend API endpoints
  - [ ] Frontend components
  - [ ] Integration tests

## Phase 3: Polish (Week 5-6)
- [ ] Performance optimization
- [ ] Accessibility audit
- [ ] Security review

## Database Schema
[Schema definitions]

## API Endpoints
| Method | Endpoint | Purpose | Priority |
|--------|----------|---------|----------|
| POST | /api/auth/login | User login | High |

## Component Hierarchy
[Component tree structure]

## Dependencies
- Production: [list]
- Development: [list]