# How SF Organizes Work

SF uses a three-level hierarchy to break projects into manageable pieces that an AI can execute reliably.

## The Hierarchy

```
Milestone  →  a shippable version (4-10 slices)
  Slice    →  one demoable vertical feature (1-7 tasks)
    Task   →  one context-window-sized unit of work
```

### Milestones

A milestone is a shippable version of your project — an MVP, a major release, or a feature set that delivers standalone value. Milestones typically contain 4-10 slices.

Examples:
- "MVP with user auth, dashboard, and settings"
- "v2.0 with real-time collaboration and API v2"
- "Security hardening milestone"

### Slices

A slice is one demoable, vertical capability within a milestone. It cuts across layers (database, backend, frontend) to deliver something you could show to a user. Slices contain 1-7 tasks.

Examples:
- "User authentication with JWT"
- "Dashboard layout with charts"
- "API rate limiting"

### Tasks

A task is the smallest unit of work — something that fits in one AI context window. If a task can't be completed in a single AI session, it's broken into smaller tasks.

Examples:
- "Create the User model and migration"
- "Implement JWT middleware"
- "Build the login form component"

## The `.sf/` Directory

All project state lives on disk in a `.sf/` directory at your project root:

```
.sf/
  PROJECT.md          — living description of what the project is
  REQUIREMENTS.md     — requirement contract (active/validated/deferred)
  DECISIONS.md        — append-only architectural decisions log
  KNOWLEDGE.md        — cross-session rules, patterns, and lessons
  RUNTIME.md          — runtime context: API endpoints, env vars, services
  STATE.md            — quick-glance status of current work
  PREFERENCES.md      — project-level preferences (optional)
  milestones/
    M001/
      M001-ROADMAP.md — slice plan with risk levels and dependencies
      M001-CONTEXT.md — scope and goals from discussion phase
      slices/
        S01/
          S01-PLAN.md     — task decomposition for this slice
          S01-SUMMARY.md  — what was built and what changed
          S01-UAT.md      — human test script
          tasks/
            T01-PLAN.md   — detailed plan for this task
            T01-SUMMARY.md — what the task accomplished
```

### Key Files

| File | Purpose |
|------|---------|
| `PROJECT.md` | High-level project description, updated as the project evolves |
| `REQUIREMENTS.md` | Formal requirement contract — tracks what's active, validated, and deferred |
| `DECISIONS.md` | Append-only log of architectural decisions with rationale |
| `KNOWLEDGE.md` | Rules, patterns, and lessons learned across sessions — SF reads this at the start of every task |
| `RUNTIME.md` | Runtime context like API URLs, ports, and environment variables |
| `STATE.md` | Current status at a glance — auto-generated, don't edit manually |

## How Work Flows

Each slice flows through phases:

```
Plan → Execute (per task) → Complete → Reassess Roadmap → Next Slice
```

1. **Plan** — SF scouts the codebase, researches relevant docs, and decomposes the slice into tasks with clear requirements
2. **Execute** — Each task runs in a fresh AI session with focused context
3. **Complete** — SF writes summaries, generates a UAT script, and commits
4. **Reassess** — The roadmap is checked against reality — slices may be reordered, added, or removed
5. **Next Slice** — The loop continues until all slices are done

After all slices complete, a **milestone validation** gate checks that success criteria were actually met before sealing the milestone.

## Adding Knowledge

SF maintains a knowledge base that persists across sessions. Add rules, patterns, or lessons:

```
/sf knowledge rule "Always use parameterized queries for database access"
/sf knowledge pattern "Service classes go in src/services/"
/sf knowledge lesson "The OAuth flow requires the redirect URL to match exactly"
```

This knowledge is injected into every task prompt automatically.