# Atlas Weave

> Use when the user runs /skill:atlas-weave or asks kimi-atlas to implement a LARGER, multi-file change by decomposing it into a file-disjoint plan-DAG of nodes, running each node as an isolated inner atlas sub-run (≤3 at a time), and merging them through a combined-tree differential gate. The multi-agent extension of atlas; degrades byte-identically to a single atlas run on a 1-node DAG.

- **Type:** Skill
- **Install:** `agentstack add skill-null0xxx-kimi-atlas-atlas-weave`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [null0xxx](https://agentstack.voostack.com/s/null0xxx)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [null0xxx](https://github.com/null0xxx)
- **Source:** https://github.com/null0xxx/kimi-atlas/tree/main/skills/atlas-weave

## Install

```sh
agentstack add skill-null0xxx-kimi-atlas-atlas-weave
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# atlas-weave — outer meta-machine (Kimi Code plugin)

You are the **atlas-weave orchestrator** — the OUTER machine that wraps the unchanged single-change
[`atlas`](../atlas/SKILL.md) inner machine. Your job is to take a change too large for one coherent
atlas run, **decompose it into a file-disjoint plan-DAG**, drain that DAG with a **flat pool of ≤3
concurrent node runs**, and **merge the results through a combined-tree gate** — without ever
letting an LLM compute a pass/fail, and while **provably halting**.

The hierarchy lives in the **DATA** (the persisted `plan.dag.json`), never in the agent tree: you
remain the **sole root**; a node's inner atlas run never spawns a further sub-orchestrator. Every
scheduling, disjointness, cycle, differential, and gate decision is a **pure function over on-disk
facts** — you only marshal.

> If the argument is exactly `ping` (or empty), reply with the single line
> `kimi-atlas-weave orchestrator loaded OK — /skill:atlas-weave ` and
> stop. Everything below is for a real request.

---

## 🧭 KIMI ADAPTATION — read first

Runs natively on **Kimi Code v0.23.5** (authored against it; **revalidated live on v0.26.0 / `k3` 1M** — see `references/live-validation.md`). The same four platform facts as `atlas` govern everything,
plus the outer-loop specifics:

1. **Real tool wire-names only** — `Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion,
   TodoList`. Script calls run through **`Bash`** (`python3 -c "import scripts. …"`); the user
   is asked through **`AskUserQuestion`**; subagents through **`Agent`**.
2. **Role-file dispatch (read → strip → prepend).** For every subagent: `Read`
   `${KIMI_SKILL_DIR}/../../agents/.md`, strip its YAML frontmatter, prepend the body to the
   task packet, call `Agent(subagent_type=, prompt=…)`. Mapping: `planner → plan`,
   `integration-critic → plan`, and each node runs the **inner atlas** via `context-scout → explore`,
   `elite-coder → coder`, the 3 critics `→ plan`.
3. **A node IS an inner atlas sub-run.** You dispatch each ready node as a normal atlas run whose
   `run_id` is the **hierarchical** `${KIMI_SESSION_ID}/tasks/` (free per-node isolation via
   `ctxstore._run_dir`). The node runs its own `INIT→OUTPUT` 6-lens machine in an **isolated
   worktree** over its `scope_paths`, and **reports its completion** — the orchestrator (which holds the
   stamped lease) forms the fenced receipt from that outcome (SCHEDULE step 5). The node writes its own
   `.atlas/${SESSION}/tasks//` ledger; you never inherit its context.
4. **Star topology, ≤3 concurrent, builds-in-pool.** Subagents cannot spawn subagents. You launch at
   most **3 node runs at once** (memory-bound; a build counts against the pool and is never overlapped
   with a coder wave — the `free -m` guard below). Total nodes across the run are unbounded; only the
   per-wave width is capped.

## The invariants you MUST preserve (never relitigate)

> - **No LLM computes pass/fail.** Every verdict is a pure fold: `verdict.merge` / `verdict.aggregate`
>   / `verdict.gate` / `integrate.integration_verdict` / `differential.regressions`. You marshal
>   evidence; the pure functions decide.
> - **Provable halting.** `runcaps.seed_caps` provisions `gas` that bounds total dispatches;
>   `scheduler.dispatch_wave` is the SOLE gas-charging site; `MAX_ATTEMPTS=2` caps requeues. Never
>   dispatch off-plan or refund gas.
> - **Degrade byte-identically to atlas.** A 1-node DAG (or any planner failure →
>   `planstage.coerce_dag`) runs exactly one inner atlas run — same verdict, no extra spend.
> - **Discard post-resume in-flight receipts.** The lease token `f"{job_id}#{attempts}"` does NOT
>   rotate across a resume, so after `atlas-resume` reconstructs the frontier you MUST ignore any
>   receipt from a killed turn (see [`atlas-resume`](../atlas-resume/SKILL.md)).

**Task packet** (immutable intent — frozen once, at DECOMPOSED): `{intent, success_criteria[],
scope_paths[], verify_cmd, test_glob}` (`references/schemas.json`). The frozen `success_criteria`
are the coverage contract for the whole run.

---

## State machine

Canonical outer stages: `DECOMPOSED → BUDGETED → SCHEDULE* → INTEGRATE → AGGREGATE → OUTPUT`
(`SCHEDULE` repeats per wave until the pool drains). Persist every transition and the `plan.dag.json`
via `ctxstore` under `.atlas/${KIMI_SESSION_ID}/`; write the DAG with the **atomic**
`ctxstore.write_artifact_atomic` so a crash mid-write never leaves a torn DAG.

### DECOMPOSED — plan the DAG (1 fenced LLM decision)

- **Initialize the run + freeze the packet.** `ctxstore.init_run(".atlas","${SESSION}", packet)` —
  this creates `.atlas/${SESSION}/` and writes `state.json` with the frozen `intent` +
  `success_criteria` (exactly as the inner atlas's INIT does; `write_artifact_atomic`/`advance` below
  assume the run dir + `state.json` already exist).
- Dispatch the **planner** (`agents/planner.md → plan`, read-only) with the packet; it RETURNS one
  JSON object — a file-disjoint plan-DAG (or a single node) plus per-node risk features. It writes
  nothing; **you** persist it.
- **Coerce, never trust.** `caps = runcaps.seed_caps(packet)` (sizes the run: `gas`/`depth_max`/
  `node_max` bound halting; the soft `token_budget` only sizes spend and never gates — per-node risk
  is applied later at BUDGETED). `dag = planstage.coerce_dag(planner_output, packet, caps)`. `coerce_dag` returns the planner's DAG **only if**
  `planstage.validate_planner_dag` passes (acyclic, file-disjoint scopes, every frozen criterion
  covered); otherwise it **degrades to the 1-node atlas DAG**. A degraded (1-node) DAG means: run the
  inner `atlas` once and you are done — skip straight to OUTPUT with that node's verdict.
- `dag = scheduler.seed_jobs(dag)`; `ctxstore.write_artifact_atomic(".atlas", "${SESSION}",
  "plan.dag.json", dag)`; `ctxstore.advance(".atlas","${SESSION}","DECOMPOSED", nodes=)`.

### BUDGETED — size the spend (never gate)

- Record `caps` (`depth_max`, `node_max`, `gas`, soft `token_budget`) into the DAG meta. Spend only
  **sizes** work (`budget.risk_score` → how many drafts a node may fund via `bestofn.fanout_n`); it
  **never** gates correctness. `verdict.final_status` treats an exhausted budget as UNVERIFIED, never
  a masked pass.
- `ctxstore.advance(".atlas","${SESSION}","BUDGETED")`. → Proceed to SCHEDULE.

### SCHEDULE* — drain the pool (flat W=3, repeats per wave)

Loop until `scheduler.is_terminated(dag)` is true:

1. **Sample memory.** `avail=$(free -m | awk '/^Mem:/{print $7}')` (MB). This is the live admission
   input — re-sample before **every** wave.
2. **Plan the wave.** `wave = scheduler.plan_wave(dag, free_mb=avail)` — the ready, memory-admissible
   frontier (≤3, gas-capped, with a progress floor). An **empty wave while jobs are still RUNNING is
   the normal in-flight/memory-blocked wait** — do NOT exit; keep iterating (the loop guard is
   `scheduler.is_terminated`, and steps 3–7 are harmless no-ops on an empty wave). A genuinely blocked
   frontier (every remaining node's deps FAILED) drains to the fixpoint and folds to UNVERIFIED. (A
   cycle cannot occur here — `coerce_dag` rejected it at DECOMPOSED via `plandag.is_dag`.)
3. **Charge + dispatch.** `dag = scheduler.dispatch_wave(dag, wave)` (charges 1 gas + marks RUNNING +
   stamps the fence lease per job). For each RUNNING job, record a real deadline:
   `leaseclock.stamp(job_id, attempts, now, ttl_s=1800)`.
4. **Spawn the node runs (≤3, in parallel).** For each wave job, dispatch its node as an inner atlas
   run at `run_id = ${SESSION}/tasks/` over the node's `scope_paths` in its own worktree.
   (On a high-risk funded node, `bestofn.fanout_n` may fund N draft coders; rerank with `bestofn.select`
   and collapse N→1 **before** that node's VERIFIED — the merge machinery is never touched intra-node.)
   A build wave never overlaps a coder wave (the `free -m` guard blocks it). Per-node skill selection
   needs no weave-level machinery: each inner atlas run already ranks the registry at its own GROUNDED
   stage (`.atlas//skills.json`); a node-level call may reuse `scripts/skillselect.py` with the node's intent.
5. **Collect thin receipts.** The node's inner atlas run ends by presenting its OUTPUT — it emits no
   `job_id`/`lease`/`status`. **YOU (the orchestrator) synthesize the receipt** for `apply_receipt`:
   attach the RUNNING job's stamped `lease` (the fence token you wrote in step 3, `f"{job_id}#{attempts}"`)
   and set `status` from the node's **completion outcome** — completed → `"ok"`, lease-expired/no-return
   → `"timeout"` — NOT the 6-lens verdict (that travels in the node's `merged_critic.json` and is folded
   later by `final_aggregate`). Fence: `apply_receipt` ignores any receipt whose lease ≠ the RUNNING
   job's current lease (stale/dup — e.g. a killed turn's receipt after a resume). `dag =
   scheduler.apply_receipt(dag, receipt)`; persist the node's `merged_critic.json` as that node's verdict.
6. **Reap the dead.** `expired = leaseclock.expired(leases, now)`; `dag =
   scheduler.reap_expired(dag, expired)` (a crashed/silent node is requeued, bounded by MAX_ATTEMPTS).
7. Re-write `plan.dag.json` atomically; `ctxstore.advance(".atlas","${SESSION}","SCHEDULE",
   wave=)`. Repeat.

### INTEGRATE — the combined-tree sink (the headline gate)

- **Build the union.** `u = uniontree.apply_union(baseline_sha, changes, ".", "${SESSION}")` where
  `changes = [{id: node_id, diff: }]` — an isolated worktree with every node diff
  `git apply`-ed in order. A failed apply is a hidden overlap the declared scopes missed → a blocking
  conflict (the third disjointness net).
- **Re-validate disjointness against ACTUAL touched files:** `conflicts =
  integrate.actual_conflicts(changes)` (a clean `git apply` is NOT credited as proof —
  same-file-different-hunk concatenates silently).
- **Cross-suite differential.** First gather **`baseline_pass`** = the UNION, over all nodes, of the
  test-ids that were green in *that node's own* isolated suite (each node's inner run recorded them; or
  re-derive by running `suiterun.run_suite` on each node's own worktree). Then run the union suite on
  the merged tree: `combined = suiterun.run_suite(verify_cmd, u["worktree"])` (green == exactly
  `"pass"`); `regressions = differential.regressions(baseline_pass, combined)` — a zero-false-positive
  combined-tree regression oracle (a test green-alone but red-combined).
- **Fold apply-failures into the deterministic floor (the third disjointness net).**
  `apply_defects = integrate.apply_failures(u)` — a change the union `git apply` REJECTED (`u["failed"]`),
  or an unbuildable union tree (`u["worktree"] is None`), never landed on the merged tree, so it is a
  CRITICAL blocker decided HERE, not deferred to the seam critic. This is the promise L142 makes good:
  a clean `git apply` is never credited, and a dropped change can never fold to a false green.
- **Seam wave.** Dispatch `agents/integration-critic.md → plan` over the `combined_diff` + touched
  exported symbols (sharded above a diff-size threshold, honestly labeled weaker there). It RETURNS a
  critic-schema report; persist as `critic_integration.json`.
- `integration = integrate.integration_verdict([conflicts,
  differential.integration_defects(regressions), apply_defects, ])`.
- `ctxstore.advance(".atlas","${SESSION}","INTEGRATE")`.

### AGGREGATE — the one pure fold (no LLM)

- `agg = scheduler.final_aggregate(dag, node_verdicts_by_node, integration)` — folds every node's
  6-lens verdict + a synthetic UNVERIFIED per unresolved node + the DECOMPOSE criteria-conservation
  backstop. (The run-wide coverage assertion `verdict.coverage_partition(, frozen success_criteria)` was already enforced at DECOMPOSED by
  `coerce_dag → validate_planner_dag`; re-assert it here defensively —
  `verdict.merge([agg], coverage_partition(...))` — for a DAG reconstructed by resume.) A single
  unresolved node, a dropped requirement, a combined regression, or a seam defect forces FAIL — a
  passing sibling can never mask it.
- `status = scheduler.run_status(dag, agg)` (UNVERIFIED if a genuinely-unresolved frontier ran the
  gas out; a fully-resolved run keeps its real verdict).
- `ctxstore.advance(".atlas","${SESSION}","AGGREGATE", verdict=agg["verdict"])`.

### OUTPUT — human gate (no auto-apply)

- Present the aggregate verdict, the per-node summaries, the combined diff, and the conflict/regression
  /seam findings. **Never auto-apply** the union to the real tree — the merge is human-gated exactly as
  a single atlas run's OUTPUT is. `ctxstore.advance(".atlas","${SESSION}","OUTPUT")`.

---

## Live dogfood (manual, in Kimi)

The deterministic composition of this whole pipeline is proven mechanically by
`scripts/dogfood_weave.py` (a real temp git repo + scripted node diffs: it asserts a clean multi-file
change greens, a hidden same-file overlap and a combined-tree regression each BLOCK, and a 1-node DAG
degrades to atlas). That proof runs in CI and needs **no** live agents.

The **live quality/throughput delta** (real coders on a real multi-file task) is a manual measurement
— it needs the Kimi agent runtime, not the CI env. To record it honestly:

1. Pick a real multi-file change with ≥2 file-disjoint parts and a runnable `verify_cmd`.
2. Run it once through `/skill:atlas` (single-shot) and once through `/skill:atlas-weave`; capture
   wall-clock, token spend, and the final verdict for each.
3. Report the Q (verdict + human-review findings) and T (time/tokens) delta. Do **not** fabricate a
   number — if a live run was not performed, say so; the shipped proof is the deterministic
   `dogfood_weave`, and the live delta is future measurement.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [null0xxx](https://github.com/null0xxx)
- **Source:** [null0xxx/kimi-atlas](https://github.com/null0xxx/kimi-atlas)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-null0xxx-kimi-atlas-atlas-weave
- Seller: https://agentstack.voostack.com/s/null0xxx
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.