Atlas Framework

---

name: atlas-framework description: "ATLAS Framework - Structured AI-assisted development methodology with GOTCHA 6-layer architecture and 5-step app building workflow. Use when building applications, creating workflows, or setting up agentic systems."

---

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