# Specs Folder Reorganization Plan

This plan reorganizes the specs/ directory into categorized folders (100-Infrastructures, 200-fullstacks, 300-others) with consistent numeric naming conventions, and updates AGENTS.md to document the new structure.

## Current State
- `specs/001-transmittals-circulation/` - Fullstack feature (plan.md, spec.md, tasks.md, test-report.md)
- `specs/002-infra-ops/` - Infrastructure work (plan.md, spec.md, quickstart.md, research.md, data-model.md, checklists/, contracts/)
- `specs/003-unified-workflow-engine/` - Fullstack core system (plan.md, spec.md, tasks.md, quickstart.md, research.md, data-model.md, checklists/, contracts/)
- Core specs folders (00-overview, 01-requirements, etc.) - Remain unchanged

## Target Structure
```
specs/
├── 00-overview/ (unchanged)
├── 01-requirements/ (unchanged)
├── 02-architecture/ (unchanged)
├── 03-Data-and-Storage/ (unchanged)
├── 04-Infrastructure-OPS/ (unchanged)
├── 05-Engineering-Guidelines/ (unchanged)
├── 06-Decision-Records/ (unchanged)
├── 08-Tasks/ (unchanged)
├── 88-logs/ (unchanged)
├── 99-archives/ (unchanged)
├── 100-Infrastructures/          # NEW: Infrastructure-related work
│   ├── 102-infra-ops/           # Moved from 002-infra-ops
│   └── README.md                # NEW: Category guide
├── 200-fullstacks/              # NEW: Backend + frontend features
│   ├── 201-transmittals-circulation/  # Moved from 001-transmittals-circulation
│   ├── 203-unified-workflow-engine/   # Moved from 003-unified-workflow-engine
│   └── README.md                # NEW: Category guide
└── 300-others/                  # NEW: Documentation, research, non-code tasks
    └── README.md                # NEW: Category guide
```

## Naming Convention
- Prefix: `nXX` where `n` = hundreds digit of category folder
- Example: `100-Infrastructures/102-infra-ops` (n=1, so 1xx)
- Example: `200-fullstacks/201-transmittals-circulation` (n=2, so 2xx)

## Steps

### 1. Create new category folders
- Create `specs/100-Infrastructures/`
- Create `specs/200-fullstacks/`
- Create `specs/300-others/`

### 2. Move existing folders with new names
- Move `specs/001-transmittals-circulation/` → `specs/200-fullstacks/201-transmittals-circulation/`
- Move `specs/002-infra-ops/` → `specs/100-Infrastructures/102-infra-ops/`
- Move `specs/003-unified-workflow-engine/` → `specs/200-fullstacks/203-unified-workflow-engine/`

### 3. Create README.md files for each category
- `specs/100-Infrastructures/README.md` - Explain infrastructure work scope
- `specs/200-fullstacks/README.md` - Explain fullstack feature scope
- `specs/300-others/README.md` - Explain documentation/research scope

### 4. Update AGENTS.md
- Add new section: "📁 Specs Folder Organization"
- Document the new category structure
- Explain naming convention (nXX prefix)
- Provide examples of what goes in each category
- Add rule: "When creating new feature specs, place in appropriate category folder"

### 5. Update specs/README.md
- Add reference to new category folders
- Update directory structure diagram
- Note that core specs (00-06, 08, 88, 99) remain unchanged

### 6. Create workflow (optional - pending user confirmation)
- Create `.windsurf/workflows/create-feature-spec.md`
- Workflow prompts user for feature type (infra/fullstack/other)
- Automatically places spec in correct category with proper naming

## Verification
- Verify all files moved correctly (no data loss)
- Verify internal file references still work (check for relative paths)
- Verify AGENTS.md documentation is clear
- Test that new structure is intuitive for team

## Files Modified
- `specs/100-Infrastructures/` (NEW)
- `specs/200-fullstacks/` (NEW)
- `specs/300-others/` (NEW)
- `specs/100-Infrastructures/README.md` (NEW)
- `specs/200-fullstacks/README.md` (NEW)
- `specs/300-others/README.md` (NEW)
- `AGENTS.md` (UPDATED - add Specs Folder Organization section)
- `specs/README.md` (UPDATED - add new categories to directory structure)

## Files Moved
- `specs/001-transmittals-circulation/` → `specs/200-fullstacks/201-transmittals-circulation/`
- `specs/002-infra-ops/` → `specs/100-Infrastructures/102-infra-ops/`
- `specs/003-unified-workflow-engine/` → `specs/200-fullstacks/203-unified-workflow-engine/`