diff --git a/.husky/pre-commit b/.husky/pre-commit index 3932801..353a79b 100644 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1 +1,2 @@ npm run format +npm run lint diff --git a/AI_MEMORY.md b/AI_MEMORY.md index 518f16c..9c58a93 100644 --- a/AI_MEMORY.md +++ b/AI_MEMORY.md @@ -1,258 +1,478 @@ # AI_MEMORY.md -## Purpose +# ReplWorks Memory -This document exists to transfer context between AI sessions. +Version: 2026-06 -It is intended to be provided as part of the first prompt when starting a new conversation. +--- + +# Core Understanding + +ReplWorks is not a project memory system. + +Project memory is only one component. + +The actual goal is: + +```text +Create a repeatable workflow that turns ideas into shipped products using AI. +``` -The goal is not to describe the project. +The original motivation was AI memory loss during development. -The goal is to preserve decision-making context. +However, memory loss was identified as a symptom rather than the root problem. -A future AI should be able to continue discussions with similar understanding and reasoning. +The root problem is: + +```text +How can a solo founder repeatedly transform ideas into production software using AI? +``` + +ReplWorks exists to answer that question. --- -# Project +# ReplWorks Definition + +Current definition: + +```text +AI-Native Product Development Workflow +``` + +Alternative definition: -Name: ReplWorks Documents +```text +A workflow methodology for turning ideas into software through AI-assisted execution. +``` -Repository: +ReplWorks should be positioned as a workflow system or methodology. - +Not as a memory system. -Website: +Not as a documentation system. - +Not as an AI tool. --- -# What We Are Building +# Important Discovery -ReplWorks Documents is a collection of AI-oriented project specification templates. +The most valuable asset is not: -The target audience is developers using AI-assisted development and vibe coding. +- AI_MEMORY.md +- AGENTS.md +- FRAMEWORK.md -The repository is not intended to teach technologies. +The most valuable asset is: -The repository exists to provide constraints that reduce AI guessing. +```text +Workflow ++ +Document Generation Prompts ++ +Validation Prompts +``` -The primary objective is predictable AI behavior. +The workflow is reusable across projects. + +Individual documents are not. --- -# Philosophy +# Development Philosophy + +The goal is not: -AI already knows technologies. +```text +Find a better AI. +``` -Documentation should provide constraints, not tutorials. +The goal is: -Good documentation tells AI: +```text +Create a better workflow. +``` -- what exists -- where things belong -- what is allowed -- what is forbidden +AI models will improve over time. -Bad documentation explains React, Laravel, FastAPI, etc. +The workflow should survive model changes. -The project follows: +--- -- AI First -- Constraints Over Knowledge -- Explicit Over Implicit -- Latest Stable Only -- Official Recommendations First -- Do Not Guess +# Workflow + +Current ReplWorks workflow: + +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +REVIEW_IMPLEMENTATION_READINESS +↓ +TASKS.md +↓ +IMPLEMENTATION +↓ +AI_MEMORY.md +``` + +This workflow is currently considered the core of ReplWorks. --- -# Development Preferences +# Document Responsibilities -The project owner prefers: +## IDEAS.md -- strong conventions -- predictable structures -- minimal architectural creativity -- fewer frameworks -- fewer options -- fewer layers +Purpose: -The project owner dislikes: +```text +Capture the validated product idea. +``` -- unnecessary abstractions -- architecture invented by AI -- speculative folder structures -- excessive flexibility -- legacy compatibility requirements +Rules: + +- Product idea only. +- No implementation. +- No architecture. +- No technology choices. +- No execution plan. --- -# Framework Selection Criteria +## PITCHING_SCRIPT.md + +Purpose: -A framework is worth supporting when: +```text +Persuade a specific audience. +``` -- it is commonly used for new projects -- it has strong conventions -- it has predictable structure -- it is AI-friendly -- it is likely to be used by solo developers, indie hackers, startups, or AI-assisted developers +Audience may be: -Popularity alone is not enough. +- investors +- VCs +- government programs +- partners +- customers + +Expected numbers, assumptions and projections may be included. + +Unlike IDEAS.md. --- -# Current Framework Decisions +## PRODUCT_SPEC.md -Supported: +Purpose: -- VANILLA -- REACT_VITE -- ASTRO -- NEXTJS -- FASTAPI +```text +Define what the product is. +``` -Planned: +Contains: -- LARAVEL +- product requirements +- user-visible behavior +- user flows +- acceptance criteria -Excluded: +Does not contain: -- DJANGO -- NUXT -- SVELTEKIT -- SPRING_BOOT -- ASPNET_CORE +- implementation +- architecture +- technologies -Reasons vary, but usually involve: +Question answered: -- low probability of actual usage -- weak convention enforcement -- architectural fragmentation -- poor fit for AI-assisted development +```text +What are we building? +``` --- -# Framework Philosophy +## ARCHITECTURE.md + +Purpose: + +```text +Define how the product works internally. +``` + +Contains: -Framework documents should contain: +- responsibilities +- flows +- ownership boundaries +- invariants +Does not contain: + +- technologies +- frameworks +- libraries + +Question answered: + +```text +How does the system work? +``` + +--- + +## FRAMEWORK.md + +Purpose: + +```text +Define implementation constraints. +``` + +Contains: + +- language - stack -- versions -- project structure -- file placement rules -- generation rules -- constraints +- coding conventions +- implementation rules + +Question answered: + +```text +How should it be built? +``` + +--- + +## TASKS.md + +Purpose: + +```text +Define what remains to be implemented. +``` + +Contains: + +- implementation milestones +- acceptance criteria + +Does not contain: -Do not split STACK and PROJECT_STRUCTURE into separate documents. +- architecture +- implementation details -One framework document should contain all framework-related rules. +Question answered: + +```text +What should be built next? +``` + +--- + +## AI_MEMORY.md + +Purpose: + +```text +Preserve decision-making context. +``` + +Not project documentation. + +Not requirements. + +Not architecture. + +Used for context recovery in future sessions. + +--- + +# Review Strategy + +The most important review step is: + +```text +REVIEW_IMPLEMENTATION_READINESS +``` + +Purpose: + +```text +Determine whether implementation can begin with confidence. +``` + +Inputs: + +- PRODUCT_SPEC.md +- ARCHITECTURE.md +- FRAMEWORK.md + +Expected reviewer: + +```text +Execution AI +``` Examples: -- REACT_VITE.md -- NEXTJS.md -- FASTAPI.md +- Codex +- implementation-focused agents + +Not discussion-oriented models. --- -# Version Policy +# Discussion AI vs Execution AI + +## Discussion AI + +Examples: + +- ChatGPT +- Claude + +Responsibilities: -Version information is important. +- ideation +- specifications +- architecture +- planning +- workflows -AI frequently assumes older versions. +Question: -Framework documents should define current major versions. +```text +What should we build? +``` -Project configuration remains the source of truth. +--- + +## Execution AI Examples: -- package.json -- pyproject.toml +- Codex + +Responsibilities: -If project configuration exists, follow it. +- implementation review +- implementation certainty +- execution -Otherwise follow framework specifications. +Question: + +```text +Can this actually be built? +``` --- -# FastAPI Decision +# Key Insight + +Many people combine multiple AI systems. -FastAPI should remain minimal. +The value does not come from using different models. -Do not introduce: +The value comes from separating: -- services -- repositories -- controllers +```text +Creation +``` -unless explicitly requested. +and -FastAPI is treated as an API framework. +```text +Validation +``` -Not a full-stack framework. +ReplWorks should preserve that separation. --- -# Django Decision +# AI-Issuer Context + +AI-Issuer became an important test project. + +Purpose: + +```text +Separate AI-generated issues from human-generated issues. +``` -Django was intentionally excluded. +Important architectural decision: -Reasoning: +```text +Author != Publisher +``` -- highly fragmented architecture styles -- inconsistent project structures -- heavy customization across teams -- difficult for AI to predict correctly +Reason: -The issue is not technical quality. +Publishing an AI-generated issue under a human account creates implicit ownership and responsibility. -The issue is predictability. +The project attempts to preserve the distinction between: + +```text +Content Creation +``` + +and + +```text +Content Publication +``` --- -# Long-Term Direction +# Current ReplWorks Positioning -Future work may include: +Previous positioning: -- additional framework specifications -- specification generators -- CLI tooling -- project detection -- framework composition +```text +Project Memory System for AI Development +``` -Potential examples: +Current positioning: -- replworks detect -- replworks generate -- replworks validate +```text +AI-Native Product Development Workflow +``` -Framework specifications may eventually be generated from project dependencies. +Reason: -Example: +Memory is only one step in the workflow. -package.json -→ detect stack -→ generate FRAMEWORK.md +Workflow is the primary product. --- -# Important Context +# Future Direction + +ReplWorks should evolve toward: + +```text +AI Product Development Methodology +``` -When making decisions, prioritize: +Comparable in spirit to: -1. AI predictability -2. simplicity -3. convention over flexibility -4. real-world usage -5. latest stable ecosystem +- Waterfall +- Agile +- Scrum -Do not optimize for theoretical completeness. +But designed specifically for AI-assisted software creation. -Do not optimize for enterprise requirements. +The long-term goal is not better prompting. -Do not optimize for legacy projects. +The long-term goal is: -Optimize for AI-assisted development. +```text +A repeatable system that transforms ideas into shipped products. +```