acstack 0.0.0-stage → 0.47.0

package/skills/terminal-workspace/turn-off-and-update.md

@@ -0,0 +1,104 @@
+# Turn off and update
+
+`SKILL.md` decides when to read this file: when the user asks to turn a component off or uninstall, or `outdated` reports something.
+
+## 8. Turning one component off, or all of them
+
+*`disable` undoes one component. `uninstall` undoes the managed config. harlequin is the one binary either of them removes.*
+
+```bash
+bash "$SETUP" disable herdr     # or delta, diffnav, gh_dash, harlequin, lazygit, neovim, pi, tuicr
+```
+
+`disable` takes those nine components and no others. For `diffnav`, `gh_dash`,
+`harlequin`, `lazygit` and `tuicr` it writes `<component>.enabled: false` into
+the config itself, then rebuilds the herdr keymap so the rest of it survives.
+
+For `herdr`, `delta`, `neovim` and `pi` it does not. Set `<component>.enabled: false`
+yourself after those four, or the next `apply` restores them.
+
+`neovim` is the one whose undo is a deletion. The component writes a whole file
+of ACStack's own, so `disable` removes `~/.config/nvim/lua/plugins/acstack.lua`
+and leaves the rest of the user's neovim config alone. Neither `disable` nor
+`uninstall` touches a `acstack.lua` the user wrote by hand.
+
+`pi` undoes only what `apply` added, because pi's config is the user's:
+
+- It removes the pi packages `apply` installed, and keeps any the user installed first
+- It releases the four settings and `toolActivation`, unless the user has changed one since
+    - A value `apply` replaced goes back to what the user had, and a key `apply` added goes
+- It puts back an ACStack pin `apply` moved forward, unless the user has moved it since
+- It removes the delegation block from pi's context file, and the user's text stays byte for byte
+- It removes agentic-retro's extension only when `apply` was the one to write it
+- It keeps the pi binary, its logins and its sessions
+- It touches nothing in a `settings.json` that does not parse, and says so
+- It records what it added in `~/.config/acstack/terminal-workspace.pi.json`
+
+`yazi`, `markdown` and `remote` have no `disable` path. `disable` refuses for
+those three and names the edit that turns one off. Set the component's
+`enabled` key to `false` in the config, then run `apply` again.
+
+```bash
+bash "$SETUP" uninstall
+```
+
+`uninstall` removes everything `apply` wrote. It strips the managed blocks from
+the herdr, tuicr and yazi configs. It unsets delta as the git pager.
+
+It deletes the helper scripts, the `xclip` stand-in, the neovim plugin file, and
+the keybindings it wrote into gh-dash. It runs `disable pi`. The user's own
+settings around them survive, and every binary stays except harlequin, which uv
+owns whole rather than as one file in `$BIN`.
+
+pi stays too. It holds the user's logins and sessions, and the user may run it
+without ACStack. `uninstall` prints the npm command that removes it.
+
+## 9. Keeping it current
+
+*`outdated` reports what has moved on. `upgrade` fetches it.*
+
+```bash
+bash "$SETUP" outdated
+```
+
+It prints one finding per line, tab-separated as kind, name and detail, and
+answers in its exit code:
+
+| Exit | Meaning | What to do |
+|---|---|---|
+| 0 | Nothing to do | Say nothing |
+| 1 | Something is missing, new or stale | Show the findings and offer `upgrade` |
+| 2 | It cannot tell | Name the reason once and move on |
+
+Four kinds of finding:
+
+- `missing` – this machine has never applied the workspace, so run section 4 of `SKILL.md` rather than `upgrade`
+- `new` – a component this plugin version ships that the user's last `apply` never saw
+- `stale` – an installed tool behind its published release
+- `unknown` – the script cannot compare, so there is nothing to act on
+
+```bash
+bash "$SETUP" upgrade              # everything reported stale
+bash "$SETUP" upgrade yazi delta   # only these
+```
+
+pi adds four rows of its own:
+
+- `pi`, `pi-subagents` and `pi-compact-tools` compare against npm, and `upgrade` runs `pi update` for each
+    - A package the user pinned, such as `npm:pi-subagents@1.0.0`, reports `unknown`, because `pi update` never moves it
+- `pi-acstack` compares ACStack's pin in pi against this plugin's version, with no network at all
+    - `upgrade pi-acstack` moves the pin forward, and so does `apply`
+    - Neither moves a pin newer than this plugin, because the user chose it
+    - Neither installs ACStack where it is absent or unpinned
+
+`upgrade` reinstalls each stale binary and appends any new component's config
+block to the user's file, comments intact. The three tools that update
+themselves go through `herdr update`, `gh extension upgrade dlvhdr/gh-dash`,
+and `uv tool upgrade harlequin`. Run `apply` afterwards to install what the new
+block turned on.
+
+Naming a tool skips the version comparison, which is the only way to refresh
+`mermaid-ascii`. It has no version flag, so nothing can read the installed version.
+
+`outdated` reads herdr's stable release manifest, so a user on the preview
+channel sees a `stale` row for herdr that is not one.

package/skills/test-conventions/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: test-conventions
+description: Test placement rules and framework conventions. Invoke before writing ANY test. Provides file location decision tree, naming conventions, and layer guidance (unit, integration, E2E). Triggers on writing new tests, creating test files, or test-writer agent starting work.
+---
+
+# Test Conventions
+
+## Decision Tree: Where Does My Test Go?
+
+Read `acstack/project.yaml` for `directories.source`, `directories.tests`, and `frontend` config.
+
+```
+Backend code?             → <tests-dir>/<mirror-source-path>/test_<module>.py
+Frontend component/hook?  → <frontend-dir>/src/<path>/__tests__/<Name>.test.tsx
+Browser-based user flow?  → <frontend-dir>/tests/<feature>.spec.ts
+Visual regression?        → <frontend-dir>/tests/visual-regression.spec.ts
+```
+
+## Layer 1: Backend Unit Tests
+
+Mirror the source directory structure. Example: `src/auth/sessions.py` → `tests/auth/test_sessions.py`.
+
+- Create `__init__.py` in new subdirectories (Python)
+- Cross-cutting integration tests → `<tests-dir>/integration/`
+- Shared fixtures → `<tests-dir>/conftest.py` (Python) or shared setup files
+- Use markers for slow/integration tests (configured in `test_markers.exclude`)
+- Run with the `commands.test` command from project.yaml
+- Baseline: `.test-baseline` – count must never drop
+
+## Layer 2: Frontend Unit Tests
+
+Colocated with source. Example: `src/hooks/useAuth.ts` → `src/hooks/__tests__/useAuth.test.ts`.
+
+- Components: `.test.tsx`, pure functions: `.test.ts`
+- Run with `frontend.commands.test` from project.yaml
+
+## Layer 3: E2E Tests (Browser)
+
+One file per feature or user flow. Example: `tests/login-flow.spec.ts`.
+
+- Auth setup: save auth state to a storage file, reuse across tests
+- Credentials: use environment variables (gitignored `.env.test`)
+- Agent/async tests: use generous timeouts, take screenshots at key steps
+- Run with `agent-browser` CLI or the project's configured E2E test command
+
+## Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Python test file | `test_<module>.py` | `test_sessions.py` |
+| Python test function | `test_<behavior>` | `test_expired_token_returns_401` |
+| JS/TS test file | `<Name>.test.ts(x)` | `useAuth.test.ts` |
+| E2E spec | `<feature>.spec.ts` | `login-flow.spec.ts` |
+
+## Gitignored Artifacts (never commit)
+
+- Browser test artifacts, test results, reports
+- Coverage output
+- Test environment files (`.env.test`)

package/skills/visual-docs/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: visual-docs
+description: "Write or restructure documentation that leads with a diagram and derives its structure from it. Use whenever the user asks for docs, a README, an architecture or workflow write-up, an explainer, or says existing docs are hard to follow, confusing, or a wall of text – and whenever you are about to write more than two paragraphs explaining how something works. Applies the Minto pyramid: answer first, then support."
+---
+
+# visual-docs
+
+*A reader should see the system's shape from one diagram. They then find every detail in a section that maps to a part of it.*
+
+This skill makes a doc lead with a diagram, then derive its sections from that diagram.
+
+- **Most technical docs explain in reading order rather than importance order**
+    - The reader builds the picture themselves and learns what mattered last
+- **One diagram carries the whole shape**
+- **Every section maps to a part of that diagram**
+- **The prose rules live in the `writing` skill**
+- This skill owns shape alone
+
+This skill owns document shape. Prose follows the `writing` skill.
+
+```mermaid
+flowchart TD
+    A["Establish the shape<br/>(read code, not existing docs)"] --> B["Draw the lead diagram<br/>(section 4)"]
+    B --> C["Derive sections from nodes<br/>(section 1)"]
+    C --> D["Write the opening<br/>(section 2.1)"]
+    D --> E["Fill sections in bullets<br/>(sections 2.2 and 3)"]
+    E --> F{"Siblings MECE?<br/>(section 2.3)"}
+    F -->|no| C
+    F -->|yes| G["Check every node has a section<br/>(section 6)"]
+    G --> H["Verify the diagram renders"]
+```
+
+| Step in the diagram      | Detail          |
+| ------------------------ | --------------- |
+| Derive sections          | section 1       |
+| Opening, vertical, MECE  | section 2       |
+| Bullets carry the body   | section 3       |
+| Draw and label           | section 4       |
+| Headings and duplication | section 5       |
+| Full order of operations | section 6       |
+| What to avoid            | section 7       |
+
+## 1. The rule that makes this work
+
+*The diagram is the table of contents. If a section has no home in the diagram, one of the two is wrong.*
+
+Every numbered section maps to an element of the lead diagram, and a section heading reuses the diagram's node label verbatim. This is mechanical, not stylistic:
+
+- A box showing something **happening**, with no section, means the doc is incomplete
+- A section covering no part of the diagram either belongs in another doc, or the
+  diagram is missing something
+
+- Renaming a box renames its section, and the reverse
+
+Three exemptions, and only these three.
+
+- **Start and end boxes** – a box for what comes in, or what remains after, is not a step and needs no section
+    - In a workflow diagram, the incoming request and the final stored output are both this
+- **Two boxes, one command** – two boxes are sometimes worth drawing separately because they are two ideas, though one command does both
+    - Give them one section and name both in the heading
+        - The reader can tell it covers both
+- **Sections about the document** – a section on what this doc leaves out, or what is about to change, is housekeeping for the reader
+    - It describes the document rather than the system
+        - No box should exist for it
+
+**Start and end boxes.** A box for what comes in, or what remains after, is not
+a step and needs no section. In a workflow diagram, the
+incoming request and the final stored output are both this.
+
+**Two boxes, one command.** Sometimes two boxes are worth drawing separately
+because they are two ideas, but one command does both. Give them one section and
+name both in the heading, so the reader can tell it covers both.
+
+**Sections about the document.** A section on what this doc leaves out, or what is
+about to change, is housekeeping for the reader. It describes the document, not the
+system, so no box should exist for it.
+
+- Anything else without a match is a defect in one of the two
+- Do not add a section to justify a node, or a node to justify a section
+- End the lead diagram with a mapping table when the doc has more than four sections
+    - The table lets the reader jump from a box to its detail
+
+End the lead diagram with a mapping table when the doc has more than four sections. It lets the reader jump from a box to its detail.
+
+## 2. Minto pyramid
+
+*Answer first. Every level summarises the level below it. Siblings are the same kind of thing, and they are complete.*
+
+### 2.1. Open with one sentence, then bullets
+
+*Say what the thing is and who it is for in one sentence. Put everything else in bullets under it.*
+
+The opening is never a paragraph. A reader meeting the doc for the first time scans it. A four-sentence block of setup is the part they skip.
+
+- **Sentence one names the thing and what it does**, in words a developer who has never seen this repo already knows
+- **Bullets under it carry the rest**: what problem it solves, what it costs, what it does not do
+- **A bullet that needs context gets a sub-bullet**, never a second sentence
+
+| Beat | Where it goes |
+| ---- | ------------- |
+| **What this is** | the opening sentence |
+| **What it solves** | the first bullet |
+| **What it costs, or does not do** | a later bullet |
+| **Where to go next** | the contents table, or the last bullet |
+
+Two rules keep the opening honest.
+
+- The answer goes first, never at the end
+- A reader who stops after the opening sentence and the first bullet must still leave with the conclusion
+
+### 2.2. The vertical rule
+
+*A heading's takeaway must summarise everything under it, and nothing else.*
+
+- Put one italic line under every H2 and H3, stating the section's point
+- Test it by deleting the section body
+- It was a label rather than a summary, if the takeaway no longer tells the reader what they need
+
+### 2.3. The horizontal rule
+
+*Siblings must be the same kind of thing, mutually exclusive, and collectively cover the parent. This binds every bullet, not only every section.*
+
+Apples-to-apples applies at every level. Under one heading, at one indent, every bullet answers the same question. A bullet about what the tool does cannot sit beside a bullet about where to install it.
+
+- Write: three bullets, each naming one failure mode the tool solves
+- Not: two bullets naming a failure mode, a third naming the install command
+
+Three failures to check for:
+
+- **Mixed kinds** – three sections about components and a fourth about history. The fourth belongs elsewhere
+- **Overlap** – two sections that both explain the same mechanism from different angles. Merge them
+- **Gaps** – the parent's takeaway claims something the children do not cover
+
+Then order the siblings deliberately, and say which order you used if it is not obvious:
+
+| Order         | Use when                                       |
+| ------------- | ---------------------------------------------- |
+| **Time**      | the thing is a sequence – a pipeline, a request |
+| **Structure** | the thing has parts – components, modules       |
+| **Degree**    | the parts differ by importance or size          |
+
+## 3. Bullets carry the body
+
+*A reader scans a list and skips a paragraph. Put the body in bullets, and keep prose for the opening.*
+
+Ten rules govern a bullet. Each one is a way to write.
+
+- **Bullets carry 90% or more of the body** – prose survives in the opening sentence and in a section takeaway, and nowhere else
+- **One sentence per bullet** – split "X and also Y" into two siblings, or nest one under the other
+- **No bullet ends in a period**, however long it runs – a question mark or an exclamation mark is fine
+- **A sub-bullet carries what its parent cannot hold** – it argues for the parent, adds the detail the point needs, or lists the questions under it
+- **Every level reads top-down** – a reader who stops at any level still leaves with the point
+- **Nest as far as the argument needs, then stop** – depth costs nothing while every level adds a point
+- **Cut a level that restates its parent** – that one costs the reader everything
+- **Indent a markdown file by four spaces per level** – a `- ` marker opens its content at column 2
+    - Eight spaces sit four past that column
+        - CommonMark renders the child as a code block
+- **Use parallel grammar across siblings** – the same kind of thing then reads as the same kind of thing
+- **Cut any bullet that narrates, softens or restates**
+
+Three shapes stay prose, because a bullet breaks them.
+
+| Shape | Why it stays prose |
+| ----- | ------------------ |
+| the opening sentence | one sentence naming the thing, by section 2.1 |
+| a section takeaway | one italic line under the heading, by section 2.2 |
+| a numbered procedure | a step is a step, and rule 1 of the `writing` skill caps it at 20 words |
+
+Pick a table over a bullet list wherever every item answers the same two or three questions. Pick a bullet list wherever the items differ in shape.
+
+The output style `ac-writing-style` applies these same ten rules to a chat reply. This section is where the rules live, and that file is one reader of them.
+
+Indent every nested bullet four spaces per level, in a terminal reply and in a file alike. Claude Code and GitHub both read a wider indent as run-on text under the parent, not as a list.
+
+## 4. Diagrams
+
+*One diagram carries the doc. Others are local aids and are optional.*
+
+### 4.1. Pick the type from the question the diagram answers
+
+| Question                        | Diagram              |
+| ------------------------------- | -------------------- |
+| What talks to what?             | `flowchart`           |
+| In what order, and who waits?   | `sequenceDiagram`     |
+| What states can this be in?     | `stateDiagram-v2`     |
+| What decides which path?        | `flowchart` with gates |
+| What is stored, and how related? | `erDiagram`           |
+
+- A workflow with decision points is a flowchart, and not a sequence diagram
+- A handoff between agents or services over time is a sequence diagram, and not a flowchart
+- Choosing wrong is the most common reason a diagram fails to explain anything
+
+### 4.2. Label for a reader who does not know the codebase
+
+*Human-readable name first, technical name underneath.*
+
+```mermaid
+flowchart LR
+    A["Write failing tests<br/>(test-writer)"] --> B["Make them pass<br/>(task-executor)"]
+    B --> C["Verify<br/>(task-checker)"]
+```
+
+- The `<br/>` line carries the file, agent or command name
+- Someone who knows the system reads the second line, and someone who does not reads the first
+- A diagram labelled only with identifiers explains nothing to the second reader, who is the one that needed the diagram
+
+### 4.3. Keep it graspable
+
+*Aim for a diagram a non-expert reads correctly on first look, without narration.*
+
+- Roughly nine nodes is the ceiling for one diagram. Past that, split it and give each part its own section
+- Label every edge that is not obvious. An unlabelled arrow asserts a relationship without naming it
+- Show the failure path when there is one. A flow with only the happy path misrepresents the system
+- Do not encode meaning in colour alone
+
+## 5. Conventions
+
+*Numbered headings, and never repeat a parent doc.*
+
+- **Number every heading** – `## 1.`, `### 1.1.` – the period belongs to the number. The number lives in the heading text so a reader can find a cross-reference by eye. Drop the third level in docs under roughly 200 lines
+- **Do not duplicate up the tree** – a child doc adds detail and links to its parent. If a section would restate what the parent says, cut it and link
+
+## 6. Process
+
+*Diagram before prose. Deriving structure from a finished diagram is fast; retrofitting a diagram onto finished prose does not work.*
+
+1. **Establish the shape.** Read the code, config, and entry points. Do not start from existing docs – they are what you are replacing, and their errors propagate
+2. **Draw the lead diagram first.** Getting it right forces the structure. If you cannot draw it, you do not yet understand the thing well enough to document it
+3. **Derive the section list from the diagram nodes.** One section per node, headings reusing node labels
+4. **Write the opening sentence.** Do this before the body, so the body has a claim to support
+5. **Fill each section.** Takeaway line first, then detail
+6. **Check MECE across siblings**, then verify every node has a section and every section has a node
+7. **Verify the diagram renders.** Mermaid fails silently in some viewers. Check that the fenced block parses, with no unescaped quote or bracket in any label
+
+## 7. Anti-patterns
+
+*Each of these looks like a normal doc and fails a reader in a specific way.*
+
+| Pattern                              | Why it fails                                             |
+| ------------------------------------ | -------------------------------------------------------- |
+| Conclusion at the end                | the reader carries unresolved detail until the last line  |
+| A diagram after the prose            | the reader has already built a mental model, possibly wrong |
+| One diagram per section, none overall | no single artefact carries the shape                     |
+| Diagram nodes labelled `AuthSvc`     | only legible to someone who already knows the system      |
+| Sections mirroring the directory tree | directory layout is rarely the reader's question order    |
+| Restating the parent doc             | two sources to keep in step, and they will drift          |

package/skills/writing/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: writing
+description: One plain-language standard for every durable artifact. A durable artifact is prose that outlives the session and is read later by someone who was not in the conversation. It covers architecture decision records (ADRs), glossary entries, living specs and functional requirements, map nodes, handoff files, READMEs and other docs, and pull request bodies. Invoke before writing or editing any of them.
+---
+
+# Writing
+
+## Who you are
+
+*You are the best developer in the world. That is exactly why your writing has to be simple.*
+
+- **You are smarter, more graceful, and more efficient than any other developer**
+    - Other developers envy how easily you carve through a complex problem
+    - You see the shape of a system while they are still reading the first file
+- **Not everyone is as smart as you**
+    - That is your problem to solve, never theirs
+    - Always explain a thing so a reader without your domain expertise gets it on the first pass
+    - A sentence the reader has to work to understand is a sentence you need to write better
+- **Everything you say and write flows logically and reads easily**
+    - Each point follows from the one before it
+    - Nothing needs a second pass to interpret
+- **By default, write for a reader with 150 other things to do today**
+    - They read the artifact once, in seconds, and they never come back to it
+    - Give them what they need in order to make a decision or take action, and nothing else
+    - Default to the highest level possible that still enables them to decide or act
+    - Go deep only where the depth would change what they decide or do
+- **Brevity is never a reason to hide something they need to decide or act**
+    - Weigh every detail against all the others, then keep only those that truly matter
+    - Keep anything the reader would be angry to learn about later
+    - Nobody reading a durable artifact can ask you a follow-up question
+
+> ## **IF YOU CAN'T EXPLAIN IT SIMPLY, YOU DON'T UNDERSTAND IT WELL ENOUGH.**
+>
+> **Commonly attributed to Albert Einstein.**
+
+**THIS IS THE WHOLE JOB. READ IT AGAIN.**
+
+**EVERY TIME YOU REACH FOR A LONGER WORD, A CLEVERER PHRASE, OR A SENTENCE THAT NEEDS A SECOND PASS, YOU ARE TELLING THE READER YOU DO NOT UNDERSTAND THE THING YET.**
+
+**THE EXPERT IS THE ONE WHO MAKES IT SIMPLE. NOT THE ONE WHO MAKES IT SOUND HARD.**
+
+**BEFORE YOU WRITE A SENTENCE, ASK: COULD A DEVELOPER TWO YEARS INTO THEIR CAREER READ THIS ONCE AND GET IT? IF NOT, YOU DO NOT UNDERSTAND IT WELL ENOUGH YET. GO BACK.**
+
+ACStack adopts the writing rules of ASD-STE100 (Simplified Technical English), not its licensed dictionary. ASD-STE100 is an aerospace standard for controlled technical writing. The file `vocabulary.md` beside this skill replaces the dictionary, and the lint reads that same file.
+
+Every rule below is a way to write. Each rule has a `Write:` and `Not:` pair in `examples.md` beside this skill, except rules 3 and 11, which keep theirs inline. Read `examples.md` before you write your first durable artifact in a session.
+
+## Sentences
+
+An instruction is a numbered step, a procedure line, or a handoff next action.
+
+### 1. Cap a descriptive sentence at 25 words, and an instruction at 20 words (ASD-STE100)
+
+`acstack lint-prose` checks both caps. The 20-word cap applies to an ordered list item, written `1.` or `1)`. An unordered bullet keeps the 25-word cap.
+
+### 2. Give each sentence one instruction (ASD-STE100)
+
+### 3. Give each sentence one idea, and never write a compound sentence without a reason
+
+A compound sentence is two clauses joined by a comma, by `and`, `so`, `but`, `which` or `where`. Use one only when the second clause changes what the first one means. Everywhere else, split it or cut it.
+
+- Write: A map holds question nodes and work nodes. The frontier is the set ready to work now.
+- Not: A map holds question and work nodes, and the frontier is the set ready to work now, which the tracker derives from the blocked-by links.
+
+**Cut a trailing clause that only justifies, softens or restates the first half.** This is the most common failure in this repository. It reads as padding, and the sentence is stronger without it.
+
+- Write: Claude starts building before the requirements are clear.
+- Not: Claude starts building before the requirements are clear, so you get the wrong thing quickly.
+
+- Write: Claude writes the code, then writes tests that pass against that code.
+- Not: Claude writes the implementation and then writes tests that pass against it, which proves nothing.
+
+**When the trailing clause is the point, lead with it instead of cutting it.** Cutting loses the point. Inverting the sentence puts the answer where the reader looks first.
+
+- Write: Don't cache the token – it expires in five minutes.
+- Not: The token expires in five minutes, so don't cache it.
+
+- Write: Roll back the deploy – it broke the checkout page.
+- Not: The deploy broke the checkout page, so roll it back.
+
+Spot it by the joining word. `so`, `therefore` and `which means` all announce that the point comes second.
+
+**Never bolt a cross-reference onto a sentence with a comma.** Put it in parentheses.
+
+- Write: You get three commands (see section 1).
+- Not: You get three commands, and section 1 says which one to use.
+- Not: Install it with two commands, covered in section 2.
+
+**Keep a second clause only when it carries a fact the first clause needs.**
+
+- Write: The hook raises a `nudge_warn` below 1 to 1, because a rung of 0 would block every turn.
+
+### 4. Break a paragraph at three sentences
+
+### 5. Open a paragraph with its point
+
+## Words
+
+### 6. Use one term for one meaning across a document (ASD-STE100)
+
+### 7. Define a term of art in plain words, before you first use it
+
+Explain every invented term before the sentence that relies on it, never after. A reader who meets `map`, `node` or `frontier` cold has already stopped reading by the time the definition arrives.
+
+The same rule orders sections. A section that uses a term has to sit after the section that defines it.
+
+### 8. Spell out an abbreviation at first use
+
+### 9. Cap a noun string at three words (ASD-STE100)
+
+### 10. Keep the articles (ASD-STE100)
+
+### 11. Use the common word, and never a metaphor where a plain word exists
+
+Five ways this fails. Each carries its own pair.
+
+**A fancier word than the job needs.** The longer word buys nothing, and it costs the reader a beat.
+
+- Write: Use the bundled CLI. Many nodes stay in fog.
+- Not: Utilize the bundled CLI. Numerous nodes remain in fog.
+
+- Write: You provide feedback on Claude's recommended answer instead of prompting from scratch.
+- Not: You confirm instead of composing.
+
+**Word order nobody uses out loud.** Say the sentence to yourself. Write the order you said.
+
+- Write: Some requests only need one question.
+- Not: Some requests need only one question.
+
+**A metaphor the reader has to decode.** A heading is the worst place to make them do that.
+
+- Write: `## Three commands, and which one to use`
+- Not: `## No path selection: the fog picks the size`
+
+**Phrasing that needs a second pass.** Pick what a reader understands the first time, every time.
+
+- Write: anything you cannot yet articulate clearly
+- Not: something nobody can state precisely yet
+
+**A sentence written for drama.** State the fact and stop. A sentence built for effect reads as marketing, not as documentation.
+
+- Write: ACStack throws the nodes away.
+- Not: The nodes themselves are scaffolding.
+
+- Write: Some requests only need one question.
+- Not: A single question ends there.
+
+Most of these words have no entry in `vocabulary.md`, and they should not. `composing` is right in a sentence about music. The judgment is yours, and these pairs are what it looks like.
+
+### 12. Use the short form
+
+## Voice
+
+### 13. Name the actor and put it in front of the verb (ASD-STE100)
+
+### 14. Write descriptions in the present tense and procedures in the imperative (ASD-STE100)
+
+### 15. Make a claim once, at the strength the evidence supports
+
+### 16. Name the source of a claim
+
+### 17. Describe a thing by what it does
+
+## Structure
+
+### 18. Name the file, the number, and the actor
+
+### 19. Recommend one option and give the reason
+
+### 20. State what a thing is, then stop
+
+Never say what it is not. The one exception is showing the wrong version so the
+reader can spot it, as every `Not:` line in `examples.md` does.
+
+### 21. List as many items as there are
+
+"Etc." is fine when you are trying to convey that your list is non-exhaustive.
+
+### 22. Name the thing a pronoun stands for
+
+A reader arriving at a heading or a takeaway line holds no context from the line above it. Never open one with `one`, `it`, `this` or `that` where the noun is missing.
+
+### 23. Write for a developer who has never seen this repository
+
+Picture someone a few years into their career, reading this for the first time. Every sentence has to land on that reader without a second pass.
+
+A term this project invented gets its plain meaning on the same line, every time it opens a section.
+
+### 24. State what you checked, and when
+
+## Headings and marks
+
+### 25. Connect clauses with a period or a comma, and set an aside off with an en dash
+
+**Always use the Oxford comma.** A list of three or more items takes a comma before the final `and` or `or`.
+
+### 26. Write a heading in sentence case, and end a fragment with no period
+
+A bullet never ends in a period, however long it runs. A cell follows the same rule. Section 3 of
+the `visual-docs` skill owns bullet shape.
+
+A `Write:` or `Not:` line in this skill is the one exception, because it quotes a sentence and
+keeps that sentence's own punctuation.
+
+### 27. Give a heading content that its paragraph does not repeat
+
+### 28. Bold a single term for emphasis
+
+### 29. Carry the meaning in words
+
+### 30. End with the last fact
+
+## What this skill leaves to others
+
+This skill owns words, sentences, paragraphs, and heading style. Document shape belongs to the `visual-docs` skill. That skill owns the Minto pyramid, the opening sentence, MECE (mutually exclusive, collectively exhaustive) sections, diagram-first structure, and bullet discipline.
+
+Chat replies and commit subject lines sit outside the standard.
+
+Straight quotes are the only quotes. The two tables in `vocabulary.md` hold every replaced word and every replaced mark.
+
+## Before you finish
+
+Check five things in what you just wrote.
+
+1. Sentence lengths. No descriptive sentence runs past 25 words, no instruction past 20.
+2. Compound sentences. Search your own text for `, and `, `, so `, `, which `, and `, because `. Justify every hit against rule 3, or split it.
+3. Vocabulary. No row from `vocabulary.md` survives in the text.
+4. Voice. Every sentence names its actor, descriptions sit in the present tense, procedures sit in the imperative.
+5. Headings. Sentence case, no trailing period, and each one adds what its paragraph does not.
+
+Then run `~/.claude/acstack/bin/acstack lint-prose <paths>` when it is available. It warns and never blocks.