# Atlas Framework

> 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.

- Skill: `gabrielmoreira/atlas-framework` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/atlas-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/atlas-framework/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/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