@arjunkhera/atlas 0.3.22 → 0.3.25

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

@@ -8,7 +8,7 @@ Rules:
 
 1. List the states a thing moves through.
 2. Say what moves it from each state to the next.
-3. Draw it as a state figure.
+3. Draw it as a state figure. The check fails the part with no figure.
 
 Example, in a file of its own:
 
@@ -18,6 +18,22 @@ part: states
 ---
 # States
 
+```woodcut wc-state-machine
+{
+  "label": "A test run",
+  "viewBox": [440, 90],
+  "states": [
+    { "id": "waiting", "x": 10, "y": 30, "w": 100, "h": 32, "label": "Waiting" },
+    { "id": "running", "x": 170, "y": 30, "w": 100, "h": 32, "label": "Running" },
+    { "id": "red", "x": 330, "y": 30, "w": 100, "h": 32, "label": "Red", "terminal": true }
+  ],
+  "transitions": [
+    { "id": "start", "path": "M 110 46 L 168 46", "tip": [168, 46], "tipDir": [1, 0], "label": "tests start", "labelAt": [139, 22] },
+    { "id": "fail", "path": "M 270 46 L 328 46", "tip": [328, 46], "tipDir": [1, 0], "label": "a test fails", "labelAt": [299, 22] }
+  ]
+}
+```
+
 | From | Event | To |
 |---|---|---|
 | Waiting | The tests start | Running |

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

@@ -6,9 +6,18 @@ Needs: Decide: optional, Flow: needed, Contract: optional, Initiative: none.
 
 Rules:
 
-1. Write one walkthrough for each story, step by step.
-2. Each step has a title and one or two sentences.
-3. Give each story a code, such as `US-1`, and put the code in the Key.
+1. Write each story under its own heading, with a code, such as `US-1`.
+   Put the code in the Key.
+2. Give each story a walkthrough figure. The reader steps through it and
+   sees what moves at each step. Use a woodcut figure with a scenario. Give
+   each step a title and one or two sentences. A figure of your own also
+   counts. The check fails a story with no walkthrough figure.
+3. Give each story a worked example with real values: an `Input:` line, the
+   steps, and an `Output:` line. The check fails a story with no worked
+   example.
+4. Pick the figure by the question it answers: `wc-sequence` for "in what
+   order", `wc-swimlane` for "who does it", `wc-flowchart` for "which
+   way", `wc-state-machine` for "what state is it in".
 
 Example, in a file of its own:
 
@@ -20,7 +29,36 @@ part: stories
 
 ### US-1: a test goes red
 
-1. The lead opens a pull request.
-2. The gate runs the tests, and one goes red.
+**Input:** pull request 88 changes `src/pay.mjs`. The test `pay rounds down` fails on it.
+
+```woodcut wc-sequence
+{
+  "label": "US-1: a test goes red",
+  "viewBox": [460, 190],
+  "actors": [
+    { "id": "lead", "x": 70, "label": "Lead" },
+    { "id": "gate", "x": 230, "label": "Gate" },
+    { "id": "owner", "x": 390, "label": "Owner" }
+  ],
+  "messages": [
+    { "id": "open", "from": "lead", "to": "gate", "y": 70, "label": "open pull request 88" },
+    { "id": "red", "from": "gate", "to": "lead", "y": 110, "label": "1 test red", "kind": "return" },
+    { "id": "block", "from": "gate", "to": "owner", "y": 150, "label": "merge blocked" }
+  ],
+  "scenarios": [{
+    "name": "US-1",
+    "steps": [
+      { "title": "The lead opens a pull request", "body": "Pull request 88 changes src/pay.mjs.", "active": ["lead", "open"] },
+      { "title": "The gate runs the tests", "body": "The test pay rounds down fails.", "active": ["gate", "red"] },
+      { "title": "The owner sees the block", "body": "The merge button stays grey and names the failing check.", "active": ["owner", "block"] }
+    ]
+  }]
+}
+```
+
+1. The lead opens pull request 88.
+2. The gate runs the tests, and `pay rounds down` goes red.
 3. The merge button stays blocked, and the owner sees the failing check.
+
+**Output:** the merge button is grey. The check list shows `pay rounds down: failed`.
 ````

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

@@ -7,7 +7,8 @@ Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
 Rules:
 
 1. Lead with the answer: what changes, for whom, and why now.
-2. Keep it to two short paragraphs and one picture.
+2. Keep it to two short paragraphs and one picture. The check fails a
+   Summary with no figure.
 3. A reader who stops here knows the whole design.
 
 Example, in a file of its own:

package/skills/sdlc-task/design/parts.yaml

@@ -12,6 +12,13 @@
 #   none      the kind does not use it
 #   shared    needed when design.yaml says `shared: true`, optional when not
 #
+# A part may say what picture it needs (owner, 21 October 2026: "any user is
+# a visual person, they need to see things flowing to make sense of it"):
+#   picture: one          the part holds at least one figure that draws
+#   picture: each-story   each story holds a walkthrough figure and a worked
+#                         example, with an Input line and an Output line
+# The check reads it whenever the part is in the folder.
+#
 # A design keeps no state. The tracker parts at the end are read from the
 # tracker at build time. No part file may hold them.
 
@@ -50,6 +57,7 @@ parts:
     name: Summary
     group: start
     holds: The answer in a few lines, and one picture.
+    picture: one
     decide: needed
     flow: needed
     contract: needed
@@ -75,6 +83,7 @@ parts:
     name: Problem today
     group: decide
     holds: What happens today, with a real example.
+    picture: one
     decide: needed
     flow: optional
     contract: optional
@@ -91,6 +100,7 @@ parts:
     name: Proposal
     group: decide
     holds: The option we pick, and how it works.
+    picture: one
     decide: needed
     flow: none
     contract: none
@@ -132,6 +142,7 @@ parts:
     name: Stories
     group: flow
     holds: One walkthrough for each story, step by step.
+    picture: each-story
     decide: optional
     flow: needed
     contract: optional
@@ -156,6 +167,7 @@ parts:
     name: States
     group: flow
     holds: The states a thing moves through, and what moves it.
+    picture: one
     decide: none
     flow: optional
     contract: none