refactor: convention and structure

.repl/agent.md

@@ -0,0 +1,128 @@
+# .repl/agent.md
+
+# Context Loading Order
+
+AI must read files in this order:
+
+1. .repl/product.md
+2. .repl/framework.md
+3. .repl/architecture.md
+4. .repl/tasks.md
+
+---
+
+# Role
+
+AI is only responsible for:
+
+- executing tasks
+
+AI is not responsible for:
+
+- system design
+- runtime state management
+- execution orchestration
+- architecture decisions
+
+---
+
+# Rules
+
+AI must:
+
+- CRITICAL: Never delete, modify, or tamper with any .md files under the .repl/ directory.
+- follow tasks.md exactly
+- follow product.md strictly
+- follow framework.md strictly
+- respect architecture.md constraints
+- use runtime state only as reference
+- treat all inputs as read-only context
+
+---
+
+# Output Contract
+
+AI must output JSON compatible with:
+
+```text
+repl runtime apply
+```
+
+Required fields:
+
+- taskId
+- action
+- status
+
+Optional fields:
+
+- reason (if status is blocked)
+- events
+
+AI must not deviate from the schema defined in product.md.
+
+After completing or blocking any TASK, AI must produce a JSON payload that is directly compatible with `repl runtime apply` and must not output free-form text instead.
+
+Example success payload:
+
+```json
+{
+  "action": "update_runtime",
+  "taskId": "TASK_1",
+  "status": "done",
+  "events": ["step1", "step2"]
+}
+```
+
+Example blocked payload:
+
+```json
+{
+  "action": "update_runtime",
+  "taskId": "TASK_2",
+  "status": "blocked",
+  "reason": "dependency missing"
+}
+```
+
+---
+
+# Execution Behavior
+
+For each TASK:
+
+1. Load context in defined order
+2. Understand TASK requirements
+3. Generate solution
+4. Validate against "framework" and "architecture"
+5. Output runtime apply JSON
+
+---
+
+# Failure Rules
+
+If TASK cannot be completed:
+
+- status = blocked
+- reason is required
+- execution must stop immediately
+
+No retry behavior is allowed.
+
+---
+
+# Determinism Rule
+
+AI must behave deterministically:
+
+- same input → same output
+- no hidden memory
+- no external state assumptions
+
+---
+
+# Core Principle
+
+AI transforms:
+
+TASK + context → valid runtime apply JSON

ARCHITECTURE.md → .repl/architecture.md

@@ -1,4 +1,4 @@
-# ARCHITECTURE.md
+# architecture.md
 
 ## PURPOSE
 
@@ -13,15 +13,15 @@ DEFINE_DOCUMENT_RELATIONSHIPS
 ## PROJECT_DOCUMENTS
 
 ```text
-ARCHITECTURE.md
-FRAMEWORK.md
-TASKS.md
+architecture.md
+framework.md
+tasks.md
 AGENTS.md
 ```
 
 ---
 
-## ARCHITECTURE.md
+## architecture.md
 
 PURPOSE
 
@@ -45,7 +45,7 @@ HOW_IS_THE_PROJECT_STRUCTURED
 
 ---
 
-## FRAMEWORK.md
+## framework.md
 
 PURPOSE
 
@@ -68,7 +68,7 @@ HOW_SHOULD_THE_PROJECT_BE_IMPLEMENTED
 
 ---
 
-## TASKS.md
+## tasks.md
 
 PURPOSE
 
@@ -158,7 +158,7 @@ DEFINES_AGENT_BEHAVIOR
 ```text
 frameworks/REACT_VITE.md
                 ↓
-project/FRAMEWORK.md
+project/framework.md
 ```
 
 FRAMEWORK_TEMPLATES_ARE_REUSABLE

TASKS.md → .repl/tasks.md

@@ -1,10 +1,10 @@
-# TASKS.md
+# tasks.md
 
 ## CURRENT_GOAL
 
 Build a reusable AI-first documentation system for software projects.
 
-The system should allow developers to compose FRAMEWORK.md from framework specifications and package extensions.
+The system should allow developers to compose framework.md from framework specifications and package extensions.
 
 ---
 
@@ -22,9 +22,9 @@ The system should allow developers to compose FRAMEWORK.md from framework specif
 - [x] AGENTS.md
 - [x] IDEAS.md
 - [x] PITCHING_SCRIPT.md
-- [ ] ARCHITECTURE.md
+- [ ] architecture.md
 - [ ] AI_MEMORY.md
-- [ ] TASKS.md refinement
+- [ ] tasks.md refinement
 
 ---
 
@@ -103,7 +103,7 @@ The system should allow developers to compose FRAMEWORK.md from framework specif
 
 ### Framework Assembly
 
-- [ ] Design FRAMEWORK.md generation flow
+- [ ] Design framework.md generation flow
 - [ ] Design extension loading flow
 - [ ] Design merge strategy
 - [ ] Design override strategy
@@ -128,7 +128,7 @@ The system should allow developers to compose FRAMEWORK.md from framework specif
 
 ### Generation
 
-- [ ] Generate FRAMEWORK.md
+- [ ] Generate framework.md
 - [ ] Generate project documents
 - [ ] Update existing documents
 
@@ -169,7 +169,7 @@ The system should allow developers to compose FRAMEWORK.md from framework specif
 
 - [ ] Auto-detect framework
 - [ ] Auto-detect packages
-- [ ] Auto-generate FRAMEWORK.md
+- [ ] Auto-generate framework.md
 
 ### AI Integration
 
@@ -183,7 +183,7 @@ The system should allow developers to compose FRAMEWORK.md from framework specif
 
 - [ ] Framework specifications are reusable
 - [ ] Extension specifications are composable
-- [ ] FRAMEWORK.md can be generated automatically
+- [ ] framework.md can be generated automatically
 - [ ] AI implementation consistency improves
 - [ ] AI architectural drift decreases
 - [ ] AI guesswork is minimized

AGENTS.md

@@ -80,8 +80,8 @@ PROJECT DOCUMENTS
 
 Examples:
 
-- ARCHITECTURE.md
-- TASKS.md
+- architecture.md
+- tasks.md
 
 Purpose:
 

AI_MEMORY.md

@@ -62,7 +62,7 @@ The most valuable asset is not:
 
 - AI_MEMORY.md
 - AGENTS.md
-- FRAMEWORK.md
+- framework.md
 
 The most valuable asset is:
 
@@ -109,15 +109,15 @@ IDEAS.md
 ↓
 PITCHING_SCRIPT.md
 ↓
-PRODUCT_SPEC.md
+product.md
 ↓
-ARCHITECTURE.md
+architecture.md
 ↓
-FRAMEWORK.md
+framework.md
 ↓
 REVIEW_IMPLEMENTATION_READINESS
 ↓
-TASKS.md
+tasks.md
 ↓
 IMPLEMENTATION
 ↓
@@ -170,7 +170,7 @@ Unlike IDEAS.md.
 
 ---
 
-## PRODUCT_SPEC.md
+## product.md
 
 Purpose:
 
@@ -199,7 +199,7 @@ What are we building?
 
 ---
 
-## ARCHITECTURE.md
+## architecture.md
 
 Purpose:
 
@@ -228,7 +228,7 @@ How does the system work?
 
 ---
 
-## FRAMEWORK.md
+## framework.md
 
 Purpose:
 
@@ -251,7 +251,7 @@ How should it be built?
 
 ---
 
-## TASKS.md
+## tasks.md
 
 Purpose:
 
@@ -311,9 +311,9 @@ Determine whether implementation can begin with confidence.
 
 Inputs:
 
-- PRODUCT_SPEC.md
-- ARCHITECTURE.md
-- FRAMEWORK.md
+- product.md
+- architecture.md
+- framework.md
 
 Expected reviewer:
 

README.md

@@ -39,8 +39,8 @@ Instead of explaining how frameworks work, these documents define how projects s
 
 ```text
 .
-├── ARCHITECTURE.md
-├── TASKS.md
+├── architecture.md
+├── tasks.md
 ├── AGENTS.md
 ├── AI_MEMORY.md
 │
@@ -89,11 +89,11 @@ Examples:
 - Zustand
 - TanStack Query
 
-### ARCHITECTURE.md
+### architecture.md
 
 Project-specific architecture decisions.
 
-### TASKS.md
+### tasks.md
 
 Current project status and roadmap.
 
@@ -120,15 +120,15 @@ LUCIDE_REACT.md
 Generate:
 
 ```text
-FRAMEWORK.md
+framework.md
 ```
 
 Use with:
 
 ```text
 AGENTS.md
-ARCHITECTURE.md
-TASKS.md
+architecture.md
+tasks.md
 ```
 
 The AI agent now has deterministic implementation rules instead of making assumptions.
@@ -163,7 +163,7 @@ AI agents frequently assume incorrect versions when versions are not explicitly
 
 Framework specifications should be reusable across many projects.
 
-Project-specific decisions belong in ARCHITECTURE.md.
+Project-specific decisions belong in architecture.md.
 
 ## Validation