@arjunkhera/atlas 0.3.8 → 0.3.10

package/skills/sdlc-task/SKILL.md

@@ -49,8 +49,9 @@ does not repeat those rules; follow the lead.
 **A change after the owner approved a design** is not a new lock. Say so at
 once, and never build against a sentence you know is wrong. Show the owner the
 change in one screen. When the owner approves it, record the owner's words with
-`decision_record` on the same item, and write the change into the design file
-with the date. (Target design, flow 4: long frozen texts with hashes retire.)
+`decision_record` on the same item. Name the part it touched, and change
+that part in the design folder. (Target design, flow 4: long frozen texts
+with hashes retire.)
 
 ## start
 
@@ -64,12 +65,12 @@ with the date. (Target design, flow 4: long frozen texts with hashes retire.)
    (`registry_list`); it may be `main` or `master`. Branch from it, and never
    commit to it. Local sessions use `feature/`, `fix/` or `chore/`; cloud
    sessions use `claude/`. The pull request targets that branch.
-4. **Design doc** (standard and above): copy
-   [`templates/design-doc.md`](templates/design-doc.md) to
-   `docs/design-docs/<slug>.md`, fill the Summary and Part 1, and list it in
-   `docs/index.md` in the commit that first lands it. Hotfix tier skips the
-   doc: the definition of done lives on the work item, and a resume anchor
-   covers pauses.
+4. **Design** (standard and above): follow [`design/README.md`](design/README.md).
+   Pick the kinds, and say why. Make the folder `docs/design-docs/<slug>/`
+   with `design.yaml`, then write the Summary, Your words and Goals first.
+   Read the template for each part in `design/parts/`. List the folder in
+   `docs/index.md` in the commit that first lands it. Hotfix tier skips the design: the definition of done lives on
+   the work item, and a resume anchor covers pauses.
 5. Enter the design loop.
 
 ## The design loop (between start and lock)
@@ -85,16 +86,17 @@ Talk to the owner by the `atlas:lead` skill. What this loop adds:
   they presume was ever decided.** A bug report says the code surprised
   someone; it does not say what the code should do.
 - **User stories before the definition of done.** Never write checks for a
-  flow no story walks through.
-- **The doc accretes in real time.** Every resolved question, decision and
-  approach lands in the design doc as it happens. Record each question with
-  `question_ask`, each answer with `question_answer`, each decision with
-  `decision_record`.
+  flow no story walks through. When the design has a flow a user walks, write
+  its Stories part first, whatever kinds it picks.
+- **The design grows in real time.** Record each question with
+  `question_ask`, each answer with `question_answer` and each decision with
+  `decision_record`, as it happens. The tracker holds them. Change the part
+  the answer touches in the design folder at the same time.
 - **Adversarial review before the owner approves.** Standard tier: at least one
   persona. Initiative: the panel, `atlas:reviewer-pm`, `atlas:reviewer-architect`
   and `atlas:reviewer-security`, each briefed with the doc path, in parallel.
   Brief each one to ask whether the design is the right thing. An unresolved
-  finding goes into the doc's open questions.
+  finding goes to the tracker with `question_ask`.
 
 ## lock
 
@@ -105,17 +107,22 @@ A lock is the owner's approval of a short design (target design, flow 4).
    `lifecycle.yaml` `lock.holds` lists: the definition of done, written as checks; the kind of change, its impact and its undo; and
    each existing test it expects to change. A change that cannot be undone
    shows in bold at the top.
-2. **Show it as a walkthrough page before you ask.** Run `atlas design` and
-   `atlas ste` on the design doc, and fix each finding by hand. Render the
-   page with the `atlas:artifact-renderer` crew, in the walkthrough format,
-   and publish it. Call `item_link` twice: kind `design-doc` for the doc, and
-   kind `artifact` for the page. Link the page from the design doc, and
+2. **Show the design's page before you ask.** Run
+   `atlas design check <folder>` and `atlas ste` on the folder, and fix each
+   finding by hand. A part that needs a custom figure goes to the
+   `atlas:artifact-renderer` crew first. Run
+   `atlas design build <folder> --tracker <item.json>`, with the tracker
+   data that `design/README.md` names. Run `atlas ste` on the page and
+   publish it. Link the folder and the page with `item_link`. Then
    rebuild the hub (see "The design hub" below).
 3. **The owner approves it in the owner's own words.** Gate on
    `lifecycle.yaml` `lock.preconditions`. Record the words with
-   `decision_record`, and mark the design doc "Approved <date>", with the words.
-4. Call `item_lock` with the definition of done as `scope.text` and the design
-   file as `scope.design_doc`. The verb keeps a fingerprint of that text for
+   `decision_record`. The tracker holds the approval; the design file does
+   not.
+4. Call `item_lock` with the definition of done as `scope.text`. Set
+   `scope.design_doc` to a link to the design at the approved commit, such
+   as `https://github.com/<owner>/<repo>/tree/<sha>/docs/design-docs/<slug>`.
+   The verb keeps a fingerprint of that text for
    the tools. No person reads or writes a hash, and no frozen text is copied
    into the doc.
    Rebuild the hub, so the design reads "Building".
@@ -164,8 +171,10 @@ next action. One short paragraph.
    migration reaches the running node after the merge.
 2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
    then a tool, then a skill, then a doc — and say which.
-3. Design doc status: `SHIPPED <date>`.
-4. Rebuild the hub, so the design reads "Shipped".
+3. Rebuild the design's page and the hub, so both read "Shipped". The
+   design folder does not change: the tracker holds the delivery. A design
+   from before 9 October 2026 is one file. Keep its page, and rebuild only
+   the hub.
 
 ## The design hub
 

package/skills/sdlc-task/design/README.md

@@ -0,0 +1,187 @@
+# How to write a design
+
+Every Atlas design has the same spine. It adds the parts of each kind it
+needs. A design keeps no state: the tracker holds anything that changes as
+the work moves. The page shows those facts, read only.
+
+The look was agreed with the owner on 9 October 2026. The boards are on the
+canvas at https://claude.ai/artifact/DP7WmrRzqyGKTkQQQ6Ev8A.
+
+## One home for each fact
+
+| Ask this | If yes, it lives in |
+|---|---|
+| Does it change as the work moves? | The tracker: the stage, splits, questions, answers, decisions, the approval, the lock, changes after approval and the proof. |
+| Does it explain why or how? | The design: the problem, the owner's words, the goals, how it works, the options and their reasons, the contract and the done line. |
+
+## Pick the kinds
+
+Pick one kind or more. One design can mix kinds: an interface change with a
+hard flow is a Contract and a Flow. A part that two kinds need appears once.
+
+| Kind | Pick it when | Example |
+|---|---|---|
+| Decide | There are several ways, and one must win. | Test before merge |
+| Flow | The behaviour is the hard part. | When a test goes red |
+| Contract | An interface, a schema or a command changes. | A document viewer route |
+| Initiative | Many designs serve one goal. | Support for many file types |
+
+Set `shared: true` when many repos use the design, such as Atlas itself.
+Then "Each kind of repo" is needed. For a design in one product it is
+optional.
+
+## All parts by kind
+
+`needed` means the check fails when the part is missing or empty.
+`shared` means needed when the design is shared. `—` means the kind does
+not use the part. The registry is [parts.yaml](parts.yaml), and a test keeps
+this table equal to it.
+
+| Part | File holds | Decide | Flow | Contract | Initiative |
+|---|---|---|---|---|---|
+| Summary | `summary` | needed | needed | needed | needed |
+| Your words | `words` | needed | needed | needed | needed |
+| Goals and non-goals | `goals` | needed | needed | needed | needed |
+| Problem today | `problem` | needed | if it applies | if it applies | — |
+| Yardstick | `yardstick` | needed | — | — | — |
+| Proposal | `proposal` | needed | — | — | — |
+| Alternatives | `alternatives` | needed | if it applies | if it applies | — |
+| Scorecard | `scorecard` | needed | — | — | — |
+| Build list | `build` | needed | if it applies | if it applies | — |
+| Who and what | `actors` | if it applies | needed | if it applies | — |
+| Stories | `stories` | if it applies | needed | if it applies | — |
+| Edge cases | `edges` | if it applies | needed | if it applies | — |
+| Records | `records` | — | needed | if it applies | — |
+| States | `states` | — | if it applies | — | — |
+| Routes and interface | `routes` | — | — | needed | — |
+| Calls and answers | `calls` | — | — | needed | — |
+| Data change | `data` | — | — | needed | — |
+| Migration and undo | `migration` | — | — | needed | — |
+| Security | `security` | if it applies | if it applies | needed | — |
+| Rollout | `rollout` | if it applies | if it applies | needed | — |
+| Why one initiative | `why` | — | — | — | needed |
+| Shared decisions | `shared-decisions` | — | — | — | needed |
+| Order and dependencies | `order` | — | — | — | needed |
+| Risks | `risks` | needed | needed | needed | needed |
+| Test and proof plan | `proof` | needed | needed | needed | — |
+| Each kind of repo | `repos` | shared | shared | shared | — |
+| Change and undo | `change` | needed | needed | needed | if it applies |
+| Done line | `done` | needed | needed | needed | needed |
+| Key | `key` | needed | needed | needed | needed |
+
+The page also shows six parts from the tracker: Questions, Decisions,
+Approval and lock, Since approval, Family and Roll-up. No file holds them.
+The builder counts the Roll-up from the Family list.
+
+## What the lock needs
+
+The lock reads `lock.holds` and `lock.preconditions` in `lifecycle.yaml`.
+Each one has a home:
+
+| The lock needs | Where it lives |
+|---|---|
+| The definition of done | The Done line part |
+| The kind of change, its impact, its undo and the tests it changes | The Change and undo part |
+| The chosen approach | The Proposal part of a Decide design. In the other kinds, the design itself is the approach. |
+| No open question | The tracker: `needs_me` shows none for the item |
+| The owner's approval in his own words | The tracker: `decision_record` |
+
+## Tier and kind
+
+The tier (hotfix, standard or initiative) sets how much process the work
+gets. The kind sets which parts the design has. The two are separate: an
+initiative-tier piece of work can be a Decide design, and an Initiative
+design holds a family of designs.
+
+At initiative tier, a Decide design goes deep:
+
+1. The Problem today part has a figure of today. The Proposal part has a
+   figure of the target.
+2. At least two options get full depth in Alternatives: their costs, their
+   risks and why each one lost.
+
+At standard tier, one chosen approach and one rejected option are enough.
+
+## What we kept from the Engram template
+
+Every section of the Engram design template has a home. The sections that
+change as work moves went to the tracker.
+
+| Engram section | Its home now |
+|---|---|
+| Status, container, tier | The top strip, read from the tracker |
+| Context and goal | Your words and Summary |
+| Goals, non-goals, success metrics | Goals and non-goals |
+| Flows | Flow kind: Stories and States |
+| User stories | Flow kind: Stories, one walkthrough each |
+| Architecture | The Summary figure, the Proposal, and the Contract parts |
+| Approaches considered | Decide kind: Alternatives and Scorecard |
+| Open and resolved questions | Tracker: Questions |
+| Decision log | Tracker: Decisions. The reasons stay in the design. |
+| Risks and failure modes | Risks |
+| Test and eval plan | Test and proof plan |
+| Acceptance criteria | Done line |
+| Lock block | Tracker: Approval and lock |
+| Deviation log | Tracker: Since approval, with the part each change touched |
+
+## The folder
+
+```text
+docs/design-docs/<slug>/
+  design.yaml      title, item, product, kinds, shared, look
+  summary.md       ---
+                   part: summary
+                   ---
+                   # Summary
+                   ...
+  words.md         part: words
+  ...
+```
+
+1. Name each file as you like. The `part:` line in its front matter says
+   which part it is.
+2. `design.yaml` holds what the design is, never where it stands. Its keys
+   are `title`, `item`, `product`, `kinds`, `shared` and `look`. `look`
+   links a mock or a canvas. The tracker holds the link to the published
+   page.
+3. When the repo's docs lint needs every page linked from an index, add an
+   `index.md` that links each part file. The check then makes sure it links
+   all of them.
+4. A part file may have a `title:` line. The page then uses it as the
+   heading of the part.
+
+## Write each part
+
+1. Read the template for the part in [parts/](parts/). It says what the
+   part holds, the rules for it and a short example.
+2. Write the part in your own file. Do not copy the template.
+3. Write "No change" and the reason when a needed part does not apply.
+   An empty part fails the check.
+4. Put every code you use, such as `US-3` or `M1`, in the Key.
+5. Never write a state line, such as "Status: approved". The check flags it.
+
+## Figures
+
+1. Use a woodcut figure when a stock figure fits: a flow chart, a sequence,
+   a state machine or swim lanes. Use a fenced block with the info string
+   `woodcut wc-<type>`. It holds the figure data as JSON, in the woodcut
+   shape.
+2. Draw your own figure when the subject has its own shape. Git lanes, a
+   time line and a data diff are examples. Use a fenced block with the info
+   string `figure`. It holds the HTML. Use the page tokens, such as
+   `var(--accent)` and `var(--line)`, so the figure works in both themes.
+3. Both kinds follow the same rules. A step has a title and one or two
+   sentences. The reader sets the pace. The figure prints as stills.
+   Meaning is never by colour alone.
+
+## Check and build
+
+1. Run `atlas design check <folder>`. Fix each finding by hand.
+2. Read the item, its questions, decisions and links with the Atlas tools.
+   Copy their fields into one JSON file, as the tools return them. The
+   shape is at the top of `door/lib/design-build.mjs`. The builder
+   refuses a field that the tracker does not hold.
+3. Run `atlas design build <folder> --tracker <item.json>`. It writes the
+   page only when the check is GREEN. `--draft` builds a page marked as a
+   draft.
+4. Run `atlas ste` on the page, then publish it.

package/skills/sdlc-task/design/parts/actors.md

@@ -0,0 +1,26 @@
+# Who and what
+
+It holds: The people, agents and systems in the flow.
+
+Needs: Decide: optional, Flow: needed, Contract: optional, Initiative: none.
+
+Rules:
+
+1. Name each person, agent and system in the flow.
+2. Say what each one may do, and what it may not do.
+3. Use the same names in the stories.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: actors
+---
+# Who and what
+
+| Who | Does |
+|---|---|
+| Owner | Merges. |
+| Lead | Opens the pull request. Never merges. |
+| Gate | Runs the tests. |
+````

package/skills/sdlc-task/design/parts/alternatives.md

@@ -0,0 +1,24 @@
+# Alternatives
+
+It holds: The other options, and why each one lost.
+
+Needs: Decide: needed, Flow: optional, Contract: optional, Initiative: none.
+
+Rules:
+
+1. List each option we did not pick, and why it lost.
+2. Keep the reason to one or two sentences.
+3. Say what we keep from it, if anything.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: alternatives
+---
+# Alternatives
+
+| Option | Why it lost |
+|---|---|
+| Run after the merge | A red test reaches master. |
+````

package/skills/sdlc-task/design/parts/build.md

@@ -0,0 +1,23 @@
+# Build list
+
+It holds: The pieces to build, in order.
+
+Needs: Decide: needed, Flow: optional, Contract: optional, Initiative: none.
+
+Rules:
+
+1. List the pieces to build, in order.
+2. Each piece is small enough for one pull request.
+3. Say what each piece waits on.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: build
+---
+# Build list
+
+1. The gate workflow. Waits on nothing.
+2. The merge rule. Waits on 1.
+````

package/skills/sdlc-task/design/parts/calls.md

@@ -0,0 +1,25 @@
+# Calls and answers
+
+It holds: A real call and its real answer for each entry of the interface. A schema repo shows a real query; a plugin shows a tool call.
+
+Needs: Decide: none, Flow: none, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Show one real call and its real answer for each route.
+2. Show one call that is refused, and its answer.
+3. Say where the example values come from.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: calls
+---
+# Calls and answers
+
+```text
+GET /documents/42/view
+200 OK  content-type: text/html
+```
+````

package/skills/sdlc-task/design/parts/change.md

@@ -0,0 +1,27 @@
+# Change and undo
+
+It holds: The kind of change, its impact, how to undo it, and each existing test it changes.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: optional.
+
+Rules:
+
+1. Name the kind of change: code, schema, config, docs or a rule.
+2. Say what it touches, how to undo it, and mark in bold a change that cannot be undone.
+3. List each existing test the change edits or removes, and why.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: change
+---
+# Change and undo
+
+| | What |
+|---|---|
+| Kind | Code: the gate workflow. |
+| Impact | Every pull request waits for the tests. |
+| Undo | Revert the pull request. |
+| Tests it changes | None. |
+````

package/skills/sdlc-task/design/parts/data.md

@@ -0,0 +1,22 @@
+# Data change
+
+It holds: The schema or data change. Write "No change" and why, when there is none, as a library or a CLI often does.
+
+Needs: Decide: none, Flow: none, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Show the schema or data change as a diff.
+2. Write "No change" and the reason when there is none.
+3. Name each table or file that changes.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: data
+---
+# Data change
+
+No change. The viewer reads the existing documents table.
+````

package/skills/sdlc-task/design/parts/done.md

@@ -0,0 +1,23 @@
+# Done line
+
+It holds: Lines someone else can check. The approval lives in the tracker.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
+
+Rules:
+
+1. Write each line as a check someone else can run: the input, what happens and the output that passes.
+2. Each line names who runs it and the proof it leaves: a test, a command output or a page.
+3. The approval lives in the tracker, not here.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: done
+---
+# Done line
+
+1. A pull request with a red test cannot merge. The verifier plants a red test; the merge button stays blocked. Proof: the check run link.
+2. `npm test` passes. The verifier runs it. Proof: the test summary.
+````

package/skills/sdlc-task/design/parts/edges.md

@@ -0,0 +1,24 @@
+# Edge cases
+
+It holds: What happens when a step fails or comes in a strange order.
+
+Needs: Decide: optional, Flow: needed, Contract: optional, Initiative: none.
+
+Rules:
+
+1. List what happens when a step fails or comes in a strange order.
+2. Say what the user sees in each case.
+3. Cover a missing input, a retry and a timeout.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: edges
+---
+# Edge cases
+
+| Case | What happens |
+|---|---|
+| The gate times out | The merge stays blocked. The check says it timed out. |
+````

package/skills/sdlc-task/design/parts/goals.md

@@ -0,0 +1,27 @@
+# Goals and non-goals
+
+It holds: What it is for, what it is not, and how we know it worked.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
+
+Rules:
+
+1. List each goal and each non-goal in one table.
+2. A non-goal names something a reader may expect, and says it is out.
+3. End with one line: how we know it worked.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: goals
+---
+# Goals and non-goals
+
+| | What |
+|---|---|
+| Goal | A red test stops the merge. |
+| Non-goal | Running the tests on every push. |
+
+How we know it worked: no merge in a month has a red test after it.
+````

package/skills/sdlc-task/design/parts/key.md

@@ -0,0 +1,25 @@
+# Key
+
+It holds: Every word and code the design uses.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
+
+Rules:
+
+1. List every word and code the design uses that a new reader may not know.
+2. One row for each, with its meaning.
+3. The check flags a code with no row here.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: key
+---
+# Key
+
+| Word | Meaning |
+|---|---|
+| Gate | The check that runs before a merge. |
+| US-1 | The story "a test goes red". |
+````

package/skills/sdlc-task/design/parts/migration.md

@@ -0,0 +1,22 @@
+# Migration and undo
+
+It holds: How old data moves to the new shape, and how the data change is undone.
+
+Needs: Decide: none, Flow: none, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Say how old data moves to the new shape.
+2. Say how to undo the change, step by step.
+3. Mark in bold a change that cannot be undone.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: migration
+---
+# Migration and undo
+
+Undo: revert the pull request. No data moves.
+````

package/skills/sdlc-task/design/parts/order.md

@@ -0,0 +1,24 @@
+# Order and dependencies
+
+It holds: Which design comes first, and what each one waits on.
+
+Needs: Decide: none, Flow: none, Contract: none, Initiative: needed.
+
+Rules:
+
+1. Say which design comes first.
+2. Say what each design waits on.
+3. Draw the order when there are more than three designs.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: order
+---
+# Order and dependencies
+
+1. The shared queue.
+2. The PDF reader, after 1.
+3. The image reader, after 1.
+````

package/skills/sdlc-task/design/parts/problem.md

@@ -0,0 +1,22 @@
+# Problem today
+
+It holds: What happens today, with a real example.
+
+Needs: Decide: needed, Flow: optional, Contract: optional, Initiative: none.
+
+Rules:
+
+1. Say what happens today, with one real example.
+2. Cite the source: a pull request, an issue or a log line.
+3. Do not propose a fix here.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: problem
+---
+# Problem today
+
+Today the tests run after the merge. On 2 October pull request 88 merged, and its tests went red one hour later.
+````

package/skills/sdlc-task/design/parts/proof.md

@@ -0,0 +1,24 @@
+# Test and proof plan
+
+It holds: How each piece proves itself.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Say how each piece proves itself.
+2. Prefer a test that fails when the code is wrong.
+3. Name the command that runs it.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: proof
+---
+# Test and proof plan
+
+| Piece | Proof |
+|---|---|
+| The gate | A planted red test blocks the merge. |
+````

package/skills/sdlc-task/design/parts/proposal.md

@@ -0,0 +1,24 @@
+# Proposal
+
+It holds: The option we pick, and how it works.
+
+Needs: Decide: needed, Flow: none, Contract: none, Initiative: none.
+
+Rules:
+
+1. Name the option we pick, and say how it works in steps.
+2. Give a worked example: the input, the process and the output.
+3. Link the figure that shows it.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: proposal
+---
+# Proposal
+
+1. A pull request opens.
+2. The gate runs the tests on its head.
+3. A red test blocks the merge button.
+````