atlas

Files (7)

• SKILL.md
• __init__.py
• baseline.html
• rationalizations.md · evals/iteration-1/baseline/pressure/
• agent-output.md · evals/iteration-1/baseline/quant/
• rationalizations.md · evals/iteration-1/with-skill/pressure/
• render.py

SKILL.md (first lines)

# /atlas

Survey skill — composes `/tesseract`'s anchor cascade + shelf reads,
`/checkpoint-resume`'s CHECKPOINT.md discovery, current git state, and the
agent's TaskList into one static HTML page at `~/.visual-aid/atlas-<slug>.html`.

**Read-only.** /atlas never writes to the tesseract shelf, bulk-beings,
CHECKPOINT.md, or the TaskList. The output HTML file is the only side effect.

## Arguments

- `--anchor <name>` — explicit anchor (passed as `override=` to
  `resolve_anchor`; skips the auto-cascade).
- `--all` — multi-anchor mode: drop the per-project sections (git, checkpoint,
  tasks); render the shelf only. v1 limitation; see ROADMAP.md Phase 5 follow-up
  entries for Option 2 (cwd-scoped) and Option 3 (per-anchor → project mapping).
- `--out <path>` — override the output path. Default is
  `~/.visual-aid/atlas-<anchor.slug>.html`.

## Process

Follow these steps in order. Collect warnings as you go; they populate
`AtlasInput.warnings` and surface in the rendered page — they never abort.

### 1. Resolve the anchor

```python
from pathlib import Path
from skills._shared.anchor import resolve_anchor
anchor, anchor_warns = resolve_anchor(Path.cwd(), override=args.anchor)
```

`resolve_anchor` walks a four-rung cascade (override → modified-file → branch →
memory), tags the source, slugifies, and returns `(Anchor, list[str])`. Always
call it. Do not hardcode an anchor slug — the cascade IS the contract;
reimplementing it loses the override semantics, the slugify rule, and the
warning population.

### 2. Read the shelf for that anchor

```python
from skills._shared.parse_shelf import parse_shelf
shelf_path = Path.home() / ".tesseract" / "shelf" / f"{anchor.slug}.md"
shelf_entries, shelf_warns = parse_shelf(shelf_path)
```

Missing file returns `([], [])`. Unreadable file returns `([], [warning])`.
Malformed entries are skipped with warnings. Append all returned warnings; keep
going.

### 3. Capture git state

```python
from skills._shared.parse_git import parse_git
git_state, git_warns = parse_git(Path.cwd())  # (None, []) when not a repo
```

Outside a repo, `git_state` is `None` — that is normal empty state, not a
failure.

### 4. Discover and parse CHECKPOINT.md

```python
from skills._shared.parse_checkpoint import parse_checkpoint
checkpoint, ckpt_warns = parse_checkpoint(Path.cwd())
```

Cascade: `cwd/CHECKPOINT.md` → `<repo-root>/CHECKPOINT.md` →
`<repo-root>/.worktrees/<branch-slug>/CHECKPOINT.md`. No file → `(None, [])`.
File found but unparseable → `CheckpointDoc(raw=text, branch="", ...)` plus a
warning — the renderer will display the raw text as a fallback.

### 5. Pull the TaskList (read-only)

Call the harness `TaskList()` tool. Map each entry to a `TaskRecord`:

```python
from skills.atlas.render import TaskRecord
raw_tasks = TaskList()
tasks = [
    TaskRecord(
        id=t["id"],
        subject=t["subject"],
        status=t["status"],
        blocked_by=t.get("blockedBy", []),
    )
    for t in raw_tasks
]
```

Do not call `TaskCreate`, `TaskUpdate`, or any other mutator during this step.
Read only.

**Fallback — Task tools absent from the tool surface.** Some sessions gate
`TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` behind an experiment flag (legacy
`TodoWrite` can be absent too, and headless `-p` sessions are unaffected); when
that happens all four are simply missing, not erroring. Do not abort — fall back
to tracking tasks with a **Markdown table** instead:

| ID  | Subject | Status | Blocked by |
| --- | ------- | ------ | ---------- |

Build `TaskRecord`s from whatever Markdown to-do list is present in cwd (per
this repo's `CLAUDE.md › Tasks, Planning, and Execution`) and continue to step 6
as if `TaskList()` had returned them.

### 6. Build `AtlasInput` and call `render()`

```python
from skills.atlas.render import AtlasInput, render
inp = AtlasInput(
    anchor=anchor,
    shelf_entries=shelf_entries,
    git_state=git_state,
    checkpoint=checkpoint,
    task_list=tasks,
    mode="all" if args.all else "single",
    warnings=anchor_warns + shelf_warns + git_warns + ckpt_warns,
)

From laurac8r/claude-damn, MIT.

More from laurac8r/claude-damn