AgentsAtlas

A minimal workflow for building production-ready projects with Claude Code & Codex. 8 commands. Fresh context via subagent execution. Quality execution.

Quick Start

npx agents-atlas --global

Then in any project:

/atlas:init       # Set up project with CLAUDE.md + STATE.md
/atlas:plan       # Create a 3-5 task plan for current phase
/atlas:execute    # Run plan with fresh subagent context

What You Get

• 8 slash commands that manage any project end-to-end
• Fresh 200k-token context per task via subagent execution — no degradation
• XML task format with built-in verification steps
• 16 development skills (debugging, testing, security audit, and more)
• Works with both Claude Code and Codex

Table of Contents

• Installation
• Commands
• Using with Codex
• Skills
• Workflow
• Project Structure
• Task Format
• Why This Works
• Customization
• License

Installation

Option 1: npx (Recommended)

# Install globally (available in all projects)
npx agents-atlas --global

# Or install locally (current project only)
npx agents-atlas --local

# Global commands + global Codex skills
npx agents-atlas --global --with-codex-global

--local also installs Codex wrappers in your repo (.agents/skills/atlas-*, scripts/atlas-*, and .codex/config.toml). Use --with-codex-global when installing globally to install Atlas skills in ~/.codex/skills/atlas-* so they are available across projects (project-local skills can still override them).

Option 2: From GitHub

git clone https://github.com/AvinashP/AgentsAtlas.git
cd AgentsAtlas
node bin/install.js --global

Option 3: Manual Symlink

git clone https://github.com/AvinashP/AgentsAtlas.git
ln -s $(pwd)/AgentsAtlas/commands/atlas ~/.claude/commands/atlas

Commands (Claude Code)

| Command | Purpose | |---------|---------| | /atlas:init | Initialize project with CLAUDE.md + STATE.md | | /atlas:plan | Create executable plan (3-5 tasks max) | | /atlas:execute | Run plan with fresh subagent context | | /atlas:status | Check progress, get next action | | /atlas:review | Review code changes, capture learnings for CLAUDE.md | | /atlas:sync | Restore context after /clear | | /atlas:triage | Pull and triage issues from Sentry, GitHub, etc. | | /atlas:complete | Complete milestone, archive, and prepare for next work |

Non-Interactive Mode

Add --auto when running without user interaction (CI, scripts, --dangerously-skip-permissions):

/atlas:init --auto    # Detects project from config files, uses [TODO] for unknowns
/atlas:plan --auto    # Picks best approach automatically, no prompts

Without --auto, these commands ask interactive questions that get phantom answers in non-interactive mode.

Using with Codex

Atlas appears in Codex as skills, not /atlas:* slash commands.

1. Open Codex in a project.
2. Run /skills (or press $) and select any atlas-* skill.

Skill precedence:

• Global skills: ~/.codex/skills/atlas-* (installed by --global --with-codex-global)
• Project-local skills: .agents/skills/atlas-* (override global skills when present)

Quick verification:

ls ~/.codex/skills/atlas-plan/SKILL.md

See docs/ai-workflow.md for the full Codex integration guide.

Skills

AgentsAtlas includes 16 development skills that provide disciplined workflows:

| Category | Skills | |----------|--------| | Discipline | debugging, testing, verifying | | Process | brainstorming, receiving-feedback | | Git | committing, creating-pr | | Code Quality | refactoring, security-audit | | Utility | explaining-code, scaffolding | | Building | frontend-design, mcp-builder, web-artifacts-builder, webapp-testing, skill-creator |

The first 11 skills emphasize the Iron Law approach — finding root causes before fixes, evidence before claims, and test-driven development. The building skills (from Anthropic) provide production-grade UI design, MCP server creation, and testing capabilities.

Workflow

/atlas:init          # Once per project
    ↓
/atlas:plan          # Plan current phase (3-5 tasks)
    ↓
/atlas:execute       # Execute with fresh context
    ↓
/atlas:status        # What's next?
    ↓
(repeat plan → execute → status)

Bug Triage Workflow

/atlas:triage        # Pull issues from Sentry/GitHub/JIRA
    ↓
/atlas:plan          # Plan fixes for selected issues
    ↓
/atlas:execute       # Execute fix plan

Milestone Completion

(all phases complete)
    ↓
/atlas:complete      # Archive, tag, prepare for next work
    ↓
/atlas:plan          # Start new milestone

Code Review

/atlas:review        # Review current phase's changes
    ↓
(address issues if any)
    ↓
/atlas:complete      # Or continue to next phase

# Or review a PR:
/atlas:review --pr 123  # Review GitHub PR, suggest CLAUDE.md additions

Context Management

When context degrades:
1. Run /clear
2. Run /atlas:sync
3. Continue working

The subagent execution pattern means each plan runs
with fresh 200k tokens—no accumulated noise.

Project Structure

After /atlas:init, your project will have:

your-project/
├── CLAUDE.md              # Project context (< 30 lines)
└── .planning/
    ├── STATE.md           # Current position + recent decisions
    ├── ROADMAP.md         # Phase checklist
    └── phases/
        ├── 01-PLAN.md     # Phase 1 execution plan
        ├── 02-PLAN.md     # Phase 2 execution plan
        └── ...

Task Format

Plans use XML for clarity:

<task id="1">
<name>Create user authentication endpoint</name>
<files>src/api/auth.ts, src/lib/jwt.ts</files>
<action>
1. Create POST /api/auth/login endpoint
2. Validate email/password against database
3. Generate JWT token on success
4. Return token with 24h expiry
</action>
<verify>curl -X POST /api/auth/login -d '{"email":"[email protected]","password":"test"}'</verify>
<done>Login returns 200 + JWT token; invalid credentials return 401</done>
</task>

• verify = How to test (commands to run)
• done = Acceptance criteria (what success looks like)

Why This Works

• Small plans (3-5 tasks) = Focused execution, fewer mistakes
• Fresh context per task = Consistent quality, no degradation across tasks
• Verification steps = Catch issues immediately, not at the end
• Atomic commits = Easy rollback, clear git history
• STATE.md = Session continuity without context bloat

See Setup Tips for hooks, permissions, and advanced Claude Code configuration.

Customization

Edit the command files in commands/atlas/ to adjust:

• Task limits
• Commit format
• Deviation rules
• Output format

Codex wrapper metadata source of truth:

• commands/atlas/manifest.json
• Run npm run sync:atlas after manifest changes.

Artifacts regenerated by the sync script:

• .agents/skills/atlas-*
• scripts/atlas-*
• AGENTS.md
• docs/ai-workflow.md
• .claude-plugin/plugin.json command list

Maintainer checks:

• npm run check:atlas

License

MIT