F3: Foundation-First Framework

your-project/
├── F3_FRAMEWORK.md      # F3 reference (you add this)
├── SPEC.md              # Project requirements
├── PLAN.md              # Architecture & implementation plan
├── CLAUDE.md            # Session bootstrap (Claude reads first)
├── docs/
│   ├── architecture.md  # System design
│   ├── api.md           # API contracts
│   ├── stack.md         # Tech stack details
│   ├── decisions.md     # Architecture Decision Records
│   ├── devlog.md        # Session logs
│   ├── todo.md          # Task tracking
│   └── changelog.md     # Release history
└── [your code here]     # Organize however you want

Analyze this codebase and give me an overview:
1. What is this application and what does it do?
2. What tech stack is being used?
3. What's the file/folder structure?
4. Are there any existing docs I should know about?
5. What state is the project in (MVP, production, etc.)?

Based on your analysis of this codebase, create a SPEC.md that 
documents:

1. What this application does (reverse-engineer the vision)
2. The problems it solves and who it's for
3. Core features that exist today
4. Any features that appear partially implemented
5. Technical constraints you can observe

This is retroactive documentation - we're capturing what IS, 
not what we planned to build.

Create a PLAN.md that documents the current implementation:

1. The architecture as it exists today
2. Database schema (from migrations or schema files)
3. API endpoints that exist
4. Component hierarchy
5. Dependencies in use

Mark any areas that seem incomplete or inconsistent.

Read @F3_FRAMEWORK.md and set up the F3 documentation system.

Using the templates in F3_FRAMEWORK.md, create:

1. CLAUDE.md in the project root
   - Use the CLAUDE.md template
   - Fill in project name, tech stack, current phase
   - Keep all F3 standard sections (Session Protocol, etc.)

2. /docs directory with:
   - architecture.md (system design)
   - api.md (API contracts, if applicable)
   - stack.md (tech stack details)
   - decisions.md (Architecture Decision Records)
   - devlog.md (session logs)
   - todo.md (task tracking)
   - changelog.md (release history)

Pull information from SPEC.md and PLAN.md to populate these files.
Mark anything needing my input with [TODO: ...]

Read @F3_FRAMEWORK.md and upgrade this project's CLAUDE.md to the 
latest F3 version.

**Update these sections:**
1. F3 Framework Reference - update version number
2. F3 Methodology Reminder - replace with latest version
3. Pre-Implementation Checkpoint - add if missing, update if exists
4. Build ↔ Guide Cycle Protocol - update if changed
5. Any new sections added since this project was created

**Process:**
1. Show me the current F3 version in this project's CLAUDE.md
2. Show me what sections need updating
3. Show me the proposed changes (diff-style)
4. Wait for my approval before making changes

Do NOT change project-specific content (Quick Context, Tech Stack, 
Current Development Phase, Critical Conventions, etc.) - only update 
F3 framework sections.

Let's start a new session. Please:

1. Read CLAUDE.md for project context
2. Check /docs/devlog.md for the last session summary
3. Review /docs/todo.md for current priorities
4. Check for any unresolved BLOCKERs in devlog.md
5. Give me a brief status: what we were working on, what's next, 
   and any blockers

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

Let's wrap up this session. Please:

1. Summarize what we accomplished today with timestamps
2. Note any decisions we made
3. List any blockers or issues encountered (Hard Stops vs Soft Issues)
4. Identify priorities for next session

Then:
- Append a new entry to /docs/devlog.md with this summary
- Update the "Current Development Phase" section in CLAUDE.md
- Update /docs/todo.md to reflect completed and new tasks
- If we made any architectural decisions, add them to /docs/decisions.md

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.

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.

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

1. Read CLAUDE.md for the project overview
2. Read /docs/architecture.md for system design
3. Read the last 3 entries in /docs/devlog.md for recent context
4. Check /docs/devlog.md for any unresolved BLOCKERs
5. Check /docs/todo.md for current priorities
6. 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.

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.

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

## 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]

# [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 complete framework 
documentation is in the project root: `F3_FRAMEWORK.md`

**Claude: Read @F3_FRAMEWORK.md when you need:**
- Complete templates for any F3 document
- Detailed methodology explanations
- Implementation prompts and examples
- Troubleshooting guidance

**Current F3 Version:** 2.3.2

## 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
- [ ] Docs updated

### Doc Update Triggers
API change → api.md | Architecture → architecture.md | Decision → decisions.md | Schema affecting API → api.md

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

## Session Protocol

### F3 Methodology Reminder

This project follows F3 (Foundation-First Framework) v2.3.2:

**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 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
- Checkpoint progress to devlog.md after every component completion
- Document blockers immediately when they occur
- Never assume - always ask for approval before major changes
- **Include logging, error handling, and security in EVERY component**

**⚠️ CRITICAL:** If a requested change is NOT in PLAN.md, do NOT implement it.
Stop and ask: "This isn't in our plan yet. Should we run Feature Discovery first?"

### 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: **STOP** and use Feature Discovery Prompt first

**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.)?

**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 → Acknowledge the gap → Ask: "Should we run this through F3 Foundation 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

## Important Warnings
⚠️ Never edit files in /legacy or /vendor
⚠️ Always run tests before committing
⚠️ Checkpoint progress after completing each component

## Documentation Map
| Document | Purpose |
|----------|---------|
| /docs/architecture.md | System design |
| /docs/decisions.md | ADRs, rationale |
| /docs/stack.md | Tech choices |
| /docs/api.md | Endpoints |
| /docs/devlog.md | Session history |
| /docs/todo.md | Tasks |
| /docs/changelog.md | Releases |

## Session Start Checklist
1. Read this file (automatic)
2. Check /docs/todo.md for priorities
3. Review last /docs/devlog.md entry (including BLOCKERs)

## Session End Protocol
Before closing:
1. Summarize accomplishments and append to /docs/devlog.md
2. Update "Current Development Phase" above
3. Update /docs/todo.md with completed/new items
4. 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

# 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]