SPEC.md   ← What + Why + Acceptance criteria
PLAN.md   ← How + Which files + Side effects
TASKS.md  ← Atomic checkboxes
[code]    ← Implementation
REVIEW.md ← Post-check vs SPEC

1. SPECIFY  → เขียน SPEC.md (what + why + acceptance)
2. CLARIFY  → ถามคำถามจน ambiguity หมด (แก้ SPEC จนชัด)
3. PLAN     → เขียน PLAN.md (how + which files + risks)
4. TASKS    → แตกเป็น TASKS.md (atomic checkboxes)
5. ANALYZE  → ตรวจ conflict กับ Codex / pattern เดิม
6. IMPLEMENT → เขียนโค้ด (Work phase)
7. REVIEW   → เขียน REVIEW.md (check vs SPEC)

features/
  XYZ-add-baby-photo/
    SPEC.md       ← required
    PLAN.md       ← optional, ถ้า touch หลายไฟล์
    TASKS.md      ← required
    REVIEW.md     ← optional, ถ้า feature สำคัญ

# SPEC: [Feature Name]
 
**ID:** XYZ-001
**Status:** Draft | Clarified | Approved | Implemented | Archived
**Owner:** [name]
**Created:** YYYY-MM-DD
**Last updated:** YYYY-MM-DD
 
## What
[ประโยคเดียว — ทำอะไร]
 
## Why
[ปัญหาที่แก้ + ผู้ได้ประโยชน์]
 
## Out of Scope
[สิ่งที่ feature นี้จะ "ไม่" ทำ — สำคัญพอๆ กับ what]
 
## User Story
As a [role]
I want to [action]
So that [benefit]
 
## Acceptance Criteria (GIVEN/WHEN/THEN)
 
### Scenario 1: Happy path
GIVEN [precondition]
WHEN [user action]
THEN [expected result]
AND [additional check]
 
### Scenario 2: Error case
GIVEN [precondition]
WHEN [user action with error condition]
THEN [expected error handling]
 
### Scenario 3: Edge case
GIVEN [edge precondition]
WHEN [action]
THEN [expected behavior]
 
## Non-functional Requirements
-Performance: [response time, throughput]
-Security: [auth, data protection]
-Privacy: [PDPA compliance if applicable]
-Accessibility: [WCAG level if applicable]
 
## Dependencies
-Other features: [feature IDs]
-External services: [APIs, libraries]
-Data: [schema changes, migrations]
 
## Open Questions
-[ ] Question 1?
-[ ] Question 2?
 
## References
-Codex patterns: P-XX, P-YY
-Related skills: skill-name
-Design: [link]

# PLAN: [Feature Name]
 
**Spec:** [link to SPEC.md]
**Status:** Draft | Approved | In Progress | Done
 
## Architecture Decision
 
[1-2 ย่อหน้า — approach ที่จะใช้ + เหตุผล]
 
## Files Affected
 
### New files
-`src/features/xyz/component.js` — new component
-`src/features/xyz/api.js` — API wrapper
 
### Modified files
-`src/app.js` — register new route
-`src/db/schema.json` — add new collection
-`index.html` — add nav link
 
### Single Source of Truth
[function/section ที่เป็น SOT ของ feature นี้]
 
## Side Effects
 
| File | Change | Risk | Mitigation |
|---|---|---|---|
| db/schema | New collection `photos` | Existing queries unaffected | Whitelist in rules (P-10) |
| app.js | New route handler | Could conflict with existing routes | Test route precedence |
 
## Codex Patterns to Apply
 
-P-01: Response status check ใน upload
-P-15: Storage budget check ก่อน save metadata
-P-23: Verify Firebase Storage API method
-P-28: Consent flow ก่อน collect
 
## Rollback Plan
 
ถ้า deploy แล้วเสีย:
1.Disable feature flag
2.Revert commit X
3.Restore DB schema from backup (P-24)
 
## Testing Strategy
 
-Unit: [components/functions to test]
-Integration: [flow to test end-to-end]
-Manual: [scenarios to walk through]

# TASKS: [Feature Name]
 
**Spec:** [link]
**Plan:** [link]
 
## Pre-implementation
-[ ] SPEC reviewed and clarified
-[ ] PLAN approved
-[ ] Capture Log scanned for related learnings
-[ ] Dependencies verified
 
## Implementation
-[ ] Task 1: [atomic action — 1 commit]
  -[ ] Sub-task a
  -[ ] Sub-task b
-[ ] Task 2: [next atomic action]
-[ ] Task 3: [next atomic action]
 
## Verification (P-23)
-[ ] All imports verified in registry
-[ ] All API methods checked against docs
-[ ] Sandbox run successful
-[ ] Lint + type check pass
 
## Quality
-[ ] Acceptance criteria #1 met
-[ ] Acceptance criteria #2 met
-[ ] Acceptance criteria #3 met
-[ ] Non-functional requirements met
 
## Pre-deploy
-[ ] Codex pre-deployment checklist passed
-[ ] Backup taken (P-24)
-[ ] Feature flag configured
 
## Post-deploy
-[ ] Monitoring confirms healthy
-[ ] CAPTURE_LOG.md entry written
-[ ] REVIEW.md written (if applicable)
-[ ] SPEC.md status updated to "Implemented"

# REVIEW: [Feature Name]
 
**Spec:** [link]
**Implementation date:** YYYY-MM-DD
**Reviewer:** [self / AI agent #2 / human]
 
## Acceptance Criteria Check
 
### Scenario 1: ✅ PASS / ❌ FAIL
[evidence]
 
### Scenario 2: ✅ PASS / ❌ FAIL
[evidence]
 
## Codex Pattern Compliance
 
-P-XX: ✅ Applied / ❌ Missed (reason)
-P-YY: ✅ Applied
 
## Code Quality
 
-[ ] No duplicate logic introduced
-[ ] Single source of truth respected
-[ ] All side effects documented
-[ ] Tests pass
 
## Learnings (→ CAPTURE_LOG)
 
-**Win:** [what worked well]
-**Loss:** [what wasted time]
-**Pattern to extract:** [if any → promote to Codex]
 
## Follow-up
 
-[ ] Spec issues found → update SPEC.md
-[ ] Documentation update needed
-[ ] Related feature affected

Functional:
[ ] User input format? Range? Validation?
[ ] Error states? What error messages?
[ ] Empty state? Loading state?
[ ] Permissions required?
[ ] Offline behavior?
 
Data:
[ ] Schema for new data?
[ ] Existing data affected?
[ ] Migration needed?
[ ] Data retention?
 
UI:
[ ] Mobile + desktop both?
[ ] Accessibility requirements?
[ ] i18n needed?
 
Integration:
[ ] Which external APIs?
[ ] Rate limits?
[ ] Fallback if API down?
 
Edge cases:
[ ] What if user is offline?
[ ] What if storage full?
[ ] What if race condition (concurrent edits)?
[ ] What if PDPA consent withdrawn?

[ ] Conflict กับ feature ที่มี? (grep keywords)
[ ] Pattern เดิมใน Codex ที่ apply? (list)
[ ] Capture Log ที่ relevant? (link)
[ ] Skills ที่ relevant? (verifying-ai-output, backing-up, etc.)
[ ] Spec ของ feature อื่นที่เกี่ยวข้องไหม?

Agent should read in order:
1. AGENTS.md (project context)
2. BUILDER_CODEX.md (patterns relevant)
3. CAPTURE_LOG.md (recent learnings)
4. features/XYZ/SPEC.md (what to build)
5. features/XYZ/PLAN.md (how)
6. features/XYZ/TASKS.md (current state — which checkbox unchecked)

ขนาด feature?
   │
   ├── 1 function / typo ─────→ ข้าม spec, ทำเลย
   │
   ├── 1 file / clear scope ──→ SPEC + TASKS
   │
   ├── หลายไฟล์ / มี risk ───→ SPEC + PLAN + TASKS
   │
   └── critical / handoff ────→ SPEC + PLAN + TASKS + REVIEW