acstack 0.0.0-stage → 0.47.1

package/skills/writing/examples.md

@@ -0,0 +1,153 @@
+# Writing examples
+
+The `Write:` and `Not:` pair for each rule in `SKILL.md`, except rules 3 and 11, which keep theirs inline.
+
+### 1. Cap a descriptive sentence at 25 words, and an instruction at 20 words (ASD-STE100)
+
+- Write: The SessionStart hook creates the symlink at `~/.claude/acstack/bin/acstack`.
+- Not: The SessionStart hook, which runs whenever a session begins and which the plugin installs for you, is responsible for creating the symlink that points at the CLI inside the current plugin cache.
+
+### 2. Give each sentence one instruction (ASD-STE100)
+
+- Write: Run the tests. Stage the spec files.
+- Not: Run the tests and stage the spec files, then check the baseline count.
+
+### 4. Break a paragraph at three sentences
+
+- Write: Three sentences, then a new paragraph, even mid-argument.
+- Not: A sixth sentence of setup inside the same block.
+
+### 5. Open a paragraph with its point
+
+- Write: Spec sync runs at commit time. It maps changed files to domains, then rewrites each spec.
+- Not: Specs can drift. One option is to update them by hand. Spec sync runs at commit time.
+
+### 6. Use one term for one meaning across a document (ASD-STE100)
+
+- Write: The map holds nodes. Each node has a status.
+- Not: The map holds nodes. Each item has a status.
+
+### 7. Define a term of art in plain words, before you first use it
+
+- Write: Work the frontier, the nodes ready to work now.
+- Not: Work the frontier, the unblocked open nodes the tracker returns.
+
+- Write: define `map` and `node`, then say what `/acstack:map` does
+- Not: say what `/acstack:map` does, then define `map` in the next subsection
+
+### 8. Spell out an abbreviation at first use
+
+- Write: an architecture decision record (ADR)
+- Not: an ADR
+
+### 9. Cap a noun string at three words (ASD-STE100)
+
+- Write: the knowledge base for browser verification
+- Not: the browser verification knowledge base file
+
+### 10. Keep the articles (ASD-STE100)
+
+- Write: Update the spec in the domain directory.
+- Not: Update spec in domain directory.
+
+### 12. Use the short form
+
+- Write: To stage the specs, run the commit skill. It warns because the cap is a heuristic.
+- Not: In order to stage the specs, run the commit skill. It warns due to the fact that the cap is a heuristic.
+
+### 13. Name the actor and put it in front of the verb (ASD-STE100)
+
+- Write: The task-checker runs the full suite.
+- Not: The full suite is run.
+
+### 14. Write descriptions in the present tense and procedures in the imperative (ASD-STE100)
+
+- Write: The hook writes the symlink. Run the hook after you install the plugin.
+- Not: The hook will have written the symlink. You should then probably run it.
+
+### 15. Make a claim once, at the strength the evidence supports
+
+- Write: The cap misfires inside tables.
+- Not: It may possibly be the case that the cap could sometimes misfire inside tables.
+
+### 16. Name the source of a claim
+
+- Write: ASD-STE100 caps a descriptive sentence at 25 words.
+- Not: Experts believe that shorter sentences read better.
+
+### 17. Describe a thing by what it does
+
+- Write: The tunnel forwards port 19988 to Chrome on the laptop.
+- Not: The tunnel offers a seamless, robust bridge to your browser.
+
+### 18. Name the file, the number, and the actor
+
+- Write: Three of the eleven skills restate these rules, `commit` among them.
+- Not: Several files restate these rules.
+
+### 19. Recommend one option and give the reason
+
+- Write: Use the files backend. It needs no network.
+- Not: There is a files backend and an issues backend. Both carry trade-offs.
+
+### 20. State what a thing is, then stop
+
+- Write: The skill holds the rules. The CLI checks them.
+- Not: The skill is not just a style guide but a contract.
+- Not: The hook writes the symlink rather than copying it.
+
+### 21. List as many items as there are
+
+- Write: The lint warns and never blocks.
+- Not: The lint is fast, focused, and forgiving.
+
+### 22. Name the thing a pronoun stands for
+
+- Write: Only `/acstack:map` creates a map.
+- Not: Only `/acstack:map` creates one.
+
+### 23. Write for a developer who has never seen this repository
+
+- Write: Node 14 asks which tracker backend ships first.
+- Not: The node from this morning's grill.
+
+- Write: the frontier, meaning the nodes you can work right now
+- Not: work the frontier
+
+### 24. State what you checked, and when
+
+- Write: `acstack lint-prose` does not exist yet, as of 2026-08-22.
+- Not: My knowledge has a cutoff, so this may have changed since.
+
+### 25. Connect clauses with a period or a comma, and set an aside off with an en dash
+
+- Write: The lint warns. It never blocks. The rule – a heuristic – misfires inside tables.
+- Not: The same two sentences joined by an em dash, or by a colon in mid sentence.
+
+- Write: proposals, designs, and tasks
+- Not: proposals, designs and tasks
+
+### 26. Write a heading in sentence case, and end a fragment with no period
+
+- Write: `## Before you finish`, and a table cell that reads `make sure`
+- Not: `## Before You Finish.`, and a table cell that reads `make sure.`
+
+### 27. Give a heading content that its paragraph does not repeat
+
+- Write: `## Sentences`
+- Not: `## This section covers the rules that apply to sentences`
+
+### 28. Bold a single term for emphasis
+
+- Write: **fog** names whatever nobody can state precisely yet.
+- Not: **ACStack** ships a **CLI** that **many** skills call.
+
+### 29. Carry the meaning in words
+
+- Write: Done. 12 tests pass.
+- Not: The same line with a tick emoji in front and a rocket after.
+
+### 30. End with the last fact
+
+- Write: The build passes. The baseline holds at 214 tests.
+- Not: Let me know if you would like me to help with anything else.

package/skills/writing/vocabulary.md

@@ -0,0 +1,96 @@
+<!--
+`acstack lint-prose` reads this layout. One Markdown table per section, columns
+`| Avoid | Write instead | Note |`, one entry per row. `Avoid` holds one
+lowercase word or phrase, never a regular expression. `Write instead` holds a
+replacement, or `-` when the fix is to delete the word. Words sit under
+`## Words`. The marks sit under `## Marks`, in a second table of the same shape.
+Emoji are not listed, because the lint detects them by the Unicode Extended_Pictographic property.
+-->
+
+# Vocabulary
+
+## Words
+
+| Avoid | Write instead | Note |
+| --- | --- | --- |
+| additionally | also | |
+| crucial | important | |
+| delve | look at | |
+| enduring | lasting | |
+| enhance | improve | |
+| garner | get | |
+| interplay | - | name the two things and how they meet |
+| intricate | complex | |
+| landscape | - | name the thing, puffery as in evolving landscape |
+| pivotal | important | also puffery, as in pivotal moment |
+| showcase | show | |
+| tapestry | - | name the thing |
+| testament | - | state the fact instead, puffery as in testament to |
+| underscore | show | |
+| setting the stage | - | puffery |
+| indelible mark | - | puffery |
+| deeply rooted | - | puffery |
+| nestled | - | promotional |
+| vibrant | - | promotional |
+| breathtaking | - | promotional |
+| groundbreaking | new | promotional |
+| renowned | - | promotional |
+| stunning | - | promotional |
+| must-visit | - | promotional |
+| seamless | - | promotional, say what it does |
+| robust | - | promotional, say what it handles |
+| cutting-edge | new | promotional |
+| serves as | is | indirect copula |
+| stands as | is | indirect copula |
+| boasts | has | indirect copula |
+| substrate | - | abstract metaphor, name the thing |
+| wedge | - | abstract metaphor, name the thing |
+| locus | - | abstract metaphor, name the thing |
+| vantage | - | abstract metaphor, name the thing |
+| nexus | - | abstract metaphor, name the thing |
+| bedrock | - | abstract metaphor, name the thing |
+| modality | - | abstract metaphor, name the thing |
+| paradigm | - | abstract metaphor, name the thing |
+| north star | - | abstract metaphor, name the goal |
+| flywheel | - | abstract metaphor, name the loop |
+| endgame | - | abstract metaphor, name the outcome |
+| gold-plating | - | abstract metaphor, name the extra work |
+| ratchet | - | abstract metaphor, name the mechanism |
+| utilize | use | |
+| commence | start | unnecessarily fancy |
+| ascertain | find out | unnecessarily fancy |
+| endeavour | try | unnecessarily fancy |
+| myriad | many | unnecessarily fancy |
+| plethora | many | unnecessarily fancy |
+| elucidate | explain | unnecessarily fancy |
+| leverage | use | |
+| facilitate | help | |
+| numerous | many | |
+| in the event that | if | |
+| in order to | to | judgment call: keep it when "to" alone reads wrong |
+| due to the fact that | because | |
+| prior to | before | |
+| subsequent to | after | |
+| commence | start | |
+| terminate | end | |
+| ensure | make sure | or check; keep when it is the literal verb |
+| experts believe | - | vague sourcing, name the source |
+| industry reports suggest | - | vague sourcing, name the report |
+| some critics argue | - | vague sourcing, name who argues it |
+| it is widely known | - | vague sourcing, cite it or cut it |
+| highlighting | - | -ing filler, start a new sentence |
+| showcasing | - | -ing filler, start a new sentence |
+| ensuring that | make sure | -ing filler |
+| reflecting | - | -ing filler, start a new sentence |
+| fostering | - | -ing filler, and AI vocabulary |
+
+## Marks
+
+| Avoid | Write instead | Note |
+| --- | --- | --- |
+| — | en dash with spaces | or a period between the two clauses |
+| “ | " | curly double quote, opening |
+| ” | " | curly double quote, closing |
+| ‘ | ' | curly single quote, opening |
+| ’ | ' | curly single quote, closing |
+| … | ... | or a period |