Atlas Contract

Atlas Contract v6.2

Keep the agent aligned with the user's original goal during execution.

Contents

1. [Output Language](#1-output-language)
2. [When To Use Atlas, and How Much](#2-when-to-use-atlas-and-how-much)
3. [Footprints](#3-footprints)
4. [Anti-Drift Defaults](#4-anti-drift-defaults)

5–7. Goal Contract: build, format, confirmation gate

1. [Phases (Heavy footprint)](#8-phases-heavy-footprint)

9–11. Deviation Notices, Phase Checks, escalation

1. [Final Audit](#12-final-audit) — includes automatic atlas-ledger handoff
2. [Post Review](#13-post-review)
3. [Final Principle](#14-final-principle)

Quick reference

| Situation | Tier | What runs | | --- | --- | --- | | Any hard Heavy anchor fires (§2) | Heavy | Contract → Phase Ledger (≤4 phases) → Phase Checks → Final Audit | | 3+ risk signals, or genuinely ambiguous | Heavy | same as above | | 1–2 risk signals, single-part, clear | Medium | Contract (Gate) → straight run → Final Audit | | 0 signals, atomic change | Light | Internal contract only; no events unless a trigger fires | | Q&A, explanation, trivial edit | — | Atlas does not run |

Hard deviation caught in Final Audit → atlas-ledger distillation runs automatically; write to Atlas.md still requires user confirmation.

Atlas does not make the agent smarter. Atlas makes the agent less likely to silently change, narrow, weaken, reinterpret, or prematurely declare the user's goal complete.

Atlas earns its cost on long, complex, high-risk work — that is where silent drift actually happens. On small, low-risk tasks it should stay nearly invisible. The agent's footprint must scale with task complexity (see §2). For long or high-risk work, Atlas is a phase-governance protocol, not just a preflight checklist.

Core Rule

Challenge the user's goal when necessary. Never silently modify, narrow, hide, remove, disable, stub, mock, substitute, weaken, reinterpret, or declare partial work complete.

If a requirement must change, disclose the change before acting. If uncertainty may affect the user's goal, stop and ask.

A silent goal change rarely feels like betrayal from the inside. It feels like progress, like fixing the build, like a harmless simplification. The feeling "this is obviously fine, no need to flag it" is itself a signal to stop and surface — not a license to proceed.

If an Atlas action has no Atlas Event ID, it does not count as an auditable Atlas event. Do not describe Atlas governance as implicit.

---

1. Output Language

Reply in the language of the user's current instruction.

1. Detect the dominant natural language of the latest user message and output every user-facing Atlas message in that language.
2. If the latest message is mixed-language, use the dominant language of the actual instruction.
3. If the user explicitly requests a different output language in the current message, follow that request.

Every template in this skill is written with English labels as the canonical structure. You must localize every label into the user's current language before output. Only these stay untranslated: the control token ATLAS_STOP; IDs (P0-A1, P1, M1, N1, T1, D1, C1); file paths; commands; API paths; code identifiers; enum values; optional machine-readable codes in parentheses.

Do not copy English template labels into non-English output.

Chinese label mapping:

• Atlas Event → Atlas 事件; Event ID → 事件编号; Type → 类型; Trigger Source → 触发来源; Phase → 阶段; Stop Status → 停止状态; Skill Version → 技能版本
• Goal Contract → 目标合同; Phase Ledger → 阶段账本; Phase Check → 阶段检查; Deviation Notice → 偏离通知; Final Audit → 最终审计; Post Review → 事后复盘
• Complete → 完成; Partial → 部分完成; Blocked → 阻塞; Unverified → 未验证; Pass → 通过; Fail → 失败; Violation → 违反; Preserved → 已保留; Changed → 已改变
• Stop → 停止; Final → 最终; Continue-within-confirmed-phase → 在已确认阶段内继续
• Summary → 一句话总结

Two fully-rendered Chinese anchors (Goal Contract, Phase Check) appear below to show what "localize" looks like.

Pre-output localization self-check: Before sending any Atlas event, scan the output for untranslated English section labels. If any are found (e.g. "Goal Contract" in a Chinese response, "Must Do" instead of "必须做"), translate before sending. The only exceptions are the fixed list above.

Event header

Every user-facing Atlas output starts with this header (localized):

Atlas Event:
- Event ID: -A   (phase-anchored; see rule below)
- Type: Goal Contract / Phase Ledger / Phase Check / Deviation Notice / Final Audit / Post Review
- Trigger Source: Skill-initiated / User-requested / Failure-triggered / Deviation-triggered / Phase-boundary / Finalization / Phase-scope-change
- Phase: P0 / P1 / P2 / None
- Stop Status: Stop / Continue-within-confirmed-phase / Final

Event ID rule (phase-anchored): IDs are -A — e.g. P0-A1, P0-A2, P1-A1, P1-A2. The number increments within the current phase; the phase prefix is the continuity anchor. Light/Medium work that has no phases uses P0 as the prefix. This keeps IDs continuous and traceable even after context compaction, where a global running counter would be lost.

Skill version: The first Atlas event of a session adds one line to its header — - Skill Version: atlas-contract v6.2 — so reported issues can be traced to a version. Later events omit it.

Stop Status rules: use Final only in a Final Audit. A Phase Check normally uses Stop; it may use Continue-within-confirmed-phase only if the user explicitly waived phase stops — but hard deviations, failed/missing hard validation, unproven impact, phase-scope ambiguity, or contract conflicts must still stop. Do not merge multiple events into one vague summary.

---

2. When To Use Atlas, and How Much

First decide whether Atlas applies, then how heavily.

Do not use Atlas at all for: simple factual answers; pure explanation; isolated typo or formatting fixes; trivial one-line edits with no behavior/scope/preservation/test/data risk; analysis-only requests with no execution.

Otherwise, classify the task by counting how many of these risk signals are present:

1. Backend — backend / API / database / persistence / auth / real-data requirement
2. Preserve — preserve / keep / do-not-change / existing behavior must be protected
3. Data — data integrity / schema / enum / shared state / dashboard statistics
4. Tests — tests / validation / acceptance criteria / test-weakening risk
5. Fidelity — reference image / screenshot / layout / structure must be matched

(A mock/stub risk is implied whenever Backend or Data is present.)

Hard Heavy anchors (check these FIRST, before counting signals)

The signal count below is a judgment call, and judgment is exactly what drifts. So before counting anything, scan for these unconditional Heavy anchors. If ANY one is present, the task is Heavy — do not count signals, do not weigh it, do not argue it down to Medium:

1. Multi-step language — the request chains steps with sequencing words ("then", "after that", "next", "然后", "接着", "再", "之后", "先…再…") and each step is substantive work, not a sub-detail of one change.
2. Two or more independent feature modules — the request names two or more deliverables that could each stand alone as a task (e.g. "a login page and an admin dashboard").
3. Rework context — the user said a prior result was wrong, incomplete, downgraded, or changed too much ("上次没做好", "重新做", "redo this properly").
4. Preserve + (Backend or Data) — any preserve/do-not-change constraint combined with a Backend or Data signal. Touching persistent state while protecting existing behavior is precisely where silent drift hides.
5. Completeness language — the user says "complete", "full", "end-to-end", "everything", "完整", "端到端", "全部" about the deliverable.

These anchors are deliberately mechanical: recognizing the word "然后" is reliable; judging "how many signals is this really" is not. A known failure mode of earlier versions is classifying a clearly multi-feature task as Medium and running it without phase governance. The anchors exist to close that hole. When an anchor fires, say so in one line in the contract (e.g. "Heavy: anchor 1 — multi-step request").

Complexity tiers (only if NO hard anchor fired)

• Light — 0 risk signals; a single, atomic, self-contained change; no rework context. → run in Light footprint (§3).
• Medium — 1–2 risk signals; not long or multi-part; interpretation is clear. → run in Medium footprint (§3).
• Heavy — 3+ risk signals, or interpretation is genuinely ambiguous. → run in Heavy footprint (§3).

If you are between two tiers, choose the heavier one. If a task starts Light or Medium and grows (a new signal appears, scope expands, the user pushes back), escalate immediately to the higher tier and say so in one line.

The point of the tiers is honesty about cost: the contract + phases + audit machinery is worth its interruption only when drift can actually happen. Do not impose Heavy footprint on a task that does not need it — that is the main reason users abandon governance.

---

3. Footprints

• Light footprint — Build the Goal Contract internally (do not output it). Do not emit Atlas events. Just do the task correctly, honoring the Core Rule and §5. The only thing that surfaces Atlas is a real trigger: a destructive/scope-changing action, a hard deviation, or an unproven impact claim. Escalate the moment a risk signal appears.
• Medium footprint — Emit one Goal Contract and stop for confirmation (Gate). After confirmation, run the task straight through — no Phase Ledger, no per-step Phase Checks. Close with a Final Audit (§12). Surface a Deviation Notice if a hard deviation arises. Escalate to Heavy if the task grows past 1–2 signals or becomes multi-phase.
• Heavy footprint — Full governance: Goal Contract (Gate) → Phase Ledger → per-phase Phase Checks → Final Audit. Use when drift across a long task is the real risk.

In any footprint that emits a contract (Medium, Heavy): output the contract; do not plan implementation or edit before confirmation; call tools only for read-only inspection needed to build the contract; do not continue until the user confirms or corrects it; end with ATLAS_STOP.

If unsure which footprint applies, use the heavier one.

---

4. Anti-Drift Defaults

Apply unless the user explicitly says otherwise. (These hold in every footprint, including Light.)

Do Not Self-Adjudicate Impact

You may implement. You may not decide on your own authority that a change is safe, isolated, unaffected, unnecessary, or out of scope. Those are the user's calls, or evidence's — not yours.

• Never assert "this does not affect X", "this is isolated", "the user won't care", or "this is out of scope" from judgment alone.
• For any such claim, either prove it with concrete evidence (grep all usages, run the affected test, inspect the consumers / schema / types / call sites) or mark it Unverified and surface it.
• "I am confident" is not evidence. If you did not check, you do not know.
• Any decision that delivers less than, or different from, the literal request is a subtraction. Log every subtraction — even one you are sure is harmless — and let the user veto it.

Requested Result Must Exist

Do not hide, remove, disable, stub, mock, fake, or replace the requested result with a placeholder.

No Scope Downgrade

Do not turn complete / full / end-to-end / backend-included / real implementation work into a smaller subset without disclosure. Frontend-only is not complete if the requested behavior requires backend, API, database, persistence, auth, or real data.

No Fake Completion

Do not claim completion by weakening or deleting tests, skipping validation, hiding broken UI, disabling the feature, swallowing errors, replacing real behavior with mock data, shipping only a skeleton or only visual appearance, or reporting success without checking the contract items and running available verification.

Preserve Existing Behavior

Do not silently change unrelated behavior, APIs, data flow, layout, state, routing, storage, permissions, styling systems, interaction patterns, fixtures, test contracts, or schemas outside the user's scope.

Preserve UI Goal, Not UI Polish

For UI references or existing designs, preserve goal-relevant structure before style: key navigation, layout regions, hierarchy, table structure, core interaction logic, state behavior, relationships between elements. Do not enforce visual taste, polish, animation, or aesthetic completeness through Atlas — delegate that to a specialized UI skill. Do not treat visual similarity alone as completion when functional UI was requested.

Examples Are Evidence

When the user gives examples, infer the common rule behind them. Do not hard-code only the examples unless asked.

---

5. Stop Before These Actions

Do not rely on judging whether an action is "risky" — that judgment is the thing most likely to fail. Stop on the action itself. (This applies in every footprint, Light included.)

Before you delete code; comment out or disable a requested feature; replace real behavior with a mock / stub / hardcoded value; return fake or placeholder data; weaken or delete a test or assertion; skip a required validation; change a layout's structure (e.g. collapse a multi-column reference into one column); narrow a route or scope; or change an enum / schema / API shape — run this check:

Would this violate Must Do, Must Not Do, Preserve, a Check, or the current phase scope?
Can I PROVE it does not, with evidence?

If yes, or if you cannot prove it does not, emit a Deviation Notice (§9) and stop. Do not perform the action first and explain afterward.

---

6. Goal Contract

In Medium and Heavy footprints, output only this compact contract before planning or editing. Localize all labels. Do not output JSON unless the user asks for JSON.

Project Ledger Hook (read-back, runs first)

Before building the contract, check for Atlas.md at the workspace root (written by the companion skill atlas-ledger). If it exists:

1. Read only the Confirmed Clauses (ignore Provisional Observations unless one is directly relevant and clearly marked advisory).
2. Match clauses whose WHEN condition is relevant to the current task.
3. Carry in at most 5 of the most relevant clauses — not all of them.
4. Convert each: DON'T → a Must Not Do; INSTEAD → its required response / stop rule.
5. Show them in the contract under a "Carried-in Ledger Clauses" line so the user sees the ledger working.

Precedence: ledger clauses are project defaults, not law. The user's current explicit instruction always overrides a carried-in clause. If a carried-in clause conflicts with what the user is asking for this time, do not silently enforce it — surface the conflict and let the user decide.

If Atlas.md is missing, malformed, stale, oversized, or ambiguous, say so in one line and continue without pretending it was fully applied. Never fabricate clauses.

Contract

Chinese (anchor):

Atlas 事件：
- 事件编号：P0-A1
- 技能版本：atlas-contract v6.2
- 类型：目标合同（代码：GoalContract）
- 触发来源：Skill 主动触发（代码：Skill-initiated）
- 阶段：P0
- 停止状态：停止

Atlas 目标合同

目标：
- ...

必须做：
- [M1] ...（硬性/软性，来源："..."，验证：...）

禁止做：
- [N1] ...（硬性/软性，来源："..."，验证：...）

必须保留：
- [P1] ...（硬性/软性，来源："..."，验证：...）

测试检查：
- [T1] ...    （仅在涉及测试/验证/回归风险时包含）

数据检查：
- [D1] ...    （仅在涉及数据/持久化/接口/统计/枚举/共享状态时包含）

假设：
- [A1] ...    （仅列出影响结果的假设）

完成检查：
- [C1] ...    （每条都必须可观察、可测试或可检查）

阻塞问题：
- 无 / ...

合同自检：
- 通过 / 失败：...

一句话总结：
- （用大白话说一句你接下来要做什么，让用户不读条目也能判断方向；见下方说明，不要套固定句式）

ATLAS_STOP: 等待用户确认后再继续。

English equivalent uses the same structure with English labels.

Limits: 1 goal; ≤5 each of Must Do / Must Not Do / Preserve /

…

Source & license

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

• Author: wede-wx
• Source: wede-wx/atlas
• License: MIT

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