94 lines
4.3 KiB
Markdown
94 lines
4.3 KiB
Markdown
# 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/`
|