atlas-framework

# ATLAS Framework A structured methodology for AI-assisted development built on the GOTCHA 6-layer architecture. ## When to Use This Skill Use this skill when: - Building full-stack applications - Creating agentic workflows - Setting up AI assistant frameworks - Designing data systems or databases - Planning integrations with external services ## The GOTCHA Framework (6 Layers) **GOT (The Engine):** - **Goals** (`goals/`) — What needs to happen (process definitions) - **Orchestration** — The AI manager that coordinates execution - **Tools** (`tools/`) — Deterministic scripts that do the actual work **CHA (The Context):** - **Context** (`context/`) — Reference material and domain knowledge - **Hard prompts** (`hardprompts/`) — Reusable instruction templates - **Args** (`args/`) — Behavior settings that shape how the system acts ### Why GOTCHA? LLMs are probabilistic (educated guesses). Business logic is deterministic (must work the same way every time). This structure bridges that gap through **separation of concerns**: - Push **reliability** into deterministic code (tools) - Push **flexibility and reasoning** into the LLM (orchestration) - Push **process clarity** into goals - Push **behavior settings** into args files - Push **domain knowledge** into context layer --- ## ATLAS Workflow (5 Steps) Use this when building applications: | Step | Phase | What You Do | |------|-------|-------------| | **A** | Architect | Define problem, users, success metrics | | **T** | Trace | Data schema, integrations map, stack proposal | | **L** | Link | Validate ALL connections before building | | **A** | Assemble | Build with layered architecture | | **S** | Stress-test | Test functionality, error handling | For production builds, also add: - **V** — Validate (security, input sanitization, edge cases, unit tests) - **M** — Monitor (logging, observability, alerts) ### A — Architect **Purpose:** Know exactly what you're building before touching code. Answer these questions: 1. **What problem does this solve?** (One sentence) 2. **Who is this for?** (Specific user, not "everyone") 3. **What does success look like?** (Measurable outcome) 4. **What are the constraints?** (Budget, time, technical requirements) ### T — Trace **Purpose:** Design before building. 1. **Data Schema** — Define source of truth BEFORE building 2. **Integrations Map** — List every external connection (service, purpose, auth type, MCP available?) 3. **Technology Stack** — Propose database, backend, frontend 4. **Edge Cases** — Document what could break (rate limits, token expiry, timeouts) ### L — Link **Purpose:** Validate ALL connections BEFORE building. ``` [ ] Database connection tested [ ] All API keys verified [ ] MCP servers responding [ ] OAuth flows working [ ] Environment variables set [ ] Rate limits understood ``` ### A — Assemble **Purpose:** Build with proper architecture. Build order: 1. Database schema first 2. Backend API routes second 3. Frontend UI last Follow GOTCHA separation: - **Frontend** — UI components, user interactions - **Backend** — API routes, business logic, validation - **Database** — Schema, migrations, indexes ### S — Stress-test **Purpose:** Test before shipping. - **Functional Testing** — All buttons work, data saves/retrieves, navigation works - **Integration Testing** — API calls succeed, MCP operations work, auth persists - **Edge Case Testing** — Invalid input handled, empty states display, network errors show feedback --- ## File Structure ``` project/ ├── goals/ — Process definitions (what to achieve) ├── tools/ — Execution scripts (organized by workflow) ├── args/ — Behavior settings (YAML/JSON) ├── context/ — Domain knowledge and references ├── hardprompts/ — Reusable instruction templates ├── memory/ — Persistent memory system ├── .tmp/ — Temporary work (disposable) ├── .env — API keys + environment variables └── CLAUDE.md — System instruction file ``` --- ## Memory System The framework includes a persistent memory system for cross-session continuity. ### Loading Memory At session start, load memory context: - Read `memory/MEMORY.md` for curated long-term facts - Read today's log: `memory/logs/YYYY-MM-DD.md` - Read yesterday's log for continuity ### Memory Types - `fact` — Objective information - `preference` — User preferences - `event` — Something that happened - `insight` — Learned pattern - `task` — Something to do - `relationship` — Connection between entities ### Search Capabilities - Keyword search - Semantic search - Hybrid search (best results) --- ## Anti-Patterns (What NOT To Do) 1. **Building before designing** — End up rewriting everything 2. **Skipping connection validation** — Hours wasted on broken integrations 3. **No data modeling** — Schema changes cascade into UI rewrites 4. **No testing** — Ship broken code, lose trust 5. **Hardcoding everything** — No flexibility for changes --- ## Guardrails - Always check `tools/manifest.md` before writing new scripts - Verify tool output format before chaining into another tool - Don't assume APIs support batch operations — check first - When a workflow fails mid-execution, preserve intermediate outputs before retrying - Read the full goal before starting a task — don't skim --- ## First Run Initialization On first session in a new environment: 1. Check if `memory/MEMORY.md` exists 2. If missing, create the folder structure: - `memory/logs/` - `data/` 3. Create `MEMORY.md` with template 4. Initialize SQLite databases for memory and activity tracking --- ## Continuous Improvement Loop Every failure strengthens the system: 1. Identify what broke and why 2. Fix the tool script 3. Test until it works reliably 4. Update the goal with new knowledge 5. Next time → automatic success