diff --git a/.replworks/TECH_STACK.md b/.replworks/TECH_STACK.md index 210a2b1..a8a7cc1 100644 --- a/.replworks/TECH_STACK.md +++ b/.replworks/TECH_STACK.md @@ -4,7 +4,7 @@ REQUIRED -- Astro 6.x +- Astro 7.x - JavaScript OPTIONAL diff --git a/AGENTS.md b/AGENTS.md index 41ca53d..77c4500 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,12 +15,11 @@ Ignore all files under: -```text -docs/ -``` +- `/docs/**/*` +- `/content/**/*` -Never use files in docs/ as requirements. -Never implement features described only in docs/. +Never use files in `/docs/**/*` and `/content/**/*` as requirements. +Never implement features described only in `/docs/**/*` and `/content/**/*`. --- diff --git a/content/AGENTS.md b/content/AGENTS.md new file mode 100644 index 0000000..41ca53d --- /dev/null +++ b/content/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. diff --git a/content/prompts/AI_MEMORY_PROMPT.txt b/content/prompts/AI_MEMORY_PROMPT.txt new file mode 100644 index 0000000..17b7cee --- /dev/null +++ b/content/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/content/prompts/ARCHITECTURE_PROMPT.txt b/content/prompts/ARCHITECTURE_PROMPT.txt new file mode 100644 index 0000000..ae7e9e5 --- /dev/null +++ b/content/prompts/ARCHITECTURE_PROMPT.txt @@ -0,0 +1,61 @@ +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 tech stacks. + +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/content/prompts/BLOG_PROMPT.txt b/content/prompts/BLOG_PROMPT.txt new file mode 100644 index 0000000..4a75de2 --- /dev/null +++ b/content/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/content/prompts/DEVELOPMENT_LOG_PROMPT.txt b/content/prompts/DEVELOPMENT_LOG_PROMPT.txt new file mode 100644 index 0000000..082fe31 --- /dev/null +++ b/content/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/content/prompts/IDEAS_PROMPT.txt b/content/prompts/IDEAS_PROMPT.txt new file mode 100644 index 0000000..1abc76e --- /dev/null +++ b/content/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/content/prompts/JOURNAL_PROMPT.txt b/content/prompts/JOURNAL_PROMPT.txt new file mode 100644 index 0000000..570e998 --- /dev/null +++ b/content/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/content/prompts/PITCHING_SCRIPT_PROMPT.txt b/content/prompts/PITCHING_SCRIPT_PROMPT.txt new file mode 100644 index 0000000..3fe6f32 --- /dev/null +++ b/content/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/content/prompts/PRODUCT_SPEC_PROMPT.txt b/content/prompts/PRODUCT_SPEC_PROMPT.txt new file mode 100644 index 0000000..d88aea4 --- /dev/null +++ b/content/prompts/PRODUCT_SPEC_PROMPT.txt @@ -0,0 +1,61 @@ +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 tech stacks. + +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/content/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt b/content/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt new file mode 100644 index 0000000..2d53db0 --- /dev/null +++ b/content/prompts/REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt @@ -0,0 +1,57 @@ +Review the following documents together: + +- PRODUCT_SPEC.md +- TECH_STACK.md +- ARCHITECTURE.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/content/prompts/TASKS_PROMPT.txt b/content/prompts/TASKS_PROMPT.txt new file mode 100644 index 0000000..686f9ed --- /dev/null +++ b/content/prompts/TASKS_PROMPT.txt @@ -0,0 +1,69 @@ +Generate TASKS.md. + +Assume PRODUCT_SPEC.md exists. + +Assume ARCHITECTURE.md exists. + +Assume TECH_STACK.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 tech stacks. + +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 +- tech-stack-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. diff --git a/content/prompts/TECH_STACK_DISCOVERY.txt b/content/prompts/TECH_STACK_DISCOVERY.txt new file mode 100644 index 0000000..befd671 --- /dev/null +++ b/content/prompts/TECH_STACK_DISCOVERY.txt @@ -0,0 +1,213 @@ +Assume PRODUCT_SPEC.md and ARCHITECTURE.md already exist and are correct. + +The purpose of this task is NOT to generate TECH_STACK.md. + +The purpose is to discover every implementation decision required to generate TECH_STACK.md. + +Do not infer missing decisions. + +Do not assume defaults. + +Do not recommend technologies unless explicitly asked. + +Do not generate TECH_STACK.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 Tech stack + +Determine: + +- user interface tech stack + +--- + +## 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 TECH_STACK.md. +- Never generate code. +- Never continue automatically. +- Wait after every answer. diff --git a/content/prompts/TECH_STACK_PROMPT.txt b/content/prompts/TECH_STACK_PROMPT.txt new file mode 100644 index 0000000..203a87d --- /dev/null +++ b/content/prompts/TECH_STACK_PROMPT.txt @@ -0,0 +1,40 @@ +Generate TECH_STACK.md. + +Assume PRODUCT.md and architecture.md already exist and are correct. + +The purpose of TECH_STACK.md is to eliminate implementation ambiguity. + +TECH_STACK.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 +- tech-stack-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/content/tech-stacks/ASTRO.md b/content/tech-stacks/ASTRO.md new file mode 100644 index 0000000..0ca8e36 --- /dev/null +++ b/content/tech-stacks/ASTRO.md @@ -0,0 +1,302 @@ +# ASTRO.md + +## STACK + +REQUIRED + +- Astro 6.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- React 19.x +- MDX + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +TECH_STACK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_ASTRO_VERSION + +DO_NOT_GENERATE_CODE_FOR_OTHER_VERSIONS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +src/ +├── components/ +├── layouts/ +├── pages/ +├── content/ +├── images/ +├── data/ +├── utils/ +└── styles/ + +public/ + +astro.config.mjs +content.config.ts +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +FOLLOW_EXISTING_STRUCTURE_BEFORE_CREATING_NEW_STRUCTURE + +--- + +## FILE_PLACEMENT + +pages -> src/pages + +layouts -> src/layouts + +components -> src/components + +content -> src/content + +images -> src/images + +data -> src/data + +utilities -> src/utils + +styles -> src/styles + +static_assets -> public + +content_configuration -> content.config.ts + +astro_configuration -> astro.config.mjs + +DO_NOT_CREATE_COMPONENTS_OUTSIDE_DEFINED_LOCATIONS + +--- + +## ROUTING_RULES + +USE_FILE_BASED_ROUTING + +ROUTES_BELONG_IN_SRC_PAGES + +DO_NOT_CREATE_CUSTOM_ROUTING_SYSTEM + +FOLLOW_ASTRO_ROUTING_CONVENTIONS + +--- + +## COMPONENT_RULES + +USE_ASTRO_COMPONENTS_BY_DEFAULT + +PREFER_ASTRO_OVER_REACT + +USE_REACT_ONLY_WHEN_REQUIRED + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## CONTENT_RULES + +CONTENT_BELONGS_IN_SRC_CONTENT + +USE_CONTENT_COLLECTIONS + +CONTENT_CONFIG_IS_SOURCE_OF_TRUTH + +DO_NOT_STORE_CONTENT_IN_COMPONENTS + +DO_NOT_STORE_LARGE_CONTENT_BLOCKS_IN_PAGES + +SEPARATE_CONTENT_FROM_PRESENTATION + +--- + +## DATA_RULES + +STATIC_DATA_BELONGS_IN_SRC_DATA + +NAVIGATION_DATA_BELONGS_IN_SRC_DATA + +FAQ_DATA_BELONGS_IN_SRC_DATA + +CONFIGURATION_DATA_BELONGS_IN_SRC_DATA + +DO_NOT_STORE_DATA_IN_COMPONENTS + +SEPARATE_DATA_FROM_PRESENTATION + +--- + +## IMAGE_RULES + +PROJECT_IMAGES_BELONG_IN_SRC_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +USE_ASTRO_IMAGE_OPTIMIZATION_WHEN_AVAILABLE + +DO_NOT_STORE_IMAGES_IN_COMPONENT_DIRECTORIES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +PREFER_GLOBAL_STYLES_IN_SRC_STYLES + +--- + +## PERFORMANCE_RULES + +PREFER_STATIC_GENERATION + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +MINIMIZE_HYDRATION + +LOAD_ONLY_REQUIRED_CLIENT_CODE + +AVOID_UNNECESSARY_REACT_COMPONENTS + +--- + +## ISLAND_RULES + +USE_ISLANDS_ARCHITECTURE + +DEFAULT_TO_SERVER_RENDERED_CONTENT + +HYDRATE_ONLY_WHEN_NECESSARY + +DO_NOT_HYDRATE_STATIC_CONTENT + +USE_CLIENT_DIRECTIVES_ONLY_WHEN_REQUIRED + +--- + +## NAMING_RULES + +COMPONENT_FILES -> PascalCase + +LAYOUT_FILES -> PascalCase + +UTILITY_FILES -> camelCase + +DATA_FILES -> camelCase + +CONTENT_FILES -> kebab-case + +IMAGE_FILES -> kebab-case + +EXAMPLES + +- Header.astro + +- HeroSection.astro + +- PostLayout.astro + +- navigationData.js + +- faqData.js + +- getting-started.md + +- first-blog-post.md + +--- + +## ROOT_DIRECTORY_POLICY + +DO_NOT_CREATE_FILES_IN_REPOSITORY_ROOT + +UNLESS_REQUIRED_BY_ASTRO + +ALLOWED_ROOT_FILES + +- astro.config.mjs +- content.config.ts +- package.json +- README.md +- tsconfig.json + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_CONTENT +4. CHECK_EXISTING_DATA +5. CHECK_EXISTING_PATTERNS +6. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_NEW_FILES + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +DO_NOT_GUESS + +--- + +## ASTRO_PRINCIPLES + +STATIC_FIRST + +CONTENT_FIRST + +SERVER_FIRST + +USE_ISLANDS_ARCHITECTURE + +MINIMIZE_JAVASCRIPT + +HYDRATE_ONLY_WHEN_NECESSARY diff --git a/content/tech-stacks/FASTAPI.md b/content/tech-stacks/FASTAPI.md new file mode 100644 index 0000000..e40b8eb --- /dev/null +++ b/content/tech-stacks/FASTAPI.md @@ -0,0 +1,259 @@ +# FASTAPI.md + +## STACK + +REQUIRED + +- Python 3.13+ +- FastAPI +- Pydantic 2.x +- Uvicorn + +OPTIONAL + +- SQLAlchemy +- Alembic +- PostgreSQL + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PYPROJECT_TOML_IS_SOURCE_OF_TRUTH + +REQUIREMENTS_TXT_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PROJECT_CONFIGURATION + +--- + +## PROJECT_STRUCTURE + +```text +app/ +├── api/ +├── schemas/ +├── dependencies/ +├── core/ +└── main.py + +tests/ + +pyproject.toml +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CONTROLLERS_DIRECTORY + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +api_routes -> app/api + +request_schemas -> app/schemas + +response_schemas -> app/schemas + +shared_dependencies -> app/dependencies + +application_configuration -> app/core + +application_entry -> app/main.py + +tests -> tests + +--- + +## API_RULES + +USE_APIRouter + +GROUP_RELATED_ENDPOINTS + +KEEP_ROUTE_MODULES_SMALL + +KEEP_ENDPOINTS_FOCUSED + +FOLLOW_FASTAPI_CONVENTIONS + +ROUTES_BELONG_IN_APP_API + +--- + +## SCHEMA_RULES + +USE_PYDANTIC_MODELS + +REQUEST_MODELS_ARE_REQUIRED + +RESPONSE_MODELS_ARE_REQUIRED + +SEPARATE_REQUEST_AND_RESPONSE_MODELS_WHEN_NEEDED + +DO_NOT_USE_RAW_DICTIONARIES_FOR_PUBLIC_APIS + +--- + +## DEPENDENCY_RULES + +USE_FASTAPI_DEPENDENCY_INJECTION + +SHARED_DEPENDENCIES_BELONG_IN_APP_DEPENDENCIES + +AVOID_GLOBAL_STATE + +PREFER_EXPLICIT_DEPENDENCIES + +--- + +## CONFIGURATION_RULES + +APPLICATION_CONFIGURATION_BELONGS_IN_APP_CORE + +USE_ENVIRONMENT_VARIABLES_FOR_CONFIGURATION + +DO_NOT_HARDCODE_SECRETS + +DO_NOT_HARDCODE_CREDENTIALS + +DO_NOT_HARDCODE_API_KEYS + +--- + +## DATABASE_RULES + +DATABASE_INTEGRATION_IS_OPTIONAL + +DO_NOT_ASSUME_DATABASE_USAGE + +DO_NOT_ASSUME_DATABASE_ENGINE + +FOLLOW_DECLARED_PROJECT_DEPENDENCIES + +--- + +## TESTING_RULES + +TESTS_BELONG_IN_TESTS_DIRECTORY + +USE_PYTEST + +TEST_API_ENDPOINTS + +TEST_CORE_BUSINESS_BEHAVIOR + +--- + +## ARCHITECTURE_RULES + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CUSTOM_ARCHITECTURE + +DO_NOT_INTRODUCE_PATTERNS_NOT_DEFINED_IN_ARCHITECTURE_MD + +DO_NOT_CREATE_ABSTRACTIONS_WITHOUT_JUSTIFICATION + +PREFER_SIMPLE_OVER_COMPLEX + +--- + +## FORBIDDEN_DIRECTORIES + +- src +- services +- repositories +- controllers + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- tests + +ALLOWED_ROOT_FILES + +- pyproject.toml +- README.md +- .env.example + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PYPROJECT_TOML_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## FASTAPI_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +API_FIRST + +MINIMAL_STRUCTURE + +SCHEMAS_ARE_REQUIRED + +DEPENDENCY_INJECTION_OVER_GLOBAL_STATE + +NO_ARCHITECTURAL_GUESSING + +REUSE_BEFORE_CREATING + +KEEP_IT_SIMPLE diff --git a/content/tech-stacks/GO_CLI.md b/content/tech-stacks/GO_CLI.md new file mode 100644 index 0000000..0d134ff --- /dev/null +++ b/content/tech-stacks/GO_CLI.md @@ -0,0 +1,406 @@ +# go-cli.md + +# AI Issue Publisher Tech Stack + +## Purpose + +This document defines implementation constraints. + +product.md defines what must be built. + +TECH_STACK.md defines how it must be built. + +Implementations must follow this document exactly. + +Do not replace technologies. + +Do not introduce alternatives. + +Do not redesign architecture. + +--- + +# Language + +Use: + +```text +Go >= 1.24 +``` + +Do not use: + +```text +Node.js +TypeScript +Python +Rust +PHP +Java +``` + +--- + +# Architecture Style + +Use: + +```text +Single Binary CLI +``` + +Requirements: + +- no backend service +- no database +- no web server +- no daemon process + +The application must execute as a standalone command-line tool. + +--- + +# CLI Tech Stack + +Use: + +```text +github.com/spf13/cobra +``` + +Do not introduce additional CLI tech stacks. + +--- + +# Clipboard + +Use: + +```text +golang.design/x/clipboard +``` + +Clipboard is the primary input source. + +Do not require file input for normal workflows. + +--- + +# Markdown Processing + +Use: + +```text +github.com/yuin/goldmark +``` + +Markdown must be parsed programmatically. + +Do not use regex-only parsing. + +--- + +# GitHub Integration + +Use: + +```text +GitHub REST API +``` + +Authentication: + +```text +AI_BACKLOG_TOKEN +``` + +Requirements: + +- token belongs to ai-backlog-bot +- issues must be created using ai-backlog-bot credentials +- GitHub must display ai-backlog-bot as issue author + +Do not use: + +```text +Current user credentials +``` + +Do not create issues as the publishing user. + +--- + +# Publisher Detection + +Publisher identity is informational only. + +Resolve publisher using: + +```text +gh api user +``` + +Fallback: + +```text +git config user.name +``` + +Publisher information must be stored inside issue metadata. + +Publisher identity must never be used for issue creation. + +--- + +# Repository Resolution + +Resolve repository from: + +```text +git remote get-url origin +``` + +Expected result: + +```text +owner/repository +``` + +If repository resolution fails: + +```text +abort operation +``` + +Do not request repository information interactively. + +--- + +# Configuration + +Configuration format: + +```text +YAML +``` + +Location: + +```text +~/.config/ai-issue/config.yaml +``` + +Configuration is optional for MVP. + +Environment variables are preferred for secrets. + +--- + +# Secrets + +Use: + +```text +AI_BACKLOG_TOKEN +``` + +Environment variable only. + +Never store tokens in: + +- repository +- source code +- configuration files + +--- + +# Commands + +## Create Issue + +Command: + +```bash +ai-issue +``` + +Supported workflow: + +```text +Clipboard +↓ +Parse +↓ +Preview +↓ +Confirm +↓ +Create Issue +``` + +--- + +## Doctor + +Command: + +```bash +ai-issue doctor +``` + +Checks: + +- clipboard support +- git repository +- GitHub connectivity +- AI_BACKLOG_TOKEN availability + +Doctor command must not modify state. + +--- + +# Directory Structure + +Use: + +```text +cmd/ + ai-issue/ + +internal/ + clipboard/ + github/ + markdown/ + metadata/ + repository/ + publisher/ + +tests/ +``` + +Avoid: + +```text +pkg/ +services/ +helpers/ +utils/ +common/ +shared/ +``` + +Create packages around responsibilities. + +--- + +# Error Handling + +Return explicit errors. + +Do not silently continue. + +Examples: + +```text +Clipboard is empty. +``` + +```text +Current directory is not a git repository. +``` + +```text +Issue title could not be determined. +``` + +```text +AI_BACKLOG_TOKEN is not configured. +``` + +--- + +# Testing + +Use: + +```text +Go standard testing package +``` + +Do not introduce testing tech stacks. + +Test: + +- markdown parsing +- repository resolution +- metadata generation +- issue payload generation + +Mock external systems when appropriate. + +Do not require GitHub access for unit tests. + +--- + +# Distribution + +Distribution method: + +```text +GitHub Releases +``` + +Artifacts: + +```text +macOS +Linux +Windows +``` + +Produce standalone binaries. + +Do not require runtime dependencies other than Git and GitHub access. + +--- + +# Non-Goals + +Do not implement: + +- AI APIs +- ChatGPT integration +- Claude integration +- Gemini integration +- pull request creation +- commit creation +- Slack integration +- Jira integration +- analytics +- project management features + +These are outside the scope of the project. + +--- + +# Tech Stacks Invariants + +The following conditions must always hold: + +```text +Author != Publisher +``` + +```text +GitHub Author == ai-backlog-bot +``` + +```text +Publisher == informational metadata only +``` + +```text +Single Binary CLI +``` + +Any implementation that violates these invariants is incorrect. diff --git a/content/tech-stacks/NEXTJS.md b/content/tech-stacks/NEXTJS.md new file mode 100644 index 0000000..19e54e7 --- /dev/null +++ b/content/tech-stacks/NEXTJS.md @@ -0,0 +1,329 @@ +# NextJS.md + +## STACK + +REQUIRED + +- Next.js 16.x +- React 19.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- TypeScript +- next-intl + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +TECH_STACK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_NEXTJS_VERSION + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +app/ + +components/ +├── layout/ +├── sections/ +└── ui/ + +data/ +hooks/ +utils/ +styles/ +images/ + +public/ + +next.config.mjs +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SRC_APP + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +routes -> app + +layout_components -> components/layout + +section_components -> components/sections + +reusable_ui_components -> components/ui + +static_content -> data + +navigation_data -> data + +custom_hooks -> hooks + +utility_functions -> utils + +global_styles -> styles + +project_images -> images + +public_assets -> public + +--- + +## ROUTING_RULES + +USE_APP_ROUTER_ONLY + +APP_ROUTER_IS_ROOT_LEVEL + +DO_NOT_USE_PAGES_ROUTER + +DO_NOT_CREATE_PAGES_DIRECTORY + +FOLLOW_NEXTJS_FILE_CONVENTIONS + +USE_ROUTE_GROUPS_WHEN_APPROPRIATE + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_CODE + +PRIVATE_FOLDERS_START_WITH_UNDERSCORE + +--- + +## COLOCATION_RULES + +ALLOW_ROUTE_LOCAL_COMPONENTS + +ALLOW_ROUTE_LOCAL_UTILITIES + +ALLOW_ROUTE_LOCAL_DATA + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_FILES + +PREFER_ROUTE_LOCAL_CODE_WHEN_NOT_SHARED + +USE_SHARED_DIRECTORIES_ONLY_FOR_REUSABLE_CODE + +--- + +## COMPONENT_RULES + +USE_SERVER_COMPONENTS_BY_DEFAULT + +ADD_USE_CLIENT_ONLY_WHEN_REQUIRED + +MINIMIZE_CLIENT_COMPONENTS + +PREFER_SERVER_RENDERING + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## DATA_FETCHING_RULES + +FETCH_DATA_IN_SERVER_COMPONENTS_WHEN_POSSIBLE + +PREFER_ASYNC_SERVER_COMPONENTS + +AVOID_CLIENT_SIDE_FETCHING_UNLESS_REQUIRED + +DO_NOT_MOVE_SERVER_FETCHING_TO_CLIENT_COMPONENTS + +--- + +## API_RULES + +API_ROUTES_BELONG_IN_APP_API + +USE_ROUTE_HANDLERS + +FOLLOW_NEXTJS_API_CONVENTIONS + +DO_NOT_CREATE_CUSTOM_API_ARCHITECTURE + +--- + +## IMAGE_RULES + +USE_NEXT_IMAGE_WHEN_POSSIBLE + +PROJECT_IMAGES_BELONG_IN_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +OPTIMIZE_IMAGES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## FORBIDDEN_DIRECTORIES + +- pages +- src +- features +- shared +- widgets +- modules +- views + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- components +- data +- hooks +- utils +- styles +- images +- public + +ALLOWED_ROOT_FILES + +- package.json +- next.config.js +- next.config.mjs +- README.md +- jsconfig.json +- tsconfig.json + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_PATTERNS +4. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## NEXTJS_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +APP_ROUTER_ONLY + +SERVER_FIRST + +SERVER_COMPONENTS_BY_DEFAULT + +MINIMIZE_USE_CLIENT + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +RESPONSIVE_BY_DEFAULT + +ACCESSIBLE_BY_DEFAULT + +REUSE_BEFORE_CREATING diff --git a/content/tech-stacks/NODE_CLI.md b/content/tech-stacks/NODE_CLI.md new file mode 100644 index 0000000..fcd27d9 --- /dev/null +++ b/content/tech-stacks/NODE_CLI.md @@ -0,0 +1,371 @@ +# node-cli.md + +## Purpose + +This document defines the implementation tech stack 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: + +> TECH_STACK.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 tech stack 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 Tech Stack Rules + +A structured CLI tech stack 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: + +- TECH_STACK.md is updated accordingly +- IMPLEMENTATION_CONSTITUTION.md is updated if required + +--- + +## Tech Stack 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 tech-stack-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/content/tech-stacks/REACT_VITE.md b/content/tech-stacks/REACT_VITE.md new file mode 100644 index 0000000..c302260 --- /dev/null +++ b/content/tech-stacks/REACT_VITE.md @@ -0,0 +1,334 @@ +# React-Vite.md + +## STACK + +REQUIRED + +- Vite 8.x +- React 19.x +- JavaScript +- TailwindCSS 4.x +- i18next 25.x +- react-i18next 15.x + +OPTIONAL + +- react-router-dom +- lucide-react +- axios +- zustand +- @tanstack/react-query +- react-hook-form +- zod + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +TECH_STACK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_GENERATE_CODE_FOR_OTHER_VERSIONS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +src/ +├── assets/ +├── components/ +│ ├── layout/ +│ ├── sections/ +│ └── ui/ +├── pages/ +├── i18n/ +│ ├── locales/ +│ │ └── en.json +│ └── index.js +├── data/ +├── hooks/ +├── utils/ +├── App.jsx +├── main.jsx +└── index.css +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +FOLLOW_EXISTING_STRUCTURE_BEFORE_CREATING_NEW_STRUCTURE + +--- + +## FILE_PLACEMENT + +pages -> src/pages + +layout_components -> src/components/layout + +section_components -> src/components/sections + +reusable_ui_components -> src/components/ui + +page_specific_components -> src/pages/ + +static_content -> src/data + +navigation_data -> src/data + +faq_data -> src/data + +content_data -> src/data + +custom_hooks -> src/hooks + +utility_functions -> src/utils + +translation_files -> src/i18n/locales + +i18n_configuration -> src/i18n/index.js + +application_root -> src/App.jsx + +application_entry -> src/main.jsx + +global_styles -> src/index.css + +DO_NOT_CREATE_SUBDIRECTORIES_UNDER_PAGES + +DO_NOT_CREATE_COMPONENTS_OUTSIDE_DEFINED_LOCATIONS + +--- + +## ROOT_DIRECTORY_POLICY + +DO_NOT_CREATE_FILES_IN_REPOSITORY_ROOT + +UNLESS_EXPLICITLY_DEFINED_IN_ARCHITECTURE_MD + +PREFER_SRC_PLACEMENT_WHENEVER_POSSIBLE + +--- + +## FORBIDDEN_DIRECTORIES + +- features +- shared +- widgets +- modules +- stores +- state +- services +- api +- views + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_DEFINED_IN_ARCHITECTURE_MD + +--- + +## NAMING_RULES + +COMPONENT_FILES -> PascalCase + +HOOK_FILES -> useCamelCase + +UTILITY_FILES -> camelCase + +DATA_FILES -> camelCase + +TRANSLATION_FILES -> language_code.json + +EXAMPLES + +- Header.jsx + +- HeroSection.jsx + +- PricingCard.jsx + +- useLanguage.js + +- useScrollPosition.js + +- navigationData.js + +- faqData.js + +DO_NOT_CREATE_INDEX_FILES_UNLESS_REQUIRED + +--- + +## COMPONENT_RULES + +USE_FUNCTION_COMPONENTS_ONLY + +DO_NOT_USE_CLASS_COMPONENTS + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +MOVE_REUSABLE_UI_TO_COMPONENTS_UI + +MOVE_PAGE_SPECIFIC_UI_TO_PAGE_DIRECTORY + +PREFER_COMPOSITION_OVER_COMPLEX_COMPONENTS + +--- + +## DATA_RULES + +STATIC_CONTENT_BELONGS_IN_SRC_DATA + +FAQ_CONTENT_BELONGS_IN_SRC_DATA + +NAVIGATION_CONTENT_BELONGS_IN_SRC_DATA + +CONTENT_BELONGS_IN_SRC_DATA + +DO_NOT_STORE_LARGE_CONTENT_BLOCKS_IN_COMPONENTS + +SEPARATE_CONTENT_FROM_PRESENTATION + +--- + +## STYLING_RULES + +USE_TAILWINDCSS_ONLY + +DO_NOT_USE_SCSS + +DO_NOT_USE_SASS + +DO_NOT_USE_CSS_MODULES + +DO_NOT_USE_STYLED_COMPONENTS + +DO_NOT_USE_EMOTION + +DO_NOT_USE_INLINE_STYLE_UNLESS_REQUIRED + +PREFER_TAILWIND_UTILITY_CLASSES + +--- + +## I18N_RULES + +SOURCE_LANGUAGE = ko + +KOREAN_IS_SOURCE_OF_TRUTH + +USE_KOREAN_TEXT_AS_TRANSLATION_KEYS + +ALL_USER_VISIBLE_TEXT_MUST_USE_TRANSLATION_FUNCTION + +DO_NOT_HARDCODE_USER_VISIBLE_TEXT + +DO_NOT_CREATE_KO_TRANSLATION_FILE + +ONLY_TRANSLATE_NON_SOURCE_LANGUAGES + +REQUIRED_FILES + +- src/i18n/locales/en.json + +EXAMPLE + +Component + +```jsx +__("회원가입"); +``` + +Translation + +```json +{ + "회원가입": "Sign Up" +} +``` + +WHEN_ADDING_NEW_TEXT + +1. USE_KOREAN_TEXT_AS_KEY +2. ADD_TRANSLATIONS_TO_ALL_NON_SOURCE_LANGUAGES +3. KEEP_TRANSLATIONS_SYNCHRONIZED + +FORBIDDEN + +```jsx +t("auth.register.button"); +``` + +```json +{ + "auth.register.button": "회원가입" +} +``` + +--- + +## ACCESSIBILITY_RULES + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT_FOR_IMAGES + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_VISIBLE_FOCUS_STATES + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_DATA_FILES +4. CHECK_EXISTING_PATTERNS +5. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_NEW_FILES + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +WHEN_UNCERTAIN_FOLLOW_EXISTING_CODEBASE + +ARCHITECTURE_MD_OVERRIDES_THIS_DOCUMENT + +TASKS_MD_OVERRIDES_ASSUMPTIONS + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +DO_NOT_GUESS diff --git a/content/tech-stacks/VANILLA.md b/content/tech-stacks/VANILLA.md new file mode 100644 index 0000000..f471c50 --- /dev/null +++ b/content/tech-stacks/VANILLA.md @@ -0,0 +1,261 @@ +# Vanilla.md + +## STACK + +REQUIRED + +- HTML5 +- CSS3 +- JavaScript ES2024 + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_TECH_STACKS + +DO_NOT_INTRODUCE_BUILD_TOOLS + +DO_NOT_INTRODUCE_PACKAGE_MANAGERS + +--- + +## PROJECT_STRUCTURE + +```text +/ +├── index.html +├── css/ +│ └── styles.css +├── js/ +│ └── main.js +├── images/ +└── assets/ +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +html_pages -> repository_root + +stylesheets -> css + +javascript -> js + +images -> images + +static_assets -> assets + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_COMPONENT_DIRECTORIES + +DO_NOT_CREATE_BUILD_DIRECTORIES + +--- + +## HTML_RULES + +USE_SEMANTIC_HTML + +PREFER_NATIVE_HTML_ELEMENTS + +USE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT_FOR_IMAGES + +AVOID_UNNECESSARY_DIV_ELEMENTS + +--- + +## CSS_RULES + +USE_PLAIN_CSS + +STORE_GLOBAL_STYLES_IN_CSS_STYLES_CSS + +DO_NOT_USE_SCSS + +DO_NOT_USE_SASS + +DO_NOT_USE_LESS + +DO_NOT_USE_CSS_MODULES + +DO_NOT_USE_CSS_IN_JS + +DO_NOT_INTRODUCE_STYLING_TECH_STACKS + +--- + +## JAVASCRIPT_RULES + +USE_VANILLA_JAVASCRIPT + +USE_ES_MODULES_WHEN_NEEDED + +PREFER_MODERN_BROWSER_APIS + +DO_NOT_USE_JQUERY + +DO_NOT_USE_REACT + +DO_NOT_USE_VUE + +DO_NOT_USE_ANGULAR + +DO_NOT_USE_SVELTE + +DO_NOT_USE_ALPINE + +DO_NOT_USE_HTMX + +--- + +## ASSET_RULES + +IMAGES_BELONG_IN_IMAGES + +FONTS_BELONG_IN_ASSETS + +ICONS_BELONG_IN_ASSETS + +DOWNLOADABLE_FILES_BELONG_IN_ASSETS + +DO_NOT_STORE_ASSETS_IN_CSS_OR_JS_DIRECTORIES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +TEST_COMMON_VIEWPORT_SIZES + +RESPONSIVE_BEHAVIOR_OVERRIDES_DESKTOP_PREFERENCES + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## PERFORMANCE_RULES + +MINIMIZE_JAVASCRIPT + +MINIMIZE_DEPENDENCIES + +OPTIMIZE_IMAGES + +PREFER_NATIVE_BROWSER_FEATURES + +AVOID_UNNECESSARY_ABSTRACTIONS + +--- + +## FORBIDDEN_TOOLS + +- React +- Vue +- Angular +- Svelte +- Next.js +- Nuxt +- Astro +- Vite +- Webpack +- Parcel +- Rollup +- jQuery + +DO_NOT_INTRODUCE_FORBIDDEN_TOOLS + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ROOT_HTML_FILES_ARE_ALLOWED + +DO_NOT_CREATE_CONFIGURATION_FILES + +DO_NOT_CREATE_PACKAGE_JSON + +DO_NOT_CREATE_NODE_MODULES + +DO_NOT_CREATE_BUILD_CONFIGURATIONS + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_INTRODUCE_TECH_STACKS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +--- + +## VANILLA_PRINCIPLES + +HTML_FIRST + +CSS_SECOND + +JAVASCRIPT_WHEN_NEEDED + +USE_NATIVE_BROWSER_FEATURES + +MOBILE_FIRST + +RESPONSIVE_BY_DEFAULT + +KEEP_IT_SIMPLE + +AVOID_DEPENDENCIES + +DO_NOT_INTRODUCE_TECH_STACKS