Embed badge
Show
Style
[](https://versuz.dev/claude-md/seb155-atlas-plugin)A CLAUDE.md is just a markdown file at the root of your repo. Copy the content below into your own project's CLAUDE.md to give your agent the same context.
npx versuz@latest install seb155-atlas-plugin --kind=claude-mdcurl -o CLAUDE.md https://raw.githubusercontent.com/seb155/atlas-plugin/HEAD/CLAUDE.md# ATLAS Plugin — Claude Code AI Engineering Assistant
<!-- stable-prefix-start: this preamble changes rarely (v6.1 M.1 — keep cache warm) -->
> **Stack**: Bash + yq + Python (tests) | **Version**: SSoT = `.claude-plugin/plugin.json` | **Branch**: `main`
> **Repo**: `forgejo.axoiq.com/axoiq/atlas-plugin` | **Owner**: Seb Gagnon (AXOIQ + G Mining, private)
> **Product vision**: `docs/PRD.md` | **Current plan**: `.blueprint/plans/stop-the-loop-v9.md`
<!-- stable-prefix-end -->
## QUICK START (AI sessions / new collaborators)
If you are an AI session or a new collaborator joining atlas-plugin :
1. **Read first** : `docs/PRD.md` (12-month vision) + `.blueprint/plans/stop-the-loop-v9.md` (current Phase 1 work)
2. **Onboarding** : `ETHOS.md` (4 doctrines) + `CONTRIBUTING.md` (skill lifecycle)
3. **Active rollback point** : tag `pre-stop-loop-v8.4.1` (Phase 1 start)
4. **Tools added in v9** : `tools/audit-hook-stdout.sh`, `tools/hook-lint.sh`, `tools/migrate-hook-stdout.py`, `tools/check-version-drift.py`, `tools/dedupe-dist.py`, `tools/validate-audit-jsonl.py`, `tools/branch-purge.sh`, `tools/hook-chatter-report.sh`
5. **Audit schemas v1** : `.atlas/audit/schemas/` — contract for future AXOIQ app suite (`docs/AUDIT-SCHEMAS.md`)
6. **Common pitfalls** :
- Edit `.claude-plugin/plugin.json` for version, NOT `VERSION` (it's derived now)
- All hooks must emit `{"continue":true}` JSON on stdout — `bash tools/hook-lint.sh --strict` enforces
- Use `[no-release]` keyword in commit body to skip auto-release (for fast-follow fixes)
- Use `[release]` keyword to force release on chore-only commits
- `cleanup-worktrees` hook now refuses to rm worktree on ambiguous git status (H2 safety)
7. **Decision history** : `docs/ADR/` (Phase 1 ADRs : ADR-025 to ADR-032, skipping 020-024 used by Zero-Trust suite)
## PHASE 1 v9 — IN PROGRESS (2026-05-11)
| WI | Status | Description |
|---|---|---|
| H1 | ✓ shipped | 56 silent hooks migrated to `_atlas_h1_ack` EXIT trap |
| H2 | ✓ shipped | `cleanup-worktrees` ambiguity-safe (no rm on uncertain state) |
| H3 | ✓ shipped | `--dedupe` flag in build.sh, symlinks dev/admin → core |
| H4 | ↻ deferred | SKILL.md slim → Phase 1.5 / Phase 2 (`docs/SKILL-MD-SLIM-TODO.md`) |
| H5 | ✓ shipped | `[no-release]` / `[release]` keyword overrides on auto-release |
| H6 | ✓ shipped | ARCHITECTURE.md regenerated for v8.4+ |
| H7 | ✓ shipped | `tools/branch-purge.sh` — dry-run audit + interactive cleanup |
| H8 | ✓ shipped | `plugin.json` as version SSoT, drift checker, VERSION derived |
| H9 | ✓ shipped | `.woodpecker/multi-deploy.yml` — atlas + gms-engineering coordinated |
| H10 | ✓ shipped | 6 audit log schemas v1 in `.atlas/audit/schemas/` + validator |
| H11 | ↻ analyzed | Hook chatter report (22 PostToolUse handlers). Consolidation → Phase 2 |
| H12 | ✓ this section | CLAUDE.md updated for SOTA AI-session onboarding |
<!-- CACHE-AUDIT-BASELINE (v6.1 Task 1.7): to measure prompt cache hit rate,
run `/cost` after a long session. Target post-v6.1: 50-70% cached input tokens.
This file's top section is marked stable to stay in cache prefix. -->
## IDENTITY
**ATLAS** is AXOIQ's unified Claude Code plugin — a multi-tier AI engineering assistant with skills, agents, and lifecycle hooks. It replaces 18+ individual plugins with one cohesive system.
**Key insight**: ATLAS develops itself using ATLAS. The plugin-builder, skill-management, and atlas-dev-self skills are used to extend the plugin.
## ETHOS — Building Doctrine
ATLAS is shaped by 4 doctrines (see `ETHOS.md` at repo root):
1. **Boil the Lake** — completeness is cheap (AI compresses 3-100×). Boil lakes, flag oceans.
2. **Search Before Building** — Layer 1 (tried-and-true) → Layer 2 (new-and-popular) → Layer 3 (first-principles) → EUREKA.
3. **User Sovereignty** — AI recommends, user decides. Karpathy "Iron Man suit" + Willison "merchants of complexity". Never auto-decide User Challenges.
4. **Build for Yourself** — the best tools solve your own problem. ATLAS exists because Seb hit friction.
Companion references:
- `references/askuserquestion-format-v2.md` — AUQ format v2 (ELI10 + Stakes + Net + Completeness + dual-scale effort)
- `references/confidence-calibration.md` — 1-10 scale + display rules per range
- `references/ai-compression-ratio.md` — Table application + dual-scale label patterns
Activated via `skills/_metadata.yaml` (`ethos_doctrine_active: true`). Adapted with attribution from [gstack ETHOS](https://github.com/garrytan/gstack) (MIT, by Garry Tan).
## CC 2.1.x Native Features Adopted (v5.7.0+)
| Feature | CC Version | ATLAS Integration |
|---------|-----------|-------------------|
| Session rename | v2.0.64 | `atlas resume <name>` dual-mode |
| LSP tool | v2.1.74 | (Phase 7 pending) |
| `/effort` | v2.1.84 | documented in ultrathink skill |
| `/loop` + CronCreate | v2.1.89 | experiment-loop delegates simple cases |
| `--worktree` (-w) | v2.1.49 | `atlas feat/fix/hotfix <desc>` wrapper |
| Worktree hooks | v2.1.50 | worktree-setup / -cleanup-native |
| TeammateIdle/TaskCompleted | v2.1.33 | team-idle-notify / task-completed-metrics |
| context_window.size/used_% | v2.1.79 | CShip context_bar |
| rate_limits | v2.1.80 | `$cship.usage_limits` |
| exceeds_200k_tokens | v2.1.87 | atlas-200k-badge-module.sh |
| cost.total_cost_usd | v2.1.x | atlas-cost-usd-module.sh |
| workspace.git_worktree | v2.1.97 | `$cship.worktree` |
| ExitWorktree safety | v2.1.72+ | worktree-exit-safe 5-option flow |
| InstructionsLoaded / ConfigChange | v2.1.83 | already wired pre-v5.7.0 |
| PreCompact / PostCompact | v2.1.89 | already wired pre-v5.7.0 |
| StopFailure / SubagentStart | v2.1.43/78 | already wired pre-v5.7.0 |
Plan: `.blueprint/plans/sleepy-tumbling-hennessy.md` (9 phases total, 5 complete)
## ARCHITECTURE
```
profiles/{user,dev,admin}.yaml ← Tier definitions (YAML inheritance)
↓ build.sh
dist/atlas-{user,dev,user}/ ← Self-contained artifacts (no runtime deps)
↓ make dev
~/.claude/plugins/cache/ ← Installed in Claude Code
```
**3-Tier Inheritance**: `user` → `dev` (inherits user) → `admin` (inherits dev)
### 6-Domain Overlay (standalone installs)
In addition to tiers, ATLAS offers **domain plugins** — standalone installs for specific workflows.
Each domain has its own `atlas-assist` router. **No inheritance** between domains.
| Domain | Skills | Role | Audience |
|--------|--------|------|----------|
| `atlas-core` | 14 | Memory, session, context, vault, assist, doctor | Everyone |
| `atlas-dev` | 25 | Planning, TDD, debugging, review, shipping | Developers |
| `atlas-admin` | 27 | Deploy, security, infra, enterprise, experiments | Admins |
| `atlas-frontend` | 5 | UI design, browser automation, visual QA | FE devs |
| `atlas-infra` | 10 | VM/container ops, network, security audit | DevOps |
| `atlas-enterprise` | 14 | Governance, knowledge engine, programme mgmt | Leads |
| `atlas-experiential` | 5 | Episode capture, intuition, relationship memory | Personal |
**⚠️ Duplication risk (partial Phase 1 fix)** : Skills in multiple domain profiles
build N times in `dist/`. Phase 1 H3 ships `bash build.sh modular --dedupe` which
replaces byte-identical duplicates in dev/admin with symlinks to core. Opt-in flag
(off by default for safety). Real measured savings : ~0.34 MB (60 files), smaller
than original audit estimate of 75% / 7.5 MB.
**Recommendation**: Install the **tier** that matches your role (user/dev/admin).
| Component | Location | Count (admin) |
|-----------|----------|---------------|
| Skills | `skills/*/SKILL.md` | ~67 (profile + atlas-assist) |
| Agents | `agents/*/AGENT.md` | 12 |
| Hooks | `hooks/hooks.json` + scripts | 16 events, ~37 handlers |
| Refs | `skills/refs/*/SKILL.md` | 5 |
| Tests | `tests/test_*.py` | 17 |
### Hook Architecture (IMPORTANT — read before adding hooks)
- **hooks.json is the SSoT** for all hook registrations. NEVER put hooks in `~/.claude/settings.json`.
- **Naming convention**: Hook scripts in `hooks/` have NO `.sh` extension (e.g., `protect-plugin-cache` not `protect-plugin-cache.sh`).
- **Plugin settings.json**: Only env vars and UI flags. NEVER include a `hooks` block.
- **Stdout contract (Phase 1 H1)**: every hook MUST emit `{"continue":true}` JSON on stdout on successful exit. CC harness v2.1.50+ rejects empty-stdout hooks ("no successful output"). The standard pattern is the `_atlas_h1_ack` EXIT trap near top of file. `bash tools/hook-lint.sh --strict` enforces this in CI.
- **Audit emit**: hooks that emit structured events should follow `.atlas/audit/schemas/*.json` and include `"version": 1` (see `docs/AUDIT-SCHEMAS.md`).
- Policy enforcement: `policy-drift-detector` hook warns at session start if deny rules are missing.
- **Current density** (Phase 1 H11 report): 22 PostToolUse handlers, 15 PreToolUse handlers. Consolidation via dispatcher pattern is Phase 2 work.
## COMMANDS
```bash
# Build
./build.sh all # Build 3 tiers → dist/
./build.sh admin # Build admin only
# Test (ALWAYS -x --tb=short)
python3 -m pytest tests/ -x -q --tb=short
python3 -m pytest tests/test_skill_frontmatter.py -x -q --tb=short # Single test
# Dev cycle (build admin + install to CC cache)
make dev
# Publish
make publish-patch # patch bump → build → test → tag → push
make publish-minor # minor bump
# Lint
make lint # Frontmatter + coverage checks
```
## PRINCIPLES
1. **Self-Contained Tiers** — Each `dist/atlas-{tier}/` is independent. No runtime inheritance.
2. **Build-Time Resolution** — `resolve_field()` in build.sh resolves YAML inheritance recursively.
3. **Dynamic Generation** — `generate-master-skill.sh` builds atlas-assist per tier with real counts.
4. **Test Everything** — 16 test types validate structure, frontmatter, cross-refs, build output, hooks.
5. **Version SSoT** — `.claude-plugin/plugin.json` is authoritative (Phase 1 H8). `VERSION` is derived. Drift checker: `python3 tools/check-version-drift.py [--fix]`.
6. **Visual Identity** — All hook outputs use `🏛️ ATLAS │` prefix. See `skills/refs/atlas-visual-identity/`.
## EXTENDING THE PLUGIN
### Adding a Skill
1. Create `skills/{name}/SKILL.md` with frontmatter: `name`, `description`, `effort`
2. Add to appropriate profile (`profiles/{tier}.yaml`)
3. Add to `EMOJI_MAP`, `DESC_MAP`, `CATEGORY_MAP` in `scripts/generate-master-skill.sh`
4. Run `make test` — validates frontmatter, coverage, cross-refs
### Adding an Agent
1. Create `agents/{name}/AGENT.md` with frontmatter: `name`, `description`, `model`
2. Add to profile under `agents:` list
3. Define workflow, tools, constraints in the AGENT.md
4. Read-only agents: add "Tools NOT Allowed" deny list
### Adding a Hook
1. Create executable script in `hooks/{name}`
2. Add entry to `hooks/hooks.json` with event, matcher, async, timeout
3. Brand output with `🏛️ ATLAS │ {emoji}{severity} {CATEGORY} │ {message}`
4. Build copies all executable hooks automatically (wildcard)
### Adding a Reference
1. Create `skills/refs/{name}/SKILL.md`
2. Add to profile under `refs:` list
## ONBOARDING & DOCTOR
- `/atlas setup` — 5-phase wizard (profile, credentials, env, context, optional)
- `/atlas doctor` — 8-category health dashboard with auto-fix
- First-run: SessionStart hook detects missing `~/.atlas/profile.json` → shows `👋 FIRST RUN`
- Storage: `~/.atlas/` (profile.json, doctor-report.json)
- Both skills available in ALL tiers (user, dev, admin)
## VERSION BUMP CONVENTION
Auto-release CI bumps version on push to `main` using conventional commits:
| Commit Type | Bump | Example |
|------------|------|---------|
| `feat(scope):` | **minor** (4.42.0 → 4.43.0) | `feat(plugin): add orchestration` |
| `fix(scope):` | **patch** (4.42.0 → 4.42.1) | `fix(ci): runner config` |
| `perf(scope):` | **patch** (4.42.0 → 4.42.1) | `perf(plugin): model allocation` |
| `feat!(scope):` / `BREAKING CHANGE` | **major** (4.42.0 → 5.0.0) | Breaking changes |
| `chore\|docs\|build\|ci\|refactor\|test\|style` | **NO bump** (skipped) | Non-functional |
**Keyword overrides (Phase 1 H5)** :
- Include `[no-release]` in commit body → release skipped EVEN for feat/fix (use for fast-follow hotfixes)
- Include `[release]` in commit body → release fires even for chore/docs (use for docs-only milestones)
**Manual release**: `make publish-patch` (or `publish-minor`) — bumps, builds, tests, tags, pushes.
**NEVER use** `build(v4.X.0):` for version bumps — auto-release ignores this pattern.
## ORCHESTRATION (Opus → Sonnet)
Main session = **Opus 4.7 [1m]** (orchestrator). Subagents = **Sonnet 4.6** (workers).
Both models have 1M context — the differentiator is reasoning quality, not context size.
| Task | Model | Why |
|------|-------|-----|
| Planning, architecture, brainstorm | Opus | GPQA +17pts, adaptive thinking (xhigh/max effort) |
| Implementation, tests, review, DB migration | Sonnet | SWE-bench gap 1.2pts, 5x cheaper, 2.7x faster |
| Validation, search | Haiku | Cheapest capable |
| Lint, format, type-check | DET (bash) | Zero AI tokens |
**Complexity Gate**: TRIVIAL (solo) → MODERATE (Sonnet ad-hoc dispatch) → COMPLEX (full pipeline).
**Context Distillation**: ~20K tokens focused prompt per subagent, never full session dump.
**Details**: `skills/refs/model-benchmarks-2026-04/SKILL.md`
## SELF-DEVELOPMENT
This plugin develops itself. When modifying atlas-plugin:
- **Use skill-management** for creating/improving skills
- **Use plugin-builder** for structural changes
- **Use atlas-dev-self** for the full self-development workflow
- **Always run `make test` before commit**
- **Always run `make dev` to install and test in a live CC session**
## KEY FILES
| File | Purpose |
|------|---------|
| `build.sh` | Multi-tier builder with inheritance |
| `scripts/atlas-cli.sh` | Shell launcher (tmux, sessions). See `.blueprint/LAUNCHER-PLAYBOOK.md` |
| `scripts/generate-master-skill.sh` | Dynamic atlas-assist generator |
| `scripts/dev-install.sh` | Build + install to CC cache + sync shell launcher |
| `profiles/*.yaml` | Tier definitions |
| `hooks/hooks.json` | Hook registry |
| `Makefile` | Dev workflow shortcuts |
| `VERSION` | Semver SSoT |
| `tests/conftest.py` | Test fixtures + constants |
| `.forgejo/workflows/ci.yaml` | CI (test on push/PR) |
| `.forgejo/workflows/publish.yaml` | Release (build on tag) |
## CONTEXT LOADING (Lazy)
| Need | Read |
|------|------|
| AXOIQ vision + Synapse concepts | `.blueprint/VISION.md` |
| Build system deep dive | `.blueprint/ARCHITECTURE.md` |
| Skill catalog (48 skills) | `.blueprint/SKILL-CATALOG.md` |
| Integration mapping | `.blueprint/INTEGRATION-MAP.md` |
| Copy-paste patterns | `.blueprint/PATTERNS.md` |
| Test strategy | `.blueprint/TESTING.md` |
| All docs index | `.blueprint/INDEX.md` |
## TESTING
15 test files covering:
- `test_skill_frontmatter` — name, description, effort in every SKILL.md
- `test_skill_coverage` — no orphan skills (except atlas-assist source)
- `test_profiles` — YAML inheritance chain
- `test_build_output` — dist/ artifact completeness
- `test_version_sync` — VERSION matches all manifests
- `test_cross_references` — skills ↔ profiles aligned
- `test_regression_gate` — structural integrity (no commands/ dir)
- `test_hooks_schema` — hooks.json validity
- `test_hook_behavior` — hook script execution
- `test_agent_frontmatter` — agent spec completeness
- `test_manifest` — plugin.json validity
- `test_no_hardcoded_paths` — portability
- `test_skill_quality` — documentation quality
Bats tests (manual, no CI wiring yet due to `.claude/rules/ci-config-freeze-week1.md`):
- `tests/bats/test-atlas-resolve-version.bats` — 9 resolver scenarios
- `tests/bats/test-atlas-discover-and-hook.bats` — 8 discover/hook/prune scenarios
- Run: `bats tests/bats/`
## VERSION RESOLVER (v5.30.0+)
The status line reads `~/.atlas/runtime/capabilities.json` via a 3-tier fallback:
```
Tier 0: ~/.atlas/runtime/.resolve-version.cache (mtime < 5s — fast path)
Tier 1: claude plugin list --json (canonical SSoT)
Tier 2: capabilities.json (SessionStart snapshot)
Tier 3: filesystem scan (zero-dep fallback)
```
Drift sentinel: `~/.atlas/runtime/.capabilities.stale` — touched by resolver when
Tier-1 disagrees with capabilities.json. Read by `capabilities-refresh` hook on
UserPromptSubmit → rerun discover + delete sentinel. Max 1×/turn. See ADR-006.
## COMPACTION
Preserve: modified file paths, VERSION, branch, tier being built, test failures,
build.sh changes, skill frontmatter changes, hook additions.
SSoT = VERSION file. Always `make test` before commit.
Memory: `~/.claude/projects/-home-sgagnon-workspace-atlas-projects-atlas-dev-plugin/memory/`