@arjunkhera/atlas 0.3.8 → 0.3.9

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

@@ -0,0 +1,24 @@
+# Records
+
+It holds: The records each step reads and writes.
+
+Needs: Decide: none, Flow: needed, Contract: optional, Initiative: none.
+
+Rules:
+
+1. List each record a step reads or writes.
+2. Say which step writes it, and where it lives.
+3. Name the fields that matter.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: records
+---
+# Records
+
+| Record | Written by | Holds |
+|---|---|---|
+| Check run | The gate | The result and the log link |
+````

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

@@ -0,0 +1,25 @@
+# Each kind of repo
+
+It holds: What the design means for a service, a library, a schema, a CLI and a plugin.
+
+Needs: Decide: shared, Flow: shared, Contract: shared, Initiative: none.
+
+Rules:
+
+1. Say what the design means for a service, a library, a schema, a CLI and a plugin.
+2. Needed when many repos use the design. Optional for a design in one product.
+3. Say what stays the same for every kind.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: repos
+---
+# Each kind of repo
+
+| Kind | What changes |
+|---|---|
+| Service | The gate also waits for the deploy check. |
+| Library | The gate runs the unit tests only. |
+````

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

@@ -0,0 +1,24 @@
+# Risks
+
+It holds: What breaks, and what we do. "Accepted" with a reason is valid.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
+
+Rules:
+
+1. List what can break, and what we do about it.
+2. "Accepted" with a reason is a valid answer.
+3. Put the worst risk first.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: risks
+---
+# Risks
+
+| Risk | What we do |
+|---|---|
+| The gate is slow | Accepted: ten minutes is fine for now. |
+````

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

@@ -0,0 +1,24 @@
+# Rollout
+
+It holds: The order of release, and how we watch it.
+
+Needs: Decide: optional, Flow: optional, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Give the order of release.
+2. Say how we watch it after the release.
+3. Say what makes us roll back.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: rollout
+---
+# Rollout
+
+1. Release behind a flag.
+2. Turn it on for the owner.
+3. Watch the error rate for one day, then turn it on for all.
+````

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

@@ -0,0 +1,24 @@
+# Routes and interface
+
+It holds: Every route, exported function, command, tool or schema object that is added, changed or removed.
+
+Needs: Decide: none, Flow: none, Contract: needed, Initiative: none.
+
+Rules:
+
+1. List every route, function, command or tool that is added, changed or removed.
+2. Mark each row as new, changed or removed.
+3. For a library, list exported functions; for a CLI, commands and flags.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: routes
+---
+# Routes and interface
+
+| | Route | What it does |
+|---|---|---|
+| new | `GET /documents/:id/view` | Returns the viewer page for one document. |
+````

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

@@ -0,0 +1,25 @@
+# Scorecard
+
+It holds: Each option against each yardstick test.
+
+Needs: Decide: needed, Flow: none, Contract: none, Initiative: none.
+
+Rules:
+
+1. Score each option against each yardstick test.
+2. Use words, not only marks: yes, no or part.
+3. The picked option is the first row.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: scorecard
+---
+# Scorecard
+
+| Option | Stops red | Fast |
+|---|---|---|
+| Gate before merge | yes | yes |
+| Run after merge | no | yes |
+````

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

@@ -0,0 +1,22 @@
+# Security
+
+It holds: Who may call it, what it may reach, and what it never leaks.
+
+Needs: Decide: optional, Flow: optional, Contract: needed, Initiative: none.
+
+Rules:
+
+1. Say who may call it, and what it may reach.
+2. Say what it never leaks, and how the tests prove it.
+3. Name the repo's own rules first.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: security
+---
+# Security
+
+Only the document's owner may open the view. A call from another tenant gets 404, and a test proves it.
+````

package/skills/sdlc-task/design/parts/shared-decisions.md

@@ -0,0 +1,24 @@
+# Shared decisions
+
+It holds: The decisions every design in the family follows, and why.
+
+Needs: Decide: none, Flow: none, Contract: none, Initiative: needed.
+
+Rules:
+
+1. List the decisions every design in the family follows.
+2. Give the reason for each one.
+3. Link the tracker decision when one exists.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: shared-decisions
+---
+# Shared decisions
+
+| Decision | Why |
+|---|---|
+| One queue for every reader | One place to watch and retry. |
+````

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

@@ -0,0 +1,25 @@
+# States
+
+It holds: The states a thing moves through, and what moves it.
+
+Needs: Decide: none, Flow: optional, Contract: none, Initiative: none.
+
+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.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: states
+---
+# States
+
+| From | Event | To |
+|---|---|---|
+| Waiting | The tests start | Running |
+| Running | A test fails | Red |
+````

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

@@ -0,0 +1,26 @@
+# Stories
+
+It holds: One walkthrough for each story, step by step.
+
+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.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: stories
+---
+# Stories
+
+### US-1: a test goes red
+
+1. The lead opens a pull request.
+2. The gate runs the tests, and one goes red.
+3. The merge button stays blocked, and the owner sees the failing check.
+````

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

@@ -0,0 +1,33 @@
+# Summary
+
+It holds: The answer in a few lines, and one picture.
+
+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.
+3. A reader who stops here knows the whole design.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: summary
+---
+# Summary
+
+Atlas runs the tests of a pull request before the merge, not after it.
+A red test stops the merge and names the failing check.
+
+```figure
+<svg viewBox="0 0 420 60" role="img" aria-label="Pull request, then tests, then merge">
+  <g font-family="var(--mono)" font-size="13" fill="var(--ink)">
+    <rect x="2" y="14" width="120" height="32" rx="6" fill="var(--card)" stroke="var(--line-strong)"/><text x="20" y="35">Pull request</text>
+    <rect x="150" y="14" width="120" height="32" rx="6" fill="var(--accent-bg)" stroke="var(--accent)"/><text x="188" y="35">Tests</text>
+    <rect x="298" y="14" width="120" height="32" rx="6" fill="var(--card)" stroke="var(--line-strong)"/><text x="336" y="35">Merge</text>
+  </g>
+</svg>
+```
+````

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

@@ -0,0 +1,22 @@
+# Why one initiative
+
+It holds: Why these designs belong together.
+
+Needs: Decide: none, Flow: none, Contract: none, Initiative: needed.
+
+Rules:
+
+1. Say why these designs belong together.
+2. Name the one goal they serve.
+3. Say what would go wrong if each went alone.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: why
+---
+# Why one initiative
+
+Each file type needs its own reader, but all share one viewer and one queue. Alone, each would build its own queue.
+````

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

@@ -0,0 +1,29 @@
+# Your words
+
+It holds: The owner's words, word for word. Claude's reading stays apart.
+
+Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
+
+Rules:
+
+1. Quote the owner word for word, in a block quote, with the date and the place.
+2. Put your own reading after the quote, as a short list headed "What we take from it".
+3. Never change a word inside the quote.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: words
+---
+# Your words
+
+> "I want tests to run before the merge, not after."
+
+The owner, 9 October, in the project thread.
+
+What we take from it:
+
+- A red test stops the merge.
+- The owner sees the failing check, not a log.
+````

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

@@ -0,0 +1,25 @@
+# Yardstick
+
+It holds: The tests every option must pass, set before the options.
+
+Needs: Decide: needed, Flow: none, Contract: none, Initiative: none.
+
+Rules:
+
+1. Set the tests every option must pass before you list the options.
+2. Give each test a short name, so the scorecard can use it.
+3. Keep it to five tests or fewer.
+
+Example, in a file of its own:
+
+````markdown
+---
+part: yardstick
+---
+# Yardstick
+
+| Test | What it asks |
+|---|---|
+| Stops red | Does a red test stop the merge? |
+| Fast | Does the check finish in ten minutes? |
+````

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

@@ -0,0 +1,306 @@
+# The parts of an Atlas design, and which kind needs each one.
+#
+# A design is a folder. design.yaml names its kinds. Each part is one
+# markdown file in the folder, with `part: <id>` in its front matter.
+# The design check reads this file to find a missing or empty part.
+# The page builder reads it for the order and the groups of the rail.
+# The guide in design/README.md shows the same table; a test keeps the two equal.
+#
+# Each part says what each kind needs:
+#   needed    the part must be in the folder and must not be empty
+#   optional  write it when it applies
+#   none      the kind does not use it
+#   shared    needed when design.yaml says `shared: true`, optional when not
+#
+# 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.
+
+kinds:
+  - id: decide
+    name: Decide
+    pick: There are several ways, and one must win.
+  - id: flow
+    name: Flow
+    pick: The behaviour is the hard part.
+  - id: contract
+    name: Contract
+    pick: An interface, a schema or a command changes.
+  - id: initiative
+    name: Initiative
+    pick: Many designs serve one goal.
+
+groups:
+  - id: start
+    name: Start here
+  - id: decide
+    name: Decide
+  - id: flow
+    name: Flow
+  - id: contract
+    name: Contract
+  - id: initiative
+    name: Initiative
+  - id: prove
+    name: Prove it
+  - id: tracker
+    name: From the tracker
+
+parts:
+  - id: summary
+    name: Summary
+    group: start
+    holds: The answer in a few lines, and one picture.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+  - id: words
+    name: Your words
+    group: start
+    holds: The owner's words, word for word. Claude's reading stays apart.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+  - id: goals
+    name: Goals and non-goals
+    group: start
+    holds: What it is for, what it is not, and how we know it worked.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+
+  - id: problem
+    name: Problem today
+    group: decide
+    holds: What happens today, with a real example.
+    decide: needed
+    flow: optional
+    contract: optional
+    initiative: none
+  - id: yardstick
+    name: Yardstick
+    group: decide
+    holds: The tests every option must pass, set before the options.
+    decide: needed
+    flow: none
+    contract: none
+    initiative: none
+  - id: proposal
+    name: Proposal
+    group: decide
+    holds: The option we pick, and how it works.
+    decide: needed
+    flow: none
+    contract: none
+    initiative: none
+  - id: alternatives
+    name: Alternatives
+    group: decide
+    holds: The other options, and why each one lost.
+    decide: needed
+    flow: optional
+    contract: optional
+    initiative: none
+  - id: scorecard
+    name: Scorecard
+    group: decide
+    holds: Each option against each yardstick test.
+    decide: needed
+    flow: none
+    contract: none
+    initiative: none
+  - id: build
+    name: Build list
+    group: decide
+    holds: The pieces to build, in order.
+    decide: needed
+    flow: optional
+    contract: optional
+    initiative: none
+
+  - id: actors
+    name: Who and what
+    group: flow
+    holds: The people, agents and systems in the flow.
+    decide: optional
+    flow: needed
+    contract: optional
+    initiative: none
+  - id: stories
+    name: Stories
+    group: flow
+    holds: One walkthrough for each story, step by step.
+    decide: optional
+    flow: needed
+    contract: optional
+    initiative: none
+  - id: edges
+    name: Edge cases
+    group: flow
+    holds: What happens when a step fails or comes in a strange order.
+    decide: optional
+    flow: needed
+    contract: optional
+    initiative: none
+  - id: records
+    name: Records
+    group: flow
+    holds: The records each step reads and writes.
+    decide: none
+    flow: needed
+    contract: optional
+    initiative: none
+  - id: states
+    name: States
+    group: flow
+    holds: The states a thing moves through, and what moves it.
+    decide: none
+    flow: optional
+    contract: none
+    initiative: none
+
+  - id: routes
+    name: Routes and interface
+    group: contract
+    holds: Every route, exported function, command, tool or schema object that is added, changed or removed.
+    decide: none
+    flow: none
+    contract: needed
+    initiative: none
+  - id: calls
+    name: Calls and answers
+    group: contract
+    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.
+    decide: none
+    flow: none
+    contract: needed
+    initiative: none
+  - id: data
+    name: Data change
+    group: contract
+    holds: The schema or data change. Write "No change" and why, when there is none, as a library or a CLI often does.
+    decide: none
+    flow: none
+    contract: needed
+    initiative: none
+  - id: migration
+    name: Migration and undo
+    group: contract
+    holds: How old data moves to the new shape, and how the data change is undone.
+    decide: none
+    flow: none
+    contract: needed
+    initiative: none
+  - id: security
+    name: Security
+    group: contract
+    holds: Who may call it, what it may reach, and what it never leaks.
+    decide: optional
+    flow: optional
+    contract: needed
+    initiative: none
+  - id: rollout
+    name: Rollout
+    group: contract
+    holds: The order of release, and how we watch it.
+    decide: optional
+    flow: optional
+    contract: needed
+    initiative: none
+
+  - id: why
+    name: Why one initiative
+    group: initiative
+    holds: Why these designs belong together.
+    decide: none
+    flow: none
+    contract: none
+    initiative: needed
+  - id: shared-decisions
+    name: Shared decisions
+    group: initiative
+    holds: The decisions every design in the family follows, and why.
+    decide: none
+    flow: none
+    contract: none
+    initiative: needed
+  - id: order
+    name: Order and dependencies
+    group: initiative
+    holds: Which design comes first, and what each one waits on.
+    decide: none
+    flow: none
+    contract: none
+    initiative: needed
+
+  - id: risks
+    name: Risks
+    group: prove
+    holds: What breaks, and what we do. "Accepted" with a reason is valid.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+  - id: proof
+    name: Test and proof plan
+    group: prove
+    holds: How each piece proves itself.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: none
+  - id: repos
+    name: Each kind of repo
+    group: prove
+    holds: What the design means for a service, a library, a schema, a CLI and a plugin.
+    decide: shared
+    flow: shared
+    contract: shared
+    initiative: none
+  - id: change
+    name: Change and undo
+    group: prove
+    holds: The kind of change, its impact, how to undo it, and each existing test it changes.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: optional
+  - id: done
+    name: Done line
+    group: prove
+    holds: Lines someone else can check. The approval lives in the tracker.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+  - id: key
+    name: Key
+    group: prove
+    holds: Every word and code the design uses.
+    decide: needed
+    flow: needed
+    contract: needed
+    initiative: needed
+
+# Read from the tracker at build time. The page shows them read only.
+tracker:
+  - id: questions
+    name: Questions
+    holds: Each question to the owner, open or answered, with the answer.
+  - id: decisions
+    name: Decisions
+    holds: Each decision, in the owner's words, with its date.
+  - id: approval
+    name: Approval and lock
+    holds: The owner's approval and the lock, with the words and the date.
+  - id: since
+    name: Since approval
+    holds: Each change after approval, the part it touched, and the owner's words.
+  - id: family
+    name: Family
+    holds: The designs linked to this one, with their state.
+  - id: rollup
+    name: Roll-up
+    holds: How far the family has come. Initiative designs only.

package/skills/sdlc-task/lifecycle.yaml

@@ -25,7 +25,7 @@ tripwires: [definition_of_done, security, schema_migrations, money_cost]
 tiers: [hotfix, standard, initiative]
 tier_escalators: [migrations, auth_rls_surface, new_external_dependency, money_cost]
 
-# Both templates travel with the package, beside the kernel.
+# The design format and the resume anchor travel with the package, beside the kernel.
 templates:
-  design_doc: templates/design-doc.md
+  design_doc: design/README.md
   resume_anchor: templates/resume-anchor.md