┌─────────────────────────────────────────────────────────────────┐
│                    SPEC-DRIVEN DEV LOOP                         │
│                                                                 │
│  ┌──────────┐     ┌──────────┐     ┌──────────────────────┐    │
│  │   PRD    │────▶│   RFC    │────▶│     Cycle Doc        │    │
│  │ (PM)     │     │ (Eng)    │     │ (Eng + AI)           │    │
│  │          │     │          │     │                      │    │
│  │ WHAT &   │     │ HOW &    │     │ IMPLEMENTATION PLAN  │    │
│  │ WHY      │     │ WHY NOT  │     │ + GH PROJECT ITEMS   │    │
│  └──────────┘     └──────────┘     └──────────────────────┘    │
│       │                │                      │                 │
│       │                │                      ▼                 │
│       │                │           ┌──────────────────────┐     │
│       │                │           │   Claude Code        │     │
│       │                │           │   reads PRD + RFC    │     │
│       │                │           │   + Cycle as native  │     │
│       │                │           │   MDX files in repo  │     │
│       │                │           └──────────────────────┘     │
│       │                │                      │                 │
│       │                │                      │ code changes    │
│       │                │                      ▼                 │
│  ┌─────────────────────────────────────────────────────┐       │
│  │              Mintlify (AI-Native Layer)              │       │
│  │  - Web editor for PMs (MDX, bi-directional sync)    │       │
│  │  - Autopilot: detects code→spec drift, opens PRs    │       │
│  │  - AGENTS.md: customize AI agent behavior           │       │
│  │  - Auto-generated MCP server for AI consumption     │       │
│  │  - llms.txt + llms-full.txt for AI indexing         │       │
│  │  - AI traffic analytics (which agents read specs)   │       │
│  └─────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────┘

PRD-007 (Feature: Smart Scheduling)
  └── RFC-003 (Calendar API Architecture)
  └── Cycle 215 (Implement Smart Scheduling)
        ├── GH Project Item: flux#89 (backend)
        ├── GH Project Item: flux#90 (frontend)
        └── PR #92 → links to Cycle 215
              └── Mintlify Autopilot detects PR #92 changes
                   └── Opens PR #93 updating PRD-007 acceptance criteria

docs/
├── docs.json                  # Mintlify configuration (navigation, theme, settings)
├── index.md                   # Landing page (overview of spec process)
│
├── PRDs/                      # Product Requirements Documents
│   ├── README.md              # PRD process guide + index
│   ├── _template.mdx          # PRD template
│   ├── PRD-001-example.mdx    # Example PRD (reference)
│   └── ...                    # Future PRDs
│
├── RFCs/                      # Requests for Comments
│   ├── README.md              # RFC process guide + index
│   ├── _template.mdx          # RFC template
│   ├── RFC-001-example.mdx    # Example RFC (reference)
│   └── ...                    # Future RFCs
│
├── adr/                       # Architecture Decision Records (existing)
│   └── 2026-03-28-job-distribution-strategy.md
│
├── guides/                    # Operational guides (existing)
│   └── dev-workstation-setup.md
│
└── roadmap/                   # Roadmap and cycles (existing)
    ├── roadmap-overview.md
    ├── canonical-strategy.md
    └── cycles/
        ├── _template.md       # Cycle doc template (NEW)
        └── ...

{
  "$schema": "https://mintlify.com/docs.json",
  "theme": "mint",
  "name": "Flux Specs",
  "description": "Spec-driven development artifacts for Flux, an AI-native hiring platform",
  "colors": {
    "primary": "#6366f1",
    "light": "#818cf8",
    "dark": "#4f46e5"
  },
  "favicon": "/favicon.svg",
  "logo": {
    "light": "/logo/light.svg",
    "dark": "/logo/dark.svg"
  },
  "appearance": {
    "default": "dark"
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Overview",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["index"]
          },
          {
            "group": "Roadmap",
            "pages": [
              "roadmap/roadmap-overview",
              "roadmap/canonical-strategy"
            ]
          }
        ]
      },
      {
        "tab": "PRDs",
        "groups": [
          {
            "group": "Product Requirements",
            "pages": [
              "PRDs/README",
              "PRDs/_template"
            ]
          }
        ]
      },
      {
        "tab": "RFCs",
        "groups": [
          {
            "group": "Technical RFCs",
            "pages": [
              "RFCs/README",
              "RFCs/_template"
            ]
          }
        ]
      },
      {
        "tab": "Cycles",
        "groups": [
          {
            "group": "Implementation Cycles",
            "pages": [
              "roadmap/cycles/cycle214-spec-driven-dev"
            ]
          }
        ]
      }
    ],
    "global": {
      "anchors": [
        {
          "anchor": "GitHub",
          "href": "https://github.com/employ-inc/flux",
          "icon": "github"
        }
      ]
    }
  },
  "contextual": {
    "options": ["copy", "view", "claude", "cursor", "mcp"]
  },
  "feedback": {
    "thumbsRating": true,
    "suggestEdit": true,
    "raiseIssue": true
  }
}

# Flux Specs — AI Agent Instructions

## Context
This documentation site contains the spec-driven development artifacts for Flux,
an AI-native hiring platform built by Employ Inc.

## Document Types
- **PRDs** (docs/PRDs/): Product Requirements Documents — functional specs owned by PMs
- **RFCs** (docs/RFCs/): Requests for Comments — non-functional/architectural specs owned by engineers
- **Cycles** (docs/roadmap/cycles/): Implementation plans referencing PRDs and RFCs

## For AI Coding Agents (Claude Code, Cursor, etc.)
When implementing a Cycle:
1. Read the Cycle doc first for the implementation plan
2. Read all referenced PRDs for functional requirements and acceptance criteria
3. Read all referenced RFCs for architectural constraints
4. Implement against the spec — do not assume requirements not stated in the PRD
5. If implementation must diverge from spec, flag it — spec drift is a bug

## For Mintlify Autopilot
When detecting code changes:
- Check if changes affect acceptance criteria in any PRD
- Check if changes introduce new patterns not covered by an RFC
- Suggest doc updates via PR, do not auto-merge

## Traceability
Every Cycle doc has `source_prds` and `source_rfcs` in frontmatter.
Every PR description should reference its Cycle number.

---
title: "PRD-XXX: [Title]"
description: "[One-line description for navigation and AI indexing]"
prd: "PRD-XXX"
status: "draft"
priority: "medium"
created: ""
updated: ""
author: ""
stakeholders: []
target_cycle: null
rfcs: []
tags: []
---

# PRD-XXX: [Title]

## Problem Statement
{/* 2-3 sentences. What problem does this solve? Who has this problem? Why now? */}

## Success Criteria
{/* Measurable outcomes. How do we know this worked? */}
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## User Stories

### Story 1: [Persona] — [Goal]
**As a** [persona], **I want** [capability], **so that** [benefit].

**Acceptance Criteria**:
- [ ] Given [context], when [action], then [outcome]
- [ ] Given [context], when [action], then [outcome]

### Story 2: [Persona] — [Goal]
...

## Functional Requirements

### FR-1: [Requirement Name]
**Description**: [What the system must do]
**Priority**: Must-have | Should-have | Nice-to-have
**Acceptance Criteria**:
- [ ] [Testable criterion]

### FR-2: [Requirement Name]
...

## UX Requirements
{/* Wireframes, flows, or descriptions of the user experience.
    Mintlify supports embedded images, Figma embeds, and interactive components. */}

## Out of Scope
{/* Explicit list of what this PRD does NOT cover. Prevents scope creep. */}

## Open Questions
| # | Question | Owner | Target Date | Resolution |
|---|----------|-------|-------------|------------|
| 1 | | | | |

## Dependencies
{/* External dependencies, other PRDs, or prerequisites */}

## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| | | | |

---
*This PRD follows the Flux spec-driven development process. See [PRD Process](/PRDs/README).*

---
title: "RFC-XXX: [Title]"
description: "[One-line description for navigation and AI indexing]"
rfc: "RFC-XXX"
status: "draft"
created: ""
updated: ""
author: ""
reviewers: []
related_prds: []
related_cycles: []
supersedes: null
superseded_by: null
tags: []
---

# RFC-XXX: [Title]

## Summary
{/* 2-3 sentences. What is this RFC proposing and why? */}

## Motivation
{/* Why is this change needed? What problem does it solve?
    Link to the PRD(s) that drive this if applicable. */}

## Detailed Design

### Architecture
{/* Technical architecture. Diagrams encouraged (Mermaid or embedded images). */}

### Data Model
{/* Schema changes, new tables, field additions. */}

### API Changes
{/* New or modified endpoints, request/response shapes. */}

### Security Considerations
{/* Authentication, authorization, data privacy implications. */}

### Performance Considerations
{/* Latency targets, throughput requirements, scalability. */}

## Alternatives Considered
| Alternative | Pros | Cons | Why Rejected |
|-------------|------|------|-------------|
| | | | |

## Migration Strategy
{/* How do we get from current state to proposed state?
    Breaking changes? Backwards compatibility? */}

## Validation Plan
- [ ] [Test or validation step]

## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| | | | |

## Open Questions
| # | Question | Owner | Target Date | Resolution |
|---|----------|-------|-------------|------------|
| 1 | | | | |

## Decision
{/* Filled in after review. What was decided? By whom? When? */}

---
*This RFC follows the Flux spec-driven development process. See [RFC Process](/RFCs/README).*

---
cycle: null
title: ""
status: draft  # draft | plan-reviewed | ready | in-progress | complete
priority: medium  # critical | high | medium | low
created: ""
updated: ""
started: null
completed: null
owner: ""
wave: null
dependencies: []
absorbs: []
source_prds: []  # PRD numbers this cycle implements
source_rfcs: []  # RFC numbers this cycle implements
related_ADRs: []
related_PRs: []
gh_project_items: []  # GitHub Project item numbers
tags: []
hidden: false
---

# Cycle [N]: [Title]

**Priority**: [LEVEL]
**Status**: [STATUS]
**Wave**: [N]
**Owner**: [@handle]
**Dependencies**: [Cycle N (description)]
**Source PRDs**: [PRD-XXX, PRD-YYY]
**Source RFCs**: [RFC-XXX]
**Product**: Flux — AI-native hiring platform
**Organization**: Employ Inc. (`employ-inc` GitHub org)

---

## Overview
<!-- 1 paragraph: What does this cycle deliver? Why now?
     Reference the source PRDs/RFCs for context. -->

## Current State
<!-- What exists today? What's working? What's broken or missing? -->

## Architecture
<!-- Technical design. Diagrams, flow charts, component relationships. -->

## Implementation Plan
<!-- Phase-by-phase breakdown. File-level detail where appropriate.
     Each phase maps to one or more GitHub Project items. -->

### Phase 1: [Name]
**GH Project Item**: flux#[N]
<!-- Detailed implementation steps -->

### Phase 2: [Name]
**GH Project Item**: flux#[N]
<!-- Detailed implementation steps -->

## Validation Plan
<!-- How do we know this works? Specific test scenarios. -->
- [ ] [Scenario 1]
- [ ] [Scenario 2]

## Estimated Scope
| Dimension | Estimate |
|-----------|----------|
| Files touched | |
| Risk level | |
| Effort | |

## Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| | | | |

## Out of Scope
<!-- What this cycle explicitly does NOT do. -->

---
*This cycle implements [PRD-XXX](../../PRDs/PRD-XXX.mdx). See [Roadmap Overview](../roadmap-overview.md).*

claude mcp add --transport http flux-specs https://specs.flux.employinc.io/mcp

{
  "mcpServers": {
    "flux-specs": {
      "type": "http",
      "url": "https://specs.flux.employinc.io/mcp"
    }
  }
}

Step 1: PM identifies need
    └── PM creates PRD in Mintlify web editor (or MDX in repo)
         └── Mintlify syncs PRD-XXX.mdx to docs/PRDs/ in GitHub

Step 2: Engineering review
    └── Engineer reads PRD (in Mintlify or as MDX file in repo)
    └── If architectural decisions needed → writes RFC-XXX.mdx
    └── RFC reviewed via GitHub PR, accepted/rejected

Step 3: Cycle planning
    └── Engineer creates Cycle doc referencing PRD + RFC in frontmatter
    └── Cycle doc includes implementation plan, file index, validation criteria
    └── GitHub Project items created for each phase

Step 4: Implementation
    └── Claude Code reads PRD + RFC + Cycle doc as native MDX/MD files
    └── Implements against spec
    └── PRs reference Cycle number in description

Step 5: Spec drift detection (AUTOMATED)
    └── Mintlify Autopilot detects code changes in PR
    └── Cross-references against PRD acceptance criteria
    └── Opens follow-up PR with suggested spec updates if drift detected

Step 6: Validation
    └── Engineer runs validation plan from Cycle doc
    └── PM verifies acceptance criteria from PRD
    └── Cycle marked complete, PRD marked completed

Step 7: Spec maintenance
    └── Completed PRDs/RFCs remain as historical record
    └── "Spec drift" is a bug — Autopilot catches it automatically

### Spec-Driven Development

Every feature follows the PRD → RFC → Cycle pipeline:
- **PRDs** (`docs/PRDs/`): Functional requirements. PM-owned. Read before implementing any feature.
- **RFCs** (`docs/RFCs/`): Non-functional requirements. Engineering-owned.
- **Cycles** (`docs/roadmap/cycles/`): Implementation specs. Always reference source PRDs/RFCs.

Before starting any Cycle implementation:
1. Read the Cycle doc
2. Read all referenced PRDs (for functional requirements and acceptance criteria)
3. Read all referenced RFCs (for architectural constraints)
4. Implement against the spec, not against assumptions
5. If implementation must diverge from spec, flag it — spec drift is a bug