diff --git a/.repl/agent.md b/.repl/agent.md deleted file mode 100644 index 32fdc17..0000000 --- a/.repl/agent.md +++ /dev/null @@ -1,128 +0,0 @@ -# .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 diff --git a/.repl/architecture.md b/.repl/architecture.md deleted file mode 100644 index 0e5f52d..0000000 --- a/.repl/architecture.md +++ /dev/null @@ -1,192 +0,0 @@ -# architecture.md - -## PURPOSE - -DEFINE_PROJECT_DOCUMENT_ARCHITECTURE - -DEFINE_DOCUMENT_RESPONSIBILITIES - -DEFINE_DOCUMENT_RELATIONSHIPS - ---- - -## PROJECT_DOCUMENTS - -```text -architecture.md -framework.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/.repl/tasks.md b/.repl/tasks.md deleted file mode 100644 index d0f4952..0000000 --- a/.repl/tasks.md +++ /dev/null @@ -1,189 +0,0 @@ -# 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 11224fe..0ed0082 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,244 +1,263 @@ # AGENTS.md -## ROLE +## DOCUMENT_ORDER -You are a documentation engineering agent. - -Your responsibility is to create, maintain, and improve AI-facing project documents. - -This repository does not contain application code. - -This repository contains reusable specifications, templates, and conventions. +1. AGENTS.md +2. PRODUCT_SPEC.md +3. TECH_STACK.md +4. ARCHITECTURE.md +5. TASKS.md + Only these documents are authoritative. --- -## REPOSITORY_PURPOSE +## IGNORE -The purpose of this repository is to provide reusable project documentation for AI-assisted software development. +Ignore all files under: -Documents must optimize for: +```text +docs/ +``` -- AI comprehension -- AI consistency -- AI implementation accuracy -- Long-term maintainability - -Documents are written for AI agents. - -Humans are secondary readers. +Never use files in docs/ as requirements. +Never implement features described only in docs/. --- -## PRIMARY_GOAL +## SOURCE_OF_TRUTH -Reduce AI guesswork. +Product Requirements: -Reduce architectural drift. +```text +PRODUCT_SPEC.md +``` -Reduce implementation inconsistency. +Implementation Constraints: -Increase deterministic project generation. +```text +TECH_STACK.md +``` ---- +Architecture: -## DOCUMENT_TYPES +```text +ARCHITECTURE.md +``` -FRAMEWORK DOCUMENTS +Execution Plan: -Examples: - -- REACT_VITE.md -- NEXTJS.md -- LARAVEL.md -- FASTAPI.md +```text +TASKS.md +``` -Purpose: +If a conflict exists: -Define framework-specific constraints and conventions. +```text +PRODUCT_SPEC.md +> +TECH_STACK.md +> +ARCHITECTURE.md +> +TASKS.md +> +everything else +``` --- -EXTENSION DOCUMENTS +## DOCUMENT_RESPONSIBILITIES -Examples: +PRODUCT_SPEC.md defines: -- REACT_ROUTER.md -- I18NEXT.md -- ZUSTAND.md +```text +What the product is. +What the product does. +``` -Purpose: +TECH_STACK.md defines: -Define package-specific constraints and conventions. +```text +How the product must be implemented. +``` -Extensions augment framework documents. +ARCHITECTURE.md defines: -Extensions must not duplicate framework rules. +```text +How the product works. +``` ---- +TASKS.md defines: -PROJECT DOCUMENTS +```text +What should be implemented next. +``` -Examples: - -- architecture.md -- tasks.md - -Purpose: - -Define project-specific information. - -These documents belong in application repositories. +Do not move responsibilities between documents. --- -## SPECIFICATION_PHILOSOPHY - -Prefer constraints over explanations. - -Prefer rules over recommendations. - -Prefer deterministic behavior over flexibility. - -Prefer consistency over completeness. - -Avoid educational content. - -Avoid tutorials. +## EXTERNAL_BOUNDARY -Avoid marketing language. +Define once. Referenced by TASK_EXECUTION and MOCK_RULES below. -Avoid human-oriented prose. +```text +External boundary = any behavior not controlled by this codebase. +Examples: +third-party DOM +third-party API +browser runtime behavior +``` --- -## WRITING_RULES - -Write for implementation agents. - -Assume documents are machine-consumed. +## IMPLEMENTATION_RULES -Use short directives. +Implement only the selected task. +Do not implement: -Use explicit constraints. - -Use uppercase directives when appropriate. - -Examples: +```text +future work +roadmap items +optional features +assumptions +inferred requirements +``` -GOOD +Requirements must originate from: -USE_FUNCTION_COMPONENTS_ONLY +```text +PRODUCT_SPEC.md +``` -DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES +Implementation must follow: -PACKAGE_JSON_IS_SOURCE_OF_TRUTH +```text +TECH_STACK.md +ARCHITECTURE.md +``` -BAD +--- -"Developers should generally consider..." +## TASK_EXECUTION -"It is recommended that..." +For every task: -"You may want to..." +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. --- -## FRAMEWORK_DOCUMENT_RULES - -Framework documents should define: +## MOCK_RULES -- stack -- versions -- structure -- file placement -- naming conventions -- generation policies +Mock only observed behavior. -Framework documents should not define: +```text +Allowed sources: +recorded live response +documented spec +``` -- project-specific business rules -- project-specific architecture -- project-specific content +```text +Forbidden sources: +assumed behavior +guessed response +inferred event flow +``` -Framework documents must remain reusable. +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. --- -## EXTENSION_DOCUMENT_RULES - -Extensions should be package-oriented. - -Examples: +## PRODUCT_CHANGES -- React Router -- i18next -- Zustand -- TanStack Query +If implementation reveals missing product requirements, or a PRODUCT_SPEC.md section is marked UNVERIFIED: -Extensions should activate additional constraints. +```text +Stop. +Do not invent requirements. +``` -Extensions should not redefine framework behavior. +Update PRODUCT_SPEC.md, and clear the UNVERIFIED mark only after human confirmation, before implementation continues. --- -## VERSION_POLICY +## TECH_STACK_CHANGES -Always specify versions when known. +If implementation requires framework changes: -AI agents frequently assume incorrect versions. - -Version ambiguity is a specification failure. - -When versions differ: - -package.json is source of truth. +1. Update TECH_STACK.md +2. Update implementation + Never allow framework and code to diverge. --- -## AI_OPTIMIZATION_RULES +## ARCHITECTURE_CHANGES -Documents should minimize ambiguity. +If implementation requires architecture changes, or an ARCHITECTURE.md section is marked UNVERIFIED: -Documents should minimize interpretation. +1. Update ARCHITECTURE.md +2. Clear the UNVERIFIED mark only after human confirmation +3. Update implementation + Never allow architecture and code to diverge. -Documents should minimize assumptions. - -Every rule should answer: +--- -"What should an implementation agent do?" +## TASK_CHANGES -If a rule does not influence implementation behavior, consider removing it. +If implementation invalidates a task: +Update TASKS.md. --- -## EVOLUTION_POLICY +## DESIGN_RULES -Specifications are living documents. +Prefer: -Improve specifications when recurring AI mistakes are discovered. +```text +simple +explicit +minimal +``` -New rules should emerge from real implementation failures. +Avoid: -Avoid speculative rules. - -Prefer observed failures over theoretical concerns. +```text +abstraction without use +premature optimization +speculative features +``` --- -## SUCCESS_CRITERIA - -A successful specification: +## FILE_CREATION -- prevents common AI mistakes -- reduces architectural invention -- reduces unnecessary file creation -- improves implementation consistency -- remains reusable across projects +Do not create new top-level documents unless explicitly requested. +Prefer modifying existing files. --- -## CORE_PRINCIPLE - -AI should not guess. +## SUCCESS_CRITERIA -Specifications exist to eliminate guessing. +Task is complete only when: + +- product requirements satisfied +- architectural requirements satisfied +- framework 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. diff --git a/ai-memory.md b/ai-memory.md deleted file mode 100644 index 76cac28..0000000 --- a/ai-memory.md +++ /dev/null @@ -1,478 +0,0 @@ -# ai-memory.md - -# ReplWorks Memory - -Version: 2026-06 - ---- - -# Core Understanding - -ReplWorks is not a project memory system. - -Project memory is only one component. - -The actual goal is: - -```text -Create a repeatable workflow that turns ideas into shipped products using AI. -``` - -The original motivation was AI memory loss during development. - -However, memory loss was identified as a symptom rather than the root problem. - -The root problem is: - -```text -How can a solo founder repeatedly transform ideas into production software using AI? -``` - -ReplWorks exists to answer that question. - ---- - -# ReplWorks Definition - -Current definition: - -```text -AI-Native Product Development Workflow -``` - -Alternative definition: - -```text -A workflow methodology for turning ideas into software through AI-assisted execution. -``` - -ReplWorks should be positioned as a workflow system or methodology. - -Not as a memory system. - -Not as a documentation system. - -Not as an AI tool. - ---- - -# Important Discovery - -The most valuable asset is not: - -- AI_MEMORY.md -- AGENTS.md -- framework.md - -The most valuable asset is: - -```text -Workflow -+ -Document Generation Prompts -+ -Validation Prompts -``` - -The workflow is reusable across projects. - -Individual documents are not. - ---- - -# Development Philosophy - -The goal is not: - -```text -Find a better AI. -``` - -The goal is: - -```text -Create a better workflow. -``` - -AI models will improve over time. - -The workflow should survive model changes. - ---- - -# Workflow - -Current ReplWorks workflow: - -```text -IDEAS.md -↓ -PITCHING_SCRIPT.md -↓ -product.md -↓ -architecture.md -↓ -framework.md -↓ -REVIEW_IMPLEMENTATION_READINESS -↓ -tasks.md -↓ -IMPLEMENTATION -↓ -AI_MEMORY.md -``` - -This workflow is currently considered the core of ReplWorks. - ---- - -# Document Responsibilities - -## IDEAS.md - -Purpose: - -```text -Capture the validated product idea. -``` - -Rules: - -- Product idea only. -- No implementation. -- No architecture. -- No technology choices. -- No execution plan. - ---- - -## PITCHING_SCRIPT.md - -Purpose: - -```text -Persuade a specific audience. -``` - -Audience may be: - -- investors -- VCs -- government programs -- partners -- customers - -Expected numbers, assumptions and projections may be included. - -Unlike IDEAS.md. - ---- - -## product.md - -Purpose: - -```text -Define what the product is. -``` - -Contains: - -- product requirements -- user-visible behavior -- user flows -- acceptance criteria - -Does not contain: - -- implementation -- architecture -- technologies - -Question answered: - -```text -What are we building? -``` - ---- - -## architecture.md - -Purpose: - -```text -Define how the product works internally. -``` - -Contains: - -- responsibilities -- flows -- ownership boundaries -- invariants - -Does not contain: - -- technologies -- frameworks -- libraries - -Question answered: - -```text -How does the system work? -``` - ---- - -## framework.md - -Purpose: - -```text -Define implementation constraints. -``` - -Contains: - -- language -- stack -- coding conventions -- implementation rules - -Question answered: - -```text -How should it be built? -``` - ---- - -## tasks.md - -Purpose: - -```text -Define what remains to be implemented. -``` - -Contains: - -- implementation milestones -- acceptance criteria - -Does not contain: - -- architecture -- implementation details - -Question answered: - -```text -What should be built next? -``` - ---- - -## AI_MEMORY.md - -Purpose: - -```text -Preserve decision-making context. -``` - -Not project documentation. - -Not requirements. - -Not architecture. - -Used for context recovery in future sessions. - ---- - -# Review Strategy - -The most important review step is: - -```text -REVIEW_IMPLEMENTATION_READINESS -``` - -Purpose: - -```text -Determine whether implementation can begin with confidence. -``` - -Inputs: - -- product.md -- architecture.md -- framework.md - -Expected reviewer: - -```text -Execution AI -``` - -Examples: - -- Codex -- implementation-focused agents - -Not discussion-oriented models. - ---- - -# Discussion AI vs Execution AI - -## Discussion AI - -Examples: - -- ChatGPT -- Claude - -Responsibilities: - -- ideation -- specifications -- architecture -- planning -- workflows - -Question: - -```text -What should we build? -``` - ---- - -## Execution AI - -Examples: - -- Codex - -Responsibilities: - -- implementation review -- implementation certainty -- execution - -Question: - -```text -Can this actually be built? -``` - ---- - -# Key Insight - -Many people combine multiple AI systems. - -The value does not come from using different models. - -The value comes from separating: - -```text -Creation -``` - -and - -```text -Validation -``` - -ReplWorks should preserve that separation. - ---- - -# AI-Issuer Context - -AI-Issuer became an important test project. - -Purpose: - -```text -Separate AI-generated issues from human-generated issues. -``` - -Important architectural decision: - -```text -Author != Publisher -``` - -Reason: - -Publishing an AI-generated issue under a human account creates implicit ownership and responsibility. - -The project attempts to preserve the distinction between: - -```text -Content Creation -``` - -and - -```text -Content Publication -``` - ---- - -# Current ReplWorks Positioning - -Previous positioning: - -```text -Project Memory System for AI Development -``` - -Current positioning: - -```text -AI-Native Product Development Workflow -``` - -Reason: - -Memory is only one step in the workflow. - -Workflow is the primary product. - ---- - -# Future Direction - -ReplWorks should evolve toward: - -```text -AI Product Development Methodology -``` - -Comparable in spirit to: - -- Waterfall -- Agile -- Scrum - -But designed specifically for AI-assisted software creation. - -The long-term goal is not better prompting. - -The long-term goal is: - -```text -A repeatable system that transforms ideas into shipped products. -``` diff --git a/builtin/agent.md b/builtin/agent.md deleted file mode 100644 index 32fdc17..0000000 --- a/builtin/agent.md +++ /dev/null @@ -1,128 +0,0 @@ -# .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 diff --git a/docs/AGENTS.md b/docs/AGENTS.md deleted file mode 100644 index 32b99a9..0000000 --- a/docs/AGENTS.md +++ /dev/null @@ -1,263 +0,0 @@ -# AGENTS.md - -## DOCUMENT_ORDER - -1. AGENTS.md -2. PRODUCT_SPEC.md -3. ARCHITECTURE.md -4. FRAMEWORK.md -5. 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 -``` - -Architecture: - -```text -ARCHITECTURE.md -``` - -Implementation Constraints: - -```text -FRAMEWORK.md -``` - -Execution Plan: - -```text -TASKS.md -``` - -If a conflict exists: - -```text -PRODUCT_SPEC.md -> -ARCHITECTURE.md -> -FRAMEWORK.md -> -TASKS.md -> -everything else -``` - ---- - -## DOCUMENT_RESPONSIBILITIES - -PRODUCT_SPEC.md defines: - -```text -What the product is. -What the product does. -``` - -ARCHITECTURE.md defines: - -```text -How the product works. -``` - -FRAMEWORK.md defines: - -```text -How the product must be implemented. -``` - -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 -ARCHITECTURE.md -FRAMEWORK.md -``` - ---- - -## TASK_EXECUTION - -For every task: - -1. Read PRODUCT_SPEC.md -2. Read ARCHITECTURE.md -3. Read FRAMEWORK.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_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. - ---- - -## 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. - ---- - -## FRAMEWORK_CHANGES - -If implementation requires framework changes: - -1. Update FRAMEWORK.md -2. Update implementation - Never allow framework 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 -- framework 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. diff --git a/docs/ideas.md b/docs/IDEAS.md similarity index 94% rename from docs/ideas.md rename to docs/IDEAS.md index 0aa4c55..383ebd9 100644 --- a/docs/ideas.md +++ b/docs/IDEAS.md @@ -1,4 +1,4 @@ -# ideas.md +# IDEAS.md # ReplWorks Documents @@ -65,7 +65,7 @@ AI는 일반적인 개발 지식보다 현재 프로젝트의 규칙을 더 필 --- -### 2. Framework First +### 2. Tech Stack First 프로젝트마다 사용하는 기술 스택은 다르다. @@ -117,22 +117,30 @@ AI는 추측하지 않는다. ```text AGENTS.md -architecture.md -tasks.md +PRODUCT_SPEC.md +TECH_STACK.md +ARCHITECTURE.md +TASKS.md AI_MEMORY.md - -framework.md ``` ### AGENTS.md AI 에이전트의 행동 규칙 -### architecture.md +### PRODUCT_SPEC.md + +현재 프로젝트가 무엇이고, 무엇을 하는가. + +### TECH_STACK.md + +현재 프로젝트의 기술 스택 및 개발 규칙 + +### ARCHITECTURE.md 시스템 구조 및 설계 -### tasks.md +### TASKS.md 현재 작업 목록 @@ -140,10 +148,6 @@ AI 에이전트의 행동 규칙 제품 비전 및 장기 컨텍스트 -### framework.md - -현재 프로젝트의 기술 스택 및 개발 규칙 - --- ## 기대 효과 diff --git a/docs/pitching-script.md b/docs/PITCHING_SCRIPT.md similarity index 99% rename from docs/pitching-script.md rename to docs/PITCHING_SCRIPT.md index 3ed9ae1..aa1fd6e 100644 --- a/docs/pitching-script.md +++ b/docs/PITCHING_SCRIPT.md @@ -1,4 +1,4 @@ -# pitching-script.md +# PITCHING_SCRIPT.md # ReplWorks Documents diff --git a/frameworks/astro.md b/frameworks/ASTRO.md similarity index 99% rename from frameworks/astro.md rename to frameworks/ASTRO.md index e0fe749..210a2b1 100644 --- a/frameworks/astro.md +++ b/frameworks/ASTRO.md @@ -1,4 +1,4 @@ -# astro.md +# ASTRO.md ## STACK diff --git a/frameworks/fastapi.md b/frameworks/FASTAPI.md similarity index 99% rename from frameworks/fastapi.md rename to frameworks/FASTAPI.md index bc098af..e40b8eb 100644 --- a/frameworks/fastapi.md +++ b/frameworks/FASTAPI.md @@ -1,4 +1,4 @@ -# fastapi.md +# FASTAPI.md ## STACK diff --git a/frameworks/go-cli.md b/frameworks/GO_CLI.md similarity index 100% rename from frameworks/go-cli.md rename to frameworks/GO_CLI.md diff --git a/frameworks/nextjs.md b/frameworks/NEXTJS.md similarity index 99% rename from frameworks/nextjs.md rename to frameworks/NEXTJS.md index 11c6a48..37850d1 100644 --- a/frameworks/nextjs.md +++ b/frameworks/NEXTJS.md @@ -1,4 +1,4 @@ -# nextjs.md +# NextJS.md ## STACK diff --git a/frameworks/node-cli.md b/frameworks/NODE_CLI.md similarity index 100% rename from frameworks/node-cli.md rename to frameworks/NODE_CLI.md diff --git a/frameworks/react-vite.md b/frameworks/REACT_VITE.md similarity index 99% rename from frameworks/react-vite.md rename to frameworks/REACT_VITE.md index 96c8f0b..94fff8f 100644 --- a/frameworks/react-vite.md +++ b/frameworks/REACT_VITE.md @@ -1,4 +1,4 @@ -# react-vite.md +# React-Vite.md ## STACK diff --git a/frameworks/vanilla.md b/frameworks/VANILLA.md similarity index 99% rename from frameworks/vanilla.md rename to frameworks/VANILLA.md index dd65051..323b2bb 100644 --- a/frameworks/vanilla.md +++ b/frameworks/VANILLA.md @@ -1,4 +1,4 @@ -# vanilla.md +# Vanilla.md ## STACK diff --git a/prompts/ARCHITECTURE_PROMPT.txt b/prompts/ARCHITECTURE_PROMPT.txt index 25d894f..1f01c71 100644 --- a/prompts/ARCHITECTURE_PROMPT.txt +++ b/prompts/ARCHITECTURE_PROMPT.txt @@ -1,8 +1,8 @@ -Generate architecture.md. +Generate ARCHITECTURE.md. -Assume product.md already exists and is correct. +Assume PRODUCT_SPEC.md already exists and is correct. -The purpose of architecture.md is to define: +The purpose of ARCHITECTURE.md is to define: ```text How the product works internally. diff --git a/prompts/PRODUCT_SPEC_PROMPT.txt b/prompts/PRODUCT_SPEC_PROMPT.txt index eda85dc..47e8f97 100644 --- a/prompts/PRODUCT_SPEC_PROMPT.txt +++ b/prompts/PRODUCT_SPEC_PROMPT.txt @@ -1,8 +1,8 @@ -Generate product.md. +Generate PRODUCT_SPEC.md. Assume all product discovery and idea validation are already complete. -The purpose of product.md is to define: +The purpose of PRODUCT_SPEC.md is to define: ```text What the product is. diff --git a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt index f324f71..2d53db0 100644 --- a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt +++ b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt @@ -1,8 +1,8 @@ Review the following documents together: -- product.md -- architecture.md -- framework.md +- PRODUCT_SPEC.md +- TECH_STACK.md +- ARCHITECTURE.md Assume you are responsible for implementing the entire product. diff --git a/prompts/TASKS_PROMPT.txt b/prompts/TASKS_PROMPT.txt index ef5c117..787058f 100644 --- a/prompts/TASKS_PROMPT.txt +++ b/prompts/TASKS_PROMPT.txt @@ -1,18 +1,18 @@ -Generate tasks.md. +Generate TASKS.md. -Assume product.md exists. +Assume PRODUCT_SPEC.md exists. -Assume architecture.md exists. +Assume ARCHITECTURE.md exists. -Assume framework.md exists. +Assume TECH_STACK.md exists. -The purpose of tasks.md is to define: +The purpose of TASKS.md is to define: ```text What remains to be implemented. ``` -tasks.md is an execution checklist. +TASKS.md is an execution checklist. Do not describe architecture. diff --git a/prompts/FRAMEWORK_DISCOVERY.txt b/prompts/TECH_STACK_DISCOVERY.txt similarity index 97% rename from prompts/FRAMEWORK_DISCOVERY.txt rename to prompts/TECH_STACK_DISCOVERY.txt index c0c15f8..8d97f4c 100644 --- a/prompts/FRAMEWORK_DISCOVERY.txt +++ b/prompts/TECH_STACK_DISCOVERY.txt @@ -1,4 +1,4 @@ -Assume product.md and architecture.md already exist and are correct. +Assume PRODUCT_SPEC.md and ARCHITECTURE.md already exist and are correct. The purpose of this task is NOT to generate framework.md. diff --git a/prompts/FRAMEWORK_PROMPT.txt b/prompts/TECH_STACK_PROMPT.txt similarity index 77% rename from prompts/FRAMEWORK_PROMPT.txt rename to prompts/TECH_STACK_PROMPT.txt index b64cf24..3abc59a 100644 --- a/prompts/FRAMEWORK_PROMPT.txt +++ b/prompts/TECH_STACK_PROMPT.txt @@ -1,10 +1,10 @@ -Generate framework.md. +Generate TECH_STACK.md. -Assume product.md and architecture.md already exist and are correct. +Assume PRODUCT.md and architecture.md already exist and are correct. -The purpose of framework.md is to eliminate implementation ambiguity. +The purpose of TECH_STACK.md is to eliminate implementation ambiguity. -framework.md defines implementation constraints only. +TECH_STACK.md defines implementation constraints only. Do not infer undecided technologies.