From 8821569d492acaab270cdaa63cff8507bf208e30 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Thu, 2 Jul 2026 15:24:28 +0900 Subject: [PATCH 1/2] docs: convert filename as kebab --- .repl/agent.md | 128 ++++++ ARCHITECTURE.md => .repl/architecture.md | 16 +- TASKS.md => .repl/tasks.md | 16 +- AGENTS.md | 4 +- AI_MEMORY.md | 24 +- README.md | 16 +- builtin/agent.md | 128 ++++++ docs/IDEAS.md | 12 +- ...{PITCHING_SCRIPT.md => pitching-script.md} | 8 +- frameworks/{GOLANG_CLI.md => go-cli.md} | 6 +- frameworks/node-cli.md | 371 ++++++++++++++++++ frameworks/{REACT_VITE.md => react-vite.md} | 0 prompts/AI_MEMORY_PROMPT.md | 11 - prompts/ARCHITECTURE_PROMPT.md | 63 --- prompts/BLOG_PROMPT.md | 55 --- prompts/DEVELOPMENT_LOG_PROMPT.md | 24 -- prompts/IDEAS_PROMPT.md | 31 -- prompts/JOURNAL_PROMPT.md | 35 -- prompts/PITCHING_SCRIPT_PROMPT.md | 37 -- prompts/PRODUCT_SPEC_PROMPT.md | 63 --- .../REVIEW_IMPLEMENTATION_READINESS_PROMPT.md | 59 --- prompts/TASKS_PROMPT.md | 71 ---- 22 files changed, 678 insertions(+), 500 deletions(-) create mode 100644 .repl/agent.md rename ARCHITECTURE.md => .repl/architecture.md (93%) rename TASKS.md => .repl/tasks.md (91%) create mode 100644 builtin/agent.md rename docs/{PITCHING_SCRIPT.md => pitching-script.md} (96%) rename frameworks/{GOLANG_CLI.md => go-cli.md} (97%) create mode 100644 frameworks/node-cli.md rename frameworks/{REACT_VITE.md => react-vite.md} (100%) delete mode 100644 prompts/AI_MEMORY_PROMPT.md delete mode 100644 prompts/ARCHITECTURE_PROMPT.md delete mode 100644 prompts/BLOG_PROMPT.md delete mode 100644 prompts/DEVELOPMENT_LOG_PROMPT.md delete mode 100644 prompts/IDEAS_PROMPT.md delete mode 100644 prompts/JOURNAL_PROMPT.md delete mode 100644 prompts/PITCHING_SCRIPT_PROMPT.md delete mode 100644 prompts/PRODUCT_SPEC_PROMPT.md delete mode 100644 prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md delete mode 100644 prompts/TASKS_PROMPT.md diff --git a/.repl/agent.md b/.repl/agent.md new file mode 100644 index 0000000..32fdc17 --- /dev/null +++ b/.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 diff --git a/ARCHITECTURE.md b/.repl/architecture.md similarity index 93% rename from ARCHITECTURE.md rename to .repl/architecture.md index 60dd948..0e5f52d 100644 --- a/ARCHITECTURE.md +++ b/.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 diff --git a/TASKS.md b/.repl/tasks.md similarity index 91% rename from TASKS.md rename to .repl/tasks.md index 06b6bb7..d0f4952 100644 --- a/TASKS.md +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index 105ad23..11224fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,8 +80,8 @@ PROJECT DOCUMENTS Examples: -- ARCHITECTURE.md -- TASKS.md +- architecture.md +- tasks.md Purpose: diff --git a/AI_MEMORY.md b/AI_MEMORY.md index 9c58a93..82798ac 100644 --- a/AI_MEMORY.md +++ b/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: diff --git a/README.md b/README.md index 504cbc6..55c2d11 100644 --- a/README.md +++ b/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 diff --git a/builtin/agent.md b/builtin/agent.md new file mode 100644 index 0000000..32fdc17 --- /dev/null +++ b/builtin/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 diff --git a/docs/IDEAS.md b/docs/IDEAS.md index 0a94688..2c70654 100644 --- a/docs/IDEAS.md +++ b/docs/IDEAS.md @@ -117,22 +117,22 @@ AI는 추측하지 않는다. ```text AGENTS.md -ARCHITECTURE.md -TASKS.md +architecture.md +tasks.md AI_MEMORY.md -FRAMEWORK.md +framework.md ``` ### AGENTS.md AI 에이전트의 행동 규칙 -### ARCHITECTURE.md +### architecture.md 시스템 구조 및 설계 -### TASKS.md +### tasks.md 현재 작업 목록 @@ -140,7 +140,7 @@ AI 에이전트의 행동 규칙 제품 비전 및 장기 컨텍스트 -### FRAMEWORK.md +### framework.md 현재 프로젝트의 기술 스택 및 개발 규칙 diff --git a/docs/PITCHING_SCRIPT.md b/docs/pitching-script.md similarity index 96% rename from docs/PITCHING_SCRIPT.md rename to docs/pitching-script.md index e76c883..aa1fd6e 100644 --- a/docs/PITCHING_SCRIPT.md +++ b/docs/pitching-script.md @@ -68,9 +68,9 @@ ReplWorks Documents는 이 문제를 해결하기 위해 만들어졌습니다. ```text AGENTS.md -FRAMEWORK.md -ARCHITECTURE.md -TASKS.md +framework.md +architecture.md +tasks.md AI_MEMORY.md ``` @@ -82,7 +82,7 @@ AI를 위한 문서입니다. 예를 들어 React/Vite 프로젝트라면 -FRAMEWORK.md 안에 다음과 같은 규칙이 들어갑니다. +framework.md 안에 다음과 같은 규칙이 들어갑니다. - React 19 - Vite diff --git a/frameworks/GOLANG_CLI.md b/frameworks/go-cli.md similarity index 97% rename from frameworks/GOLANG_CLI.md rename to frameworks/go-cli.md index daa5f9e..5430d3d 100644 --- a/frameworks/GOLANG_CLI.md +++ b/frameworks/go-cli.md @@ -1,4 +1,4 @@ -# FRAMEWORK.md +# framework.md # AI Issue Publisher Framework @@ -6,9 +6,9 @@ This document defines implementation constraints. -PRODUCT_SPEC.md defines what must be built. +product.md defines what must be built. -FRAMEWORK.md defines how it must be built. +framework.md defines how it must be built. Implementations must follow this document exactly. diff --git a/frameworks/node-cli.md b/frameworks/node-cli.md new file mode 100644 index 0000000..572211f --- /dev/null +++ b/frameworks/node-cli.md @@ -0,0 +1,371 @@ +# framework.md + +## Purpose + +This document defines the implementation framework for all projects using the following stack: + +- Node.js +- TypeScript +- CLI-based execution +- Playwright-based browser automation + +This document is a strict implementation contract. + +All implementation must comply with this document. + +If any conflict exists between documents: + +> framework.md takes priority over all other specifications except IMPLEMENTATION_CONSTITUTION.md. + +--- + +## Stack Definition (Immutable) + +All projects MUST use the following stack: + +- Language: TypeScript +- Runtime: Node.js +- Browser Automation: Playwright +- Package Manager: pnpm (recommended) + +Rules: + +- Do not use JavaScript without TypeScript +- Do not use alternative runtimes (Bun, Deno, etc.) +- Do not replace Playwright with other automation tools +- Do not mix multiple runtimes +- Do not assume framework defaults + +--- + +## Version Lock (STRICT) + +All versions MUST be explicitly pinned. + +No “latest”, “stable”, or “recommended” assumptions are allowed. + +### Node.js + +- Node.js: 20.x LTS (exact version must be pinned per repository) + +### TypeScript + +- TypeScript: 5.x (minor version must be explicitly pinned per repository) + +### Playwright + +- Playwright: 1.4x.x (exact version must be pinned per repository) + +### pnpm + +- pnpm: 9.x (exact version must be pinned per repository) + +Rules: + +- No automatic upgrades +- No implicit version resolution +- No dependency drift allowed +- All lockfiles are considered authoritative +- Any version mismatch is a build failure condition + +--- + +## CLI Application Model + +All applications MUST be CLI-first systems. + +Requirements: + +- Single CLI entry point +- Command-driven execution model +- No GUI dependency for core execution +- No daemon dependency for runtime behavior + +Standard commands: + +- `start` +- `stop` +- `status` +- `run ` + +All commands must be deterministic and side-effect controlled. + +--- + +## Project Structure Convention + +All projects MUST follow this structure: + +```text +src/ + cli/ # command entry layer + core/ # orchestration and business logic + browser/ # Playwright automation layer + extractors/ # DOM parsing and message extraction + router/ # decision logic + missions/ # state management + adapters/ # external system integrations + utils/ # shared utilities +``` + +Rules: + +- Each directory must have a single responsibility +- No cross-domain logic between unrelated modules +- No hidden directories +- No generic buckets like utils/shared unless explicitly justified +- Structure must reflect system responsibilities exactly + +--- + +## Dependency Direction Rules + +Strict dependency flow: + +```text +cli → core → router → missions +core → browser → extractors +core → adapters +adapters → browser +``` + +Rules: + +- No circular dependencies +- No reverse-layer imports +- No bypassing core orchestration layer +- No hidden coupling between modules + +Any violation is invalid implementation. + +--- + +## Playwright Usage Rules + +Playwright is the ONLY allowed browser automation tool. + +Rules: + +- All interactions must simulate human behavior +- No API-level integration with external LLM providers +- No hidden DOM hooks or internal APIs +- No parallel uncontrolled sessions + +Allowed actions: + +- click +- type +- paste +- wait +- observe + +All automation must be observable and reproducible. + +--- + +## TypeScript Rules + +Strict TypeScript mode is mandatory. + +Requirements: + +- strict: true +- noImplicitAny: true +- explicit typing for all core domain logic + +Forbidden: + +- any (unless explicitly justified) +- unsafe type assertions +- runtime type guessing without validation + +Types must reflect runtime reality. + +--- + +## CLI Framework Rules + +A structured CLI framework MUST be used. + +Recommended: + +- oclif (preferred) + +Rules: + +- Commands must be modular +- No inline command logic in entry files +- No ad-hoc argument parsing +- Each command must be independently testable + +--- + +## Configuration Rules + +Configuration MUST be externalized. + +Standard location: + +```text +~/.config//config.yaml +``` + +Rules: + +- Configuration must be optional at startup +- Defaults must always be valid +- No hardcoded environment assumptions +- No implicit global configuration state + +--- + +## Secrets Rules + +Strict prohibition: + +- No secrets in source code +- No secrets in configuration files +- No secrets in logs + +Allowed storage: + +- environment variables only +- system keychain (if explicitly defined per project) + +--- + +## Logging Rules + +Logging must be: + +- structured +- minimal +- non-sensitive + +Forbidden: + +- tokens +- credentials +- session data containing sensitive information + +Logs must support debugging without leaking secrets. + +--- + +## Error Handling Rules + +All errors MUST be: + +- explicit +- descriptive +- actionable + +Forbidden: + +- silent failures +- generic errors +- hidden fallback logic + +Each error must include: + +- cause +- context +- recovery guidance + +--- + +## Testing Rules + +All tests MUST be: + +- deterministic +- isolated +- repeatable + +Forbidden: + +- network access +- real browser sessions +- live external service calls + +All external dependencies must be mocked. + +--- + +## External Integration Rules + +All external systems (e.g. GPT, Gemini) MUST be accessed through adapters. + +Rules: + +- business logic must not directly depend on Playwright +- adapters must encapsulate all external interaction logic +- adapters must be replaceable without affecting core logic + +--- + +## Dependency Management Rules + +- Minimize dependencies +- Prefer standard library +- Add dependencies only when strictly necessary +- Avoid overlapping libraries + +Each dependency must be justified by: + +- necessity +- maintenance status +- non-duplication + +--- + +## Build & Distribution Rules + +- Must produce a standalone CLI distribution +- Must not require runtime compilation in production +- Must support macOS, Linux, Windows + +Distribution method: + +- GitHub Releases + +--- + +## Architecture Stability Rules + +Once defined: + +- directory structure must not change arbitrarily +- dependency flow must remain stable +- new features must conform to existing structure + +Refactoring is allowed only if: + +- framework.md is updated accordingly +- IMPLEMENTATION_CONSTITUTION.md is updated if required + +--- + +## Framework Invariants + +The following conditions MUST always remain true: + +- CLI-first execution model +- TypeScript strict mode enforced +- Playwright is the only browser automation tool +- All external integrations are isolated via adapters +- Dependency direction rules are enforced +- No hidden architecture layers exist +- No runtime ambiguity in versioned dependencies + +Any violation is considered a framework-level failure. + +--- + +## Final Rule + +If ambiguity exists: + +> Always choose deterministic behavior over flexible interpretation. + +Flexibility is considered a source of implementation risk. diff --git a/frameworks/REACT_VITE.md b/frameworks/react-vite.md similarity index 100% rename from frameworks/REACT_VITE.md rename to frameworks/react-vite.md diff --git a/prompts/AI_MEMORY_PROMPT.md b/prompts/AI_MEMORY_PROMPT.md deleted file mode 100644 index 92d7bf7..0000000 --- a/prompts/AI_MEMORY_PROMPT.md +++ /dev/null @@ -1,11 +0,0 @@ -# AI Memory Prompt - -Generate AI_MEMORY.md from this conversation. - -Preserve decision-making context. - -Focus on why decisions were made. - -Assume the document will be provided to a future AI session. - -Optimize for context recovery, not human readability. diff --git a/prompts/ARCHITECTURE_PROMPT.md b/prompts/ARCHITECTURE_PROMPT.md deleted file mode 100644 index ebe204f..0000000 --- a/prompts/ARCHITECTURE_PROMPT.md +++ /dev/null @@ -1,63 +0,0 @@ -# ARCHITECTURE_PROMPT.md - -Generate ARCHITECTURE.md. - -Assume PRODUCT_SPEC.md already exists and is correct. - -The purpose of ARCHITECTURE.md is to define: - -```text -How the product works internally. -How responsibilities are separated. -How information flows through the system. -Which invariants must always remain true. -``` - -Do not describe implementation technologies. - -Do not describe frameworks. - -Do not describe programming languages. - -Do not describe libraries. - -Do not describe deployment. - -Do not describe coding conventions. - -Architecture must remain technology-agnostic. - -The document must include: - -- Purpose -- Core Concepts -- System Flow -- Components -- Component Responsibilities -- Responsibility Boundaries -- Data Flow -- Architectural Rules -- Failure Boundaries -- Non-Goals -- Architectural Invariants - -Every component must have: - -- Responsibilities -- Inputs -- Outputs -- Explicit ownership boundaries - -Identify: - -- missing responsibilities -- conflicting responsibilities -- ambiguous flows - -Resolve them before generating the document. - -Prefer clear ownership over abstraction. - -Optimize for implementation certainty. - -The document is intended for AI implementation, not human documentation. diff --git a/prompts/BLOG_PROMPT.md b/prompts/BLOG_PROMPT.md deleted file mode 100644 index c8e64a1..0000000 --- a/prompts/BLOG_PROMPT.md +++ /dev/null @@ -1,55 +0,0 @@ -# Blog Prompt - -Generate a blog post draft from this discussion. - -Audience: - -- developers using AI for software development -- technical founders -- AI-assisted development practitioners - -Focus on: - -- the problem that occurred -- why it was difficult to diagnose -- what was discovered -- what changed in my thinking -- practical lessons learned - -Do not write as a tutorial. - -Do not write as marketing. - -Write as an engineering journal. - -Use first-person perspective. - -Preserve uncertainty where appropriate. - -Include: - -# What Happened - -# What I Initially Thought - -# What I Discovered - -# Why This Matters - -# What I Changed - -# Future Work - -The goal is not to teach. - -The goal is to document a real learning experience. - -Future readers should feel: - -"I encountered the same problem." - -Length: - -800–1500 words. - -Output markdown only. diff --git a/prompts/DEVELOPMENT_LOG_PROMPT.md b/prompts/DEVELOPMENT_LOG_PROMPT.md deleted file mode 100644 index d1b0171..0000000 --- a/prompts/DEVELOPMENT_LOG_PROMPT.md +++ /dev/null @@ -1,24 +0,0 @@ -# Development Log Prompt - -I am building software with AI. - -Transform this discussion into a public development log. - -Requirements: - -- Preserve the original problem. -- Explain the investigation process. -- Explain dead ends and failed ideas. -- Highlight the key insight. -- Explain how it affects future projects. -- Include concrete examples from the discussion. - -Write for developers who are experimenting with AI coding tools. - -Do not present the final insight immediately. - -Let the reader follow the discovery process. - -Use markdown. - -Target length: 5–10 minute read. diff --git a/prompts/IDEAS_PROMPT.md b/prompts/IDEAS_PROMPT.md deleted file mode 100644 index 532184a..0000000 --- a/prompts/IDEAS_PROMPT.md +++ /dev/null @@ -1,31 +0,0 @@ -# Ideas Prompt - -Generate IDEAS.md from this conversation. - -This document is intended for human consumption. - -Record only information explicitly discussed during the conversation. - -Do not expand the idea. - -Do not invent features. - -Do not invent business models. - -Do not invent technical solutions. - -Do not invent implementation details. - -Do not add assumptions. - -Do not add recommendations. - -Do not add future possibilities unless explicitly discussed. - -Preserve the original intent. - -Focus on capturing the idea exactly as discussed. - -If information was not mentioned in the conversation, omit it. - -Optimize for accurate idea preservation rather than idea improvement. diff --git a/prompts/JOURNAL_PROMPT.md b/prompts/JOURNAL_PROMPT.md deleted file mode 100644 index 1736ded..0000000 --- a/prompts/JOURNAL_PROMPT.md +++ /dev/null @@ -1,35 +0,0 @@ -# Development Journal Prompt - -Convert this discussion into a REPLWorks Development Journal entry. - -Writing style: - -- honest -- technical -- reflective - -Avoid: - -- hype -- AI marketing language -- exaggerated claims - -Focus on: - -1. What problem blocked progress -2. What assumptions turned out to be wrong -3. What insight emerged -4. How the insight changed REPLWorks -5. What remains unsolved - -End with: - -"Current hypothesis" - -and - -"Things I still don't know" - -The goal is to document learning, not conclusions. - -Output markdown. diff --git a/prompts/PITCHING_SCRIPT_PROMPT.md b/prompts/PITCHING_SCRIPT_PROMPT.md deleted file mode 100644 index 332483b..0000000 --- a/prompts/PITCHING_SCRIPT_PROMPT.md +++ /dev/null @@ -1,37 +0,0 @@ -# Pitching Script Prompt - -Generate PITCHING_SCRIPT.md from: - -- IDEAS.md -- this conversation - -Target Audience: - - - -This document is intended for human consumption. - -The goal is persuasion. - -Use information explicitly discussed during the conversation. - -You may expand: - -- market opportunity -- target users -- business potential -- revenue potential -- competitive advantages -- growth opportunities - -Only when they are supported by the conversation context. - -Do not invent unrealistic claims. - -Do not invent unsupported numbers. - -Clearly distinguish assumptions from established facts. - -Optimize for credibility, persuasion, and audience relevance. - -Adapt the structure and messaging for the target audience. diff --git a/prompts/PRODUCT_SPEC_PROMPT.md b/prompts/PRODUCT_SPEC_PROMPT.md deleted file mode 100644 index 2c9750c..0000000 --- a/prompts/PRODUCT_SPEC_PROMPT.md +++ /dev/null @@ -1,63 +0,0 @@ -# PRODUCT_SPEC_PROMPT.md - -Generate PRODUCT_SPEC.md. - -Assume all product discovery and idea validation are already complete. - -The purpose of PRODUCT_SPEC.md is to define: - -```text -What the product is. -What the product does. -What the user can do. -What success means. -``` - -Do not describe implementation. - -Do not describe architecture. - -Do not describe technologies. - -Do not describe frameworks. - -Do not describe programming languages. - -Do not describe databases. - -Do not describe APIs. - -Do not describe internal components. - -Do not describe directory structures. - -Focus only on externally observable product behavior. - -The document should be sufficient for a product manager to approve the product scope. - -The document must include: - -- Purpose -- Problem -- Product Goals -- Users -- Inputs -- Outputs -- Functional Requirements -- User Flows -- Error Conditions -- Non-Goals -- Acceptance Criteria -- Success Criteria - -Do not propose improvements. - -Do not add features that were not discussed. - -Do not expand the scope. - -Prefer explicit requirements over explanations. - -Optimize for implementation certainty. - -The document is intended for AI implementation, not human marketing. diff --git a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md deleted file mode 100644 index 873dd6e..0000000 --- a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.md +++ /dev/null @@ -1,59 +0,0 @@ -# REVIEW_IMPLEMENTATION_READINESS_PROMPT.md - -Review the following documents together: - -- PRODUCT_SPEC.md -- ARCHITECTURE.md -- FRAMEWORK.md - -Assume you are responsible for implementing the entire product. - -Assume no additional information will be provided. - -Your goal is to determine whether implementation can begin with confidence. - -Generate only questions. - -Do not answer questions. - -Do not suggest improvements. - -Do not suggest new features. - -Do not redesign the product. - -Do not modify requirements. - -Focus on identifying: - -- missing requirements -- missing architectural responsibilities -- missing implementation constraints -- ambiguous behavior -- conflicting definitions -- undefined ownership -- undefined flows -- undefined inputs -- undefined outputs -- contradictions between documents - -Treat the three documents as a single implementation contract. - -A question is valid only if it blocks implementation certainty. - -Ignore: - -- personal preferences -- alternative technologies -- feature ideas -- product strategy - -Output only a numbered list of questions. - -If no blocking questions exist, output: - -```text -Implementation can begin with high confidence. -``` - -Optimize for implementation certainty. diff --git a/prompts/TASKS_PROMPT.md b/prompts/TASKS_PROMPT.md deleted file mode 100644 index d296803..0000000 --- a/prompts/TASKS_PROMPT.md +++ /dev/null @@ -1,71 +0,0 @@ -# TASKS_PROMPT.md - -Generate TASKS.md. - -Assume PRODUCT_SPEC.md exists. - -Assume ARCHITECTURE.md exists. - -Assume FRAMEWORK.md exists. - -The purpose of TASKS.md is to define: - -```text -What remains to be implemented. -``` - -TASKS.md is an execution checklist. - -Do not describe architecture. - -Do not describe technologies. - -Do not describe frameworks. - -Do not describe implementation details. - -Do not reference specific classes. - -Do not reference specific files. - -Do not reference specific libraries. - -Generate implementation tasks only. - -Tasks should represent user-visible capabilities or architectural milestones. - -Each task must be independently completable. - -Each task must be independently testable. - -Organize tasks into phases. - -For each phase: - -- define tasks -- define acceptance criteria - -Tasks must: - -- be actionable -- be verifiable -- be implementation-independent - -Avoid: - -- implementation steps -- code-level instructions -- framework-specific instructions - -Include: - -- MVP -- Future - -Acceptance criteria must be objective. - -A task is complete only when acceptance criteria are satisfied. - -Optimize for autonomous execution by AI systems. - -The document is intended for AI implementation, not human project management. From b96f1fe8a2163b093c0750702bf0f0f2c1fb56e6 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Thu, 2 Jul 2026 15:25:02 +0900 Subject: [PATCH 2/2] docs: convert prompts extension from `.md` to `.txt` --- prompts/AI_MEMORY_PROMPT.txt | 9 + prompts/ARCHITECTURE_PROMPT.txt | 61 +++++ prompts/BLOG_PROMPT.txt | 53 +++++ prompts/DEVELOPMENT_LOG_PROMPT.txt | 22 ++ prompts/FRAMEWORK_DISCOVERY.txt | 213 ++++++++++++++++++ prompts/FRAMEWORK_PROMPT.md | 36 --- prompts/FRAMEWORK_PROMPT.txt | 40 ++++ prompts/IDEAS_PROMPT.txt | 29 +++ prompts/JOURNAL_PROMPT.txt | 33 +++ prompts/PITCHING_SCRIPT_PROMPT.txt | 35 +++ prompts/PRODUCT_SPEC_PROMPT.txt | 61 +++++ ...REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt | 57 +++++ prompts/TASKS_PROMPT.txt | 69 ++++++ 13 files changed, 682 insertions(+), 36 deletions(-) create mode 100644 prompts/AI_MEMORY_PROMPT.txt create mode 100644 prompts/ARCHITECTURE_PROMPT.txt create mode 100644 prompts/BLOG_PROMPT.txt create mode 100644 prompts/DEVELOPMENT_LOG_PROMPT.txt create mode 100644 prompts/FRAMEWORK_DISCOVERY.txt delete mode 100644 prompts/FRAMEWORK_PROMPT.md create mode 100644 prompts/FRAMEWORK_PROMPT.txt create mode 100644 prompts/IDEAS_PROMPT.txt create mode 100644 prompts/JOURNAL_PROMPT.txt create mode 100644 prompts/PITCHING_SCRIPT_PROMPT.txt create mode 100644 prompts/PRODUCT_SPEC_PROMPT.txt create mode 100644 prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt create mode 100644 prompts/TASKS_PROMPT.txt diff --git a/prompts/AI_MEMORY_PROMPT.txt b/prompts/AI_MEMORY_PROMPT.txt new file mode 100644 index 0000000..17b7cee --- /dev/null +++ b/prompts/AI_MEMORY_PROMPT.txt @@ -0,0 +1,9 @@ +Generate AI_MEMORY.md from this conversation. + +Preserve decision-making context. + +Focus on why decisions were made. + +Assume the document will be provided to a future AI session. + +Optimize for context recovery, not human readability. diff --git a/prompts/ARCHITECTURE_PROMPT.txt b/prompts/ARCHITECTURE_PROMPT.txt new file mode 100644 index 0000000..25d894f --- /dev/null +++ b/prompts/ARCHITECTURE_PROMPT.txt @@ -0,0 +1,61 @@ +Generate architecture.md. + +Assume product.md already exists and is correct. + +The purpose of architecture.md is to define: + +```text +How the product works internally. +How responsibilities are separated. +How information flows through the system. +Which invariants must always remain true. +``` + +Do not describe implementation technologies. + +Do not describe frameworks. + +Do not describe programming languages. + +Do not describe libraries. + +Do not describe deployment. + +Do not describe coding conventions. + +Architecture must remain technology-agnostic. + +The document must include: + +- Purpose +- Core Concepts +- System Flow +- Components +- Component Responsibilities +- Responsibility Boundaries +- Data Flow +- Architectural Rules +- Failure Boundaries +- Non-Goals +- Architectural Invariants + +Every component must have: + +- Responsibilities +- Inputs +- Outputs +- Explicit ownership boundaries + +Identify: + +- missing responsibilities +- conflicting responsibilities +- ambiguous flows + +Resolve them before generating the document. + +Prefer clear ownership over abstraction. + +Optimize for implementation certainty. + +The document is intended for AI implementation, not human documentation. diff --git a/prompts/BLOG_PROMPT.txt b/prompts/BLOG_PROMPT.txt new file mode 100644 index 0000000..4a75de2 --- /dev/null +++ b/prompts/BLOG_PROMPT.txt @@ -0,0 +1,53 @@ +Generate a blog post draft from this discussion. + +Audience: + +- developers using AI for software development +- technical founders +- AI-assisted development practitioners + +Focus on: + +- the problem that occurred +- why it was difficult to diagnose +- what was discovered +- what changed in my thinking +- practical lessons learned + +Do not write as a tutorial. + +Do not write as marketing. + +Write as an engineering journal. + +Use first-person perspective. + +Preserve uncertainty where appropriate. + +Include: + +# What Happened + +# What I Initially Thought + +# What I Discovered + +# Why This Matters + +# What I Changed + +# Future Work + +The goal is not to teach. + +The goal is to document a real learning experience. + +Future readers should feel: + +"I encountered the same problem." + +Length: + +800–1500 words. + +Output markdown only. diff --git a/prompts/DEVELOPMENT_LOG_PROMPT.txt b/prompts/DEVELOPMENT_LOG_PROMPT.txt new file mode 100644 index 0000000..082fe31 --- /dev/null +++ b/prompts/DEVELOPMENT_LOG_PROMPT.txt @@ -0,0 +1,22 @@ +I am building software with AI. + +Transform this discussion into a public development log. + +Requirements: + +- Preserve the original problem. +- Explain the investigation process. +- Explain dead ends and failed ideas. +- Highlight the key insight. +- Explain how it affects future projects. +- Include concrete examples from the discussion. + +Write for developers who are experimenting with AI coding tools. + +Do not present the final insight immediately. + +Let the reader follow the discovery process. + +Use markdown. + +Target length: 5–10 minute read. diff --git a/prompts/FRAMEWORK_DISCOVERY.txt b/prompts/FRAMEWORK_DISCOVERY.txt new file mode 100644 index 0000000..c0c15f8 --- /dev/null +++ b/prompts/FRAMEWORK_DISCOVERY.txt @@ -0,0 +1,213 @@ +Assume product.md and architecture.md already exist and are correct. + +The purpose of this task is NOT to generate framework.md. + +The purpose is to discover every implementation decision required to generate framework.md. + +Do not infer missing decisions. + +Do not assume defaults. + +Do not recommend technologies unless explicitly asked. + +Do not generate framework.md. + +Do not generate code. + +Do not evaluate alternatives unless explicitly requested. + +--- + +Your job is to identify implementation decisions that are still undefined. + +For each missing decision: + +- explain why the decision is required, +- explain which parts of the system depend on it, +- ask a question, +- wait for an answer. + +Do not continue past unanswered decisions. + +Do not batch unrelated decisions. + +Ask one decision at a time. + +Do not make assumptions. + +--- + +The discovery process must cover: + +## Platform + +Determine: + +- target platforms +- runtime constraints +- distribution targets + +--- + +## Programming Language + +Determine: + +- implementation language + +--- + +## UI Framework + +Determine: + +- user interface framework + +--- + +## Rendering System + +Determine: + +- rendering approach +- graphics constraints + +--- + +## State Management Style + +Determine: + +- state ownership model +- mutation model + +--- + +## Persistence + +Determine: + +- persistence requirements +- storage boundaries + +--- + +## Directory Structure + +Determine: + +- project organization rules +- ownership boundaries + +--- + +## Dependency Rules + +Determine: + +- external dependency policy +- dependency ownership + +--- + +## Testing + +Determine: + +- required test types +- coverage expectations + +--- + +## Configuration + +Determine: + +- configuration ownership +- environment separation rules + +--- + +## Logging + +Determine: + +- logging rules +- sensitive information rules + +--- + +## Security + +Determine: + +- secret handling rules +- input validation rules + +--- + +## Deployment + +Determine: + +- deployment targets +- release environments + +--- + +## Build Rules + +Determine: + +- build variants +- build constraints + +--- + +## Performance Constraints + +Determine: + +- latency requirements +- throughput requirements +- memory constraints + +--- + +## Debugging + +Determine: + +- debugging capabilities +- observability requirements + +--- + +Output format: + +```text +MISSING DECISION + +Name: + + +Reason: + + +Affected Areas: +- ... + +Question: + + +WAITING FOR ANSWER +``` + +Rules: + +- Ask only one question at a time. +- Never assume missing decisions. +- Never generate framework.md. +- Never generate code. +- Never continue automatically. +- Wait after every answer. diff --git a/prompts/FRAMEWORK_PROMPT.md b/prompts/FRAMEWORK_PROMPT.md deleted file mode 100644 index 8c9cbee..0000000 --- a/prompts/FRAMEWORK_PROMPT.md +++ /dev/null @@ -1,36 +0,0 @@ -# GOLANG Cli Prompt - -Generate FRAMEWORK.md. - -Assume all technology decisions have already been made. - -Do not evaluate alternatives. - -Do not compare frameworks. - -Do not recommend different technologies. - -Generate an AI-oriented FRAMEWORK.md that constrains implementation. - -The document must: - -- define implementation rules -- define architectural constraints -- define directory structure -- define testing rules -- define deployment rules -- define configuration rules -- define security rules -- define framework-specific conventions -- define non-goals -- define architectural invariants - -Optimize for implementation consistency. - -The purpose of FRAMEWORK.md is to eliminate implementation ambiguity. - -If a decision has already been made, encode it as a rule. - -Prefer explicit constraints over explanations. - -The document is intended for AI implementation, not human learning. diff --git a/prompts/FRAMEWORK_PROMPT.txt b/prompts/FRAMEWORK_PROMPT.txt new file mode 100644 index 0000000..b64cf24 --- /dev/null +++ b/prompts/FRAMEWORK_PROMPT.txt @@ -0,0 +1,40 @@ +Generate framework.md. + +Assume product.md and architecture.md already exist and are correct. + +The purpose of framework.md is to eliminate implementation ambiguity. + +framework.md defines implementation constraints only. + +Do not infer undecided technologies. + +Do not assume technology decisions have already been made. + +If required decisions are missing, stop and ask questions. + +Do not evaluate alternatives. + +Do not recommend technologies. + +When a decision has already been made, encode it as a rule. + +When a decision has not been made, do not invent one. + +The document must include: + +- implementation rules +- architectural constraints +- directory structure +- testing rules +- deployment rules +- configuration rules +- security rules +- framework-specific conventions +- non-goals +- architectural invariants + +Prefer explicit constraints over explanations. + +Optimize for implementation consistency. + +The document is intended for AI implementation, not human learning. diff --git a/prompts/IDEAS_PROMPT.txt b/prompts/IDEAS_PROMPT.txt new file mode 100644 index 0000000..1abc76e --- /dev/null +++ b/prompts/IDEAS_PROMPT.txt @@ -0,0 +1,29 @@ +Generate IDEAS.md from this conversation. + +This document is intended for human consumption. + +Record only information explicitly discussed during the conversation. + +Do not expand the idea. + +Do not invent features. + +Do not invent business models. + +Do not invent technical solutions. + +Do not invent implementation details. + +Do not add assumptions. + +Do not add recommendations. + +Do not add future possibilities unless explicitly discussed. + +Preserve the original intent. + +Focus on capturing the idea exactly as discussed. + +If information was not mentioned in the conversation, omit it. + +Optimize for accurate idea preservation rather than idea improvement. diff --git a/prompts/JOURNAL_PROMPT.txt b/prompts/JOURNAL_PROMPT.txt new file mode 100644 index 0000000..570e998 --- /dev/null +++ b/prompts/JOURNAL_PROMPT.txt @@ -0,0 +1,33 @@ +Convert this discussion into a REPLWorks Development Journal entry. + +Writing style: + +- honest +- technical +- reflective + +Avoid: + +- hype +- AI marketing language +- exaggerated claims + +Focus on: + +1. What problem blocked progress +2. What assumptions turned out to be wrong +3. What insight emerged +4. How the insight changed REPLWorks +5. What remains unsolved + +End with: + +"Current hypothesis" + +and + +"Things I still don't know" + +The goal is to document learning, not conclusions. + +Output markdown. diff --git a/prompts/PITCHING_SCRIPT_PROMPT.txt b/prompts/PITCHING_SCRIPT_PROMPT.txt new file mode 100644 index 0000000..3fe6f32 --- /dev/null +++ b/prompts/PITCHING_SCRIPT_PROMPT.txt @@ -0,0 +1,35 @@ +Generate PITCHING_SCRIPT.md from: + +- IDEAS.md +- this conversation + +Target Audience: + + + +This document is intended for human consumption. + +The goal is persuasion. + +Use information explicitly discussed during the conversation. + +You may expand: + +- market opportunity +- target users +- business potential +- revenue potential +- competitive advantages +- growth opportunities + +Only when they are supported by the conversation context. + +Do not invent unrealistic claims. + +Do not invent unsupported numbers. + +Clearly distinguish assumptions from established facts. + +Optimize for credibility, persuasion, and audience relevance. + +Adapt the structure and messaging for the target audience. diff --git a/prompts/PRODUCT_SPEC_PROMPT.txt b/prompts/PRODUCT_SPEC_PROMPT.txt new file mode 100644 index 0000000..eda85dc --- /dev/null +++ b/prompts/PRODUCT_SPEC_PROMPT.txt @@ -0,0 +1,61 @@ +Generate product.md. + +Assume all product discovery and idea validation are already complete. + +The purpose of product.md is to define: + +```text +What the product is. +What the product does. +What the user can do. +What success means. +``` + +Do not describe implementation. + +Do not describe architecture. + +Do not describe technologies. + +Do not describe frameworks. + +Do not describe programming languages. + +Do not describe databases. + +Do not describe APIs. + +Do not describe internal components. + +Do not describe directory structures. + +Focus only on externally observable product behavior. + +The document should be sufficient for a product manager to approve the product scope. + +The document must include: + +- Purpose +- Problem +- Product Goals +- Users +- Inputs +- Outputs +- Functional Requirements +- User Flows +- Error Conditions +- Non-Goals +- Acceptance Criteria +- Success Criteria + +Do not propose improvements. + +Do not add features that were not discussed. + +Do not expand the scope. + +Prefer explicit requirements over explanations. + +Optimize for implementation certainty. + +The document is intended for AI implementation, not human marketing. diff --git a/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt new file mode 100644 index 0000000..f324f71 --- /dev/null +++ b/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt @@ -0,0 +1,57 @@ +Review the following documents together: + +- product.md +- architecture.md +- framework.md + +Assume you are responsible for implementing the entire product. + +Assume no additional information will be provided. + +Your goal is to determine whether implementation can begin with confidence. + +Generate only questions. + +Do not answer questions. + +Do not suggest improvements. + +Do not suggest new features. + +Do not redesign the product. + +Do not modify requirements. + +Focus on identifying: + +- missing requirements +- missing architectural responsibilities +- missing implementation constraints +- ambiguous behavior +- conflicting definitions +- undefined ownership +- undefined flows +- undefined inputs +- undefined outputs +- contradictions between documents + +Treat the three documents as a single implementation contract. + +A question is valid only if it blocks implementation certainty. + +Ignore: + +- personal preferences +- alternative technologies +- feature ideas +- product strategy + +Output only a numbered list of questions. + +If no blocking questions exist, output: + +```text +Implementation can begin with high confidence. +``` + +Optimize for implementation certainty. diff --git a/prompts/TASKS_PROMPT.txt b/prompts/TASKS_PROMPT.txt new file mode 100644 index 0000000..ef5c117 --- /dev/null +++ b/prompts/TASKS_PROMPT.txt @@ -0,0 +1,69 @@ +Generate tasks.md. + +Assume product.md exists. + +Assume architecture.md exists. + +Assume framework.md exists. + +The purpose of tasks.md is to define: + +```text +What remains to be implemented. +``` + +tasks.md is an execution checklist. + +Do not describe architecture. + +Do not describe technologies. + +Do not describe frameworks. + +Do not describe implementation details. + +Do not reference specific classes. + +Do not reference specific files. + +Do not reference specific libraries. + +Generate implementation tasks only. + +Tasks should represent user-visible capabilities or architectural milestones. + +Each task must be independently completable. + +Each task must be independently testable. + +Organize tasks into phases. + +For each phase: + +- define tasks +- define acceptance criteria + +Tasks must: + +- be actionable +- be verifiable +- be implementation-independent + +Avoid: + +- implementation steps +- code-level instructions +- framework-specific instructions + +Include: + +- MVP +- Future + +Acceptance criteria must be objective. + +A task is complete only when acceptance criteria are satisfied. + +Optimize for autonomous execution by AI systems. + +The document is intended for AI implementation, not human project management.