From b5ca30ecce79aeb060d2034976e7dda2a4fa1c83 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Thu, 1 Oct 2026 18:39:37 +0900 Subject: [PATCH] feat: add comprehensive architecture and tasks documentation --- .replworks/ARCHITECTURE.md | 191 +++++++++++++++++++++++++++ .replworks/TASKS.md | 189 ++++++++++++++++++++++++++ AGENTS.md | 65 +-------- templates/AGENTS.md | 263 +++++++++++++++++++++++++++++++++++++ 4 files changed, 645 insertions(+), 63 deletions(-) create mode 100644 .replworks/ARCHITECTURE.md create mode 100644 .replworks/TASKS.md create mode 100644 templates/AGENTS.md diff --git a/.replworks/ARCHITECTURE.md b/.replworks/ARCHITECTURE.md new file mode 100644 index 0000000..5cec7aa --- /dev/null +++ b/.replworks/ARCHITECTURE.md @@ -0,0 +1,191 @@ +# architecture.md + +## PURPOSE + +DEFINE_PROJECT_DOCUMENT_ARCHITECTURE + +DEFINE_DOCUMENT_RESPONSIBILITIES + +DEFINE_DOCUMENT_RELATIONSHIPS + +--- + +## PROJECT_DOCUMENTS + +```text +ARCHITECTURE.md +TASKS.md +AGENTS.md +``` + +--- + +## architecture.md + +PURPOSE + +DEFINE_SYSTEM_STRUCTURE + +DEFINE_COMPONENT_BOUNDARIES + +DEFINE_PROJECT_ORGANIZATION + +CONTAINS + +- components +- layers +- modules +- data_flow +- responsibility_boundaries + +QUESTION + +HOW_IS_THE_PROJECT_STRUCTURED + +--- + +## framework.md + +PURPOSE + +DEFINE_IMPLEMENTATION_RULES + +DEFINE_TECHNICAL_CONSTRAINTS + +CONTAINS + +- stack +- versions +- directory_structure +- file_placement +- naming_rules +- restrictions + +QUESTION + +HOW_SHOULD_THE_PROJECT_BE_IMPLEMENTED + +--- + +## tasks.md + +PURPOSE + +TRACK_CURRENT_WORK + +TRACK_PROGRESS + +TRACK_NEXT_ACTIONS + +CONTAINS + +- active_tasks +- completed_tasks +- priorities +- next_steps + +QUESTION + +WHAT_SHOULD_BE_DONE_NEXT + +--- + +## AGENTS.md + +PURPOSE + +DEFINE_AGENT_BEHAVIOR + +DEFINE_EXECUTION_RULES + +DEFINE_DOCUMENT_LOADING_ORDER + +CONTAINS + +- workflow +- validation_rules +- execution_rules + +QUESTION + +HOW_SHOULD_THE_AGENT_OPERATE + +--- + +## DOCUMENT_DEPENDENCIES + +```text +ARCHITECTURE + ↓ +FRAMEWORK + ↓ +TASKS +``` + +AGENTS_READS_ALL_DOCUMENTS + +--- + +## DOCUMENT_RESPONSIBILITIES + +ARCHITECTURE + +DEFINES_STRUCTURE + +--- + +FRAMEWORK + +DEFINES_IMPLEMENTATION_CONSTRAINTS + +--- + +TASKS + +DEFINES_CURRENT_WORK + +--- + +AGENTS + +DEFINES_AGENT_BEHAVIOR + +--- + +## FRAMEWORK_TEMPLATE_FLOW + +```text +frameworks/REACT_VITE.md + ↓ +project/framework.md +``` + +FRAMEWORK_TEMPLATES_ARE_REUSABLE + +PROJECT_FRAMEWORK_MD_IS_PROJECT_SPECIFIC + +--- + +## DESIGN_RULES + +AI_FIRST + +EXPLICIT_OVER_IMPLICIT + +CONSTRAINTS_OVER_EXPLANATIONS + +CONSISTENCY_OVER_FLEXIBILITY + +REUSE_OVER_REINVENTION + +--- + +## CORE_PRINCIPLE + +ARCHITECTURE_DEFINES_STRUCTURE + +FRAMEWORK_DEFINES_CONSTRAINTS + +TASKS_DEFINE_EXECUTION + +AGENTS_DEFINE_BEHAVIOR diff --git a/.replworks/TASKS.md b/.replworks/TASKS.md new file mode 100644 index 0000000..63d4cd6 --- /dev/null +++ b/.replworks/TASKS.md @@ -0,0 +1,189 @@ +# 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. + +--- + +## PHASE_1_FOUNDATION + +### Repository Structure + +- [ ] Define repository directory structure +- [ ] Define naming conventions +- [ ] Define document lifecycle +- [ ] Define document loading order + +### Core Documents + +- [x] AGENTS.md +- [x] IDEAS.md +- [x] PITCHING_SCRIPT.md +- [ ] architecture.md +- [ ] AI_MEMORY.md +- [ ] tasks.md refinement + +--- + +## PHASE_2_FRAMEWORK_SPECIFICATIONS + +### React Ecosystem + +- [x] REACT_VITE.md +- [x] ASTRO.md +- [x] VANILLA.md +- [ ] NEXTJS.md +- [ ] REMIX.md + +### Laravel Ecosystem + +- [ ] LARAVEL.md + +### Python Ecosystem + +- [ ] FASTAPI.md +- [ ] DJANGO.md + +### Additional Frameworks + +- [ ] NUXT.md +- [ ] SVELTEKIT.md + +--- + +## PHASE_3_EXTENSION_SPECIFICATIONS + +### React + +- [ ] REACT_ROUTER.md +- [ ] I18NEXT.md +- [ ] LUCIDE_REACT.md +- [ ] ZUSTAND.md +- [ ] TANSTACK_QUERY.md +- [ ] REACT_HOOK_FORM.md +- [ ] ZOD.md +- [ ] AXIOS.md + +### Laravel + +- [ ] LIVEWIRE.md +- [ ] INERTIA.md +- [ ] FILAMENT.md +- [ ] PEST.md + +### Shared + +- [ ] DOCKER.md +- [ ] GITHUB_ACTIONS.md + +--- + +## PHASE_4_DOCUMENT_STANDARDS + +### Framework Specification Standard + +- [ ] Define required sections +- [ ] Define version policy +- [ ] Define structure policy +- [ ] Define generation policy + +### Extension Specification Standard + +- [ ] Define extension format +- [ ] Define activation rules +- [ ] Define merge rules +- [ ] Define conflict rules + +--- + +## PHASE_5_COMPOSITION_SYSTEM + +### Framework Assembly + +- [ ] Design framework.md generation flow +- [ ] Design extension loading flow +- [ ] Design merge strategy +- [ ] Design override strategy + +### Package Detection + +- [ ] Detect installed packages +- [ ] Map packages to extensions +- [ ] Support manual extension selection + +--- + +## PHASE_6_CLI + +### Commands + +- [ ] replworks init +- [ ] replworks framework +- [ ] replworks extension +- [ ] replworks build-framework +- [ ] replworks update-framework + +### Generation + +- [ ] Generate framework.md +- [ ] Generate project documents +- [ ] Update existing documents + +--- + +## PHASE_7_VALIDATION + +### AI Testing + +- [ ] Test with ChatGPT +- [ ] Test with Claude +- [ ] Test with Gemini +- [ ] Test with Cursor + +### Framework Validation + +- [ ] React/Vite validation +- [ ] Next.js validation +- [ ] Laravel validation +- [ ] FastAPI validation + +### Extension Validation + +- [ ] Router validation +- [ ] i18n validation +- [ ] State management validation + +--- + +## FUTURE + +### Marketplace + +- [ ] Community specifications +- [ ] Community extensions + +### Automation + +- [ ] Auto-detect framework +- [ ] Auto-detect packages +- [ ] Auto-generate framework.md + +### AI Integration + +- [ ] MCP support +- [ ] IDE integration +- [ ] Agent integration + +--- + +## SUCCESS_CRITERIA + +- [ ] Framework specifications are reusable +- [ ] Extension specifications are composable +- [ ] framework.md can be generated automatically +- [ ] AI implementation consistency improves +- [ ] AI architectural drift decreases +- [ ] AI guesswork is minimized diff --git a/AGENTS.md b/AGENTS.md index d422fe2..694face 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,10 +3,8 @@ ## DOCUMENT_ORDER 1. AGENTS.md -2. PRODUCT_SPEC.md -3. TECH_STACK.md -4. ARCHITECTURE.md -5. TASKS.md +2. ./replworks/ARCHITECTURE.md +3. ./replworks/TASKS.md Only these documents are authoritative. --- @@ -26,18 +24,6 @@ Never implement features described only in docs/. ## SOURCE_OF_TRUTH -Product Requirements: - -```text -PRODUCT_SPEC.md -``` - -Implementation Constraints: - -```text -TECH_STACK.md -``` - Architecture: ```text @@ -53,10 +39,6 @@ TASKS.md If a conflict exists: ```text -PRODUCT_SPEC.md -> -TECH_STACK.md -> ARCHITECTURE.md > TASKS.md @@ -68,19 +50,6 @@ everything else ## DOCUMENT_RESPONSIBILITIES -PRODUCT_SPEC.md defines: - -```text -What the product is. -What the product does. -``` - -TECH_STACK.md defines: - -```text -How the product must be implemented. -``` - ARCHITECTURE.md defines: ```text @@ -124,16 +93,9 @@ assumptions inferred requirements ``` -Requirements must originate from: - -```text -PRODUCT_SPEC.md -``` - Implementation must follow: ```text -TECH_STACK.md ARCHITECTURE.md ``` @@ -180,29 +142,6 @@ Re-verify mocks when the external system's behavior may have changed. --- -## PRODUCT_CHANGES - -If implementation reveals missing product requirements, or a PRODUCT_SPEC.md section is marked UNVERIFIED: - -```text -Stop. -Do not invent requirements. -``` - -Update PRODUCT_SPEC.md, and clear the UNVERIFIED mark only after human confirmation, before implementation continues. - ---- - -## TECH_STACK_CHANGES - -If implementation requires tech stack changes: - -1. Update TECH_STACK.md -2. Update implementation - Never allow tech stack and code to diverge. - ---- - ## ARCHITECTURE_CHANGES If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED: diff --git a/templates/AGENTS.md b/templates/AGENTS.md new file mode 100644 index 0000000..f6199ec --- /dev/null +++ b/templates/AGENTS.md @@ -0,0 +1,263 @@ +# AGENTS.md + +## DOCUMENT_ORDER + +1. AGENTS.md +2. ./replworks/PRODUCT_SPEC.md +3. ./replworks/TECH_STACK.md +4. ./replworks/ARCHITECTURE.md +5. ./replworks/TASKS.md + Only these documents are authoritative. + +--- + +## IGNORE + +Ignore all files under: + +```text +docs/ +``` + +Never use files in docs/ as requirements. +Never implement features described only in docs/. + +--- + +## SOURCE_OF_TRUTH + +Product Requirements: + +```text +PRODUCT_SPEC.md +``` + +Implementation Constraints: + +```text +TECH_STACK.md +``` + +Architecture: + +```text +ARCHITECTURE.md +``` + +Execution Plan: + +```text +TASKS.md +``` + +If a conflict exists: + +```text +PRODUCT_SPEC.md +> +TECH_STACK.md +> +ARCHITECTURE.md +> +TASKS.md +> +everything else +``` + +--- + +## DOCUMENT_RESPONSIBILITIES + +PRODUCT_SPEC.md defines: + +```text +What the product is. +What the product does. +``` + +TECH_STACK.md defines: + +```text +How the product must be implemented. +``` + +ARCHITECTURE.md defines: + +```text +How the product works. +``` + +TASKS.md defines: + +```text +What should be implemented next. +``` + +Do not move responsibilities between documents. + +--- + +## EXTERNAL_BOUNDARY + +Define once. Referenced by TASK_EXECUTION and MOCK_RULES below. + +```text +External boundary = any behavior not controlled by this codebase. +Examples: +third-party DOM +third-party API +browser runtime behavior +``` + +--- + +## IMPLEMENTATION_RULES + +Implement only the selected task. +Do not implement: + +```text +future work +roadmap items +optional features +assumptions +inferred requirements +``` + +Requirements must originate from: + +```text +PRODUCT_SPEC.md +``` + +Implementation must follow: + +```text +TECH_STACK.md +ARCHITECTURE.md +``` + +--- + +## TASK_EXECUTION + +For every task: + +1. Read PRODUCT_SPEC.md +2. Read TECH_STACK.md +3. Read ARCHITECTURE.md +4. Read task definition +5. If the task touches a domain not covered by verified knowledge in PRODUCT_SPEC.md or ARCHITECTURE.md: stop. Mark the relevant section UNVERIFIED. Do not implement against an UNVERIFIED section. Require explicit human confirmation before continuing. +6. Implement +7. Write unit tests for internal logic +8. If the task touches an EXTERNAL_BOUNDARY: write an E2E test against the live boundary. A mocked test alone does not satisfy this step. +9. Run all tests +10. Stop + Do not start another task automatically. + +--- + +## MOCK_RULES + +Mock only observed behavior. + +```text +Allowed sources: +recorded live response +documented spec +``` + +```text +Forbidden sources: +assumed behavior +guessed response +inferred event flow +``` + +If a mock's values cannot be traced to a recorded observation or a spec, do not write it. +Any code touching an EXTERNAL_BOUNDARY requires at least one live observation before it may be mocked. +Re-verify mocks when the external system's behavior may have changed. + +--- + +## PRODUCT_SPEC_CHANGES + +If implementation reveals missing product requirements, or a PRODUCT_SPEC.md section is marked UNVERIFIED: + +```text +Stop. +Do not invent requirements. +``` + +Update PRODUCT_SPEC.md, and clear the UNVERIFIED mark only after human confirmation, before implementation continues. + +--- + +## TECH_STACK_CHANGES + +If implementation requires tech stack changes: + +1. Update TECH_STACK.md +2. Update implementation + Never allow tech stack and code to diverge. + +--- + +## ARCHITECTURE_CHANGES + +If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED: + +1. Update ARCHITECTURE.md +2. Clear the UNVERIFIED mark only after human confirmation +3. Update implementation + Never allow architecture and code to diverge. + +--- + +## TASK_CHANGES + +If implementation invalidates a task: +Update TASKS.md. + +--- + +## DESIGN_RULES + +Prefer: + +```text +simple +explicit +minimal +``` + +Avoid: + +```text +abstraction without use +premature optimization +speculative features +``` + +--- + +## FILE_CREATION + +Do not create new top-level documents unless explicitly requested. +Prefer modifying existing files. + +--- + +## SUCCESS_CRITERIA + +Task is complete only when: + +- product requirements satisfied +- architectural requirements satisfied +- tech stack constraints satisfied +- acceptance criteria satisfied +- no UNVERIFIED sections remain in scope for this task +- code runs +- unit tests pass +- E2E tests pass for any EXTERNAL_BOUNDARY code touched + Then stop.