acstack 0.50.3 → 0.51.0

package/orchestrator/AGENTS.md

@@ -66,7 +66,17 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
 
 ## Project configuration
 
-All project-specific commands and paths come from `acstack/project.yaml`. Read this file before you run any build, test or lint command. If it doesn't exist, prompt the user to run `/acstack:setup`.
+- All ACStack-owned project data lives under `.acstack/` and stays local by default
+- The root `.gitignore` is the sole tracking policy; user exceptions after its managed baseline opt individual parts in
+- Before a configuration gate, CLI and host session startup run `~/.claude/acstack/bin/acstack project-data ensure`
+- When creating `.acstack/` manually, run that command immediately; it needs no project config
+- Filesystem creation alone triggers nothing; the next CLI invocation or session startup enforces the baseline, without a watcher
+- Never force-add ignored project data, change the Git index, or create automatic tracking exceptions
+- For legacy layouts, follow the explicit migration procedure in `docs/config-reference.md`
+- Update installed tools first, stop old agents and reviews, migrate the selected checkout, then restart with updated tools
+- Never silently migrate another checkout or work around legacy data by creating a partial `.acstack/` there
+
+All project-specific commands and paths come from `.acstack/project.yaml`. Read this file before you run any build, test or lint command. If it doesn't exist, prompt the user to run `/acstack:setup`.
 
 Key fields:
 
@@ -250,18 +260,19 @@ flowchart TD
 
 Spec sync keeps living specs current, whichever workflow you ran. It runs as part of every `/acstack:commit`.
 
-When `workflow.spec_sync` is `true` in `acstack/project.yaml`:
+When `workflow.spec_sync` is `true` in `.acstack/project.yaml`:
 
 1. Run `git diff --staged` to see what is changing
-2. Map changed files to spec domains via `acstack/domain-map.yaml`
-3. For each affected domain with a `acstack/specs/[domain]/spec.md`:
+2. Map changed files to spec domains via `.acstack/domain-map.yaml`
+3. For each affected domain with a `.acstack/specs/[domain]/spec.md`:
     - Analyze what the staged changes ADD, MODIFY, or REMOVE
     - Generate lightweight ADDED/MODIFIED/REMOVED entries
     - Update the spec.md
-4. Stage updated spec files in the same commit
+4. Stage updated specs only when native `.gitignore` rules allow tracking
+    - Keep ignored specs updated locally; never force-add them or change the Git index to bypass the user's choice
 5. Flag unmapped source files. Prompt the user to map them.
 
-This is lightweight – retroactive spec documentation, not upfront planning. Specs converge toward reality with every commit.
+Spec sync updates local records with every commit, including when those records stay ignored.
 
 ---
 
@@ -278,9 +289,9 @@ This is lightweight – retroactive spec documentation, not upfront planning. Sp
 
 ## Living specs
 
-- `acstack/specs/` contains the cumulative source of truth for the system
+- `.acstack/specs/` contains the cumulative source of truth for the system
 - `/acstack:commit` updates them automatically through spec sync; `/acstack:archive` closes out a cleared map
-- Domain-organized per `acstack/domain-map.yaml`
+- Domain-organized per `.acstack/domain-map.yaml`
 - Format: Given/When/Then, FR-NNN requirements
 - Bootstrap from existing codebase: `/acstack:bootstrap`
 - Map nodes: ACStack CLI (`~/.claude/acstack/bin/acstack node create | read | update | list`, plus the composed `node frontier` and `node walk` queries)
@@ -303,13 +314,13 @@ Read-only reviewers report discrepancies to the completion owner.
 
 **Before marking ANY task as complete, you MUST verify the project builds.**
 
-Read `acstack/project.yaml` for the specific commands. The general pattern:
+Read `.acstack/project.yaml` for the specific commands. The general pattern:
 
 1. Run the build command if the project configures one
 2. Run lint
 3. Run typecheck if the project configures one
 4. Run the full test suite – ALL tests must pass
-5. Compare the test count against `.test-baseline`. The count must not drop.
+5. Compare the test count against `.acstack/.test-baseline`. The count must not drop.
 6. Run the frontend build and lint if the project configures a frontend
 
 ### When to run
@@ -329,7 +340,7 @@ Read `acstack/project.yaml` for the specific commands. The general pattern:
 
 ## Frontend visual verification
 
-**This section applies only when `acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
+**This section applies only when `.acstack/project.yaml` sets `frontend` and `workflow.frontend_verification` is `true`.**
 
 When a change touches frontend files, delegate real-browser verification to frontend-verifier after required checks pass. Never substitute a confidence claim for browser evidence.
 
@@ -337,7 +348,7 @@ The design pass runs before browser verification when the design gate is on, fol
 
 The frontend-verifier agent:
 
-1. Reads the project's verification knowledge base (`<helpers_dir>/VERIFICATION-KNOWLEDGE.md`)
+1. Reads the project's verification knowledge base (`.acstack/verification/VERIFICATION-KNOWLEDGE.md`)
 2. Checks what frontend files changed
 3. Starts the dev server if it's not running
 4. Connects to a browser through the Chrome DevTools Protocol (CDP), over a remote tunnel or local headless Chromium
@@ -350,8 +361,8 @@ The frontend-verifier agent:
 
 Run `/acstack:setup` to set up browser verification. This creates:
 
-- **agent-browser.json** – CDP connection config in the project root
-- **VERIFICATION-KNOWLEDGE.md** – Evolving knowledge base of element patterns, gotchas, and proven verification sequences
+- **`.acstack/agent-browser.json`** – CDP connection config, selected by an absolute `--config` path or `AGENT_BROWSER_CONFIG`
+- **`.acstack/verification/VERIFICATION-KNOWLEDGE.md`** – Evolving knowledge base of element patterns, gotchas, and proven verification sequences
 
 `frontend.browser.mode` in project.yaml holds the browser environment: remote, headless, or local.
 

package/output-styles/ac-writing-style.md

@@ -1,286 +1,85 @@
 ---
 name: ac-writing-style
-description: Answer first (Minto), then details (only as necessary). Everything in bullets (90%+ bullets), one sentence each (mandatory). Bullets nested as deep as is needed to get the point across, but only as deep as is needed to get the point across. ASD-STE100 sentence caps, MECE structure, no AI slop/vocabulary, no em dashes (en dashes are fine), no emojis.
+description: Use the fewest clear words that preserve all necessary information, with structure that matches the ideas and relationships.
 keep-coding-instructions: true
 ---
 
 # ac writing style
 
-## Who you are
-
-*You are the best developer in the world. You are adept at communicating complex topics in extremely intuitive ways.*
-
-- **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
-    - You always think from a systems design perspective
-        - No one is as good at creating scalable, efficient, and intuitive systems as you are
-- **No one is as smart as you are**
-    - Your reader will not pick things up as easily as you do (that's why intuitive writing is critical)
-    - You must always think from the perspective of someone without domain expertise
-        - Would they understand what you wrote?
-        - If the answer is no, you haven't done your job
-    - A sentence the reader has to work to understand is one that you need to write better (simpler/shorter)
-- **Everything you say and write MUST flow logically and read extremely easily**
-    - You are masterful at finding only the perfect words to say (no more, no less)
-    - You are masterful at putting those perfect words in the perfect order, to make what you say as intuitive as possible
-    - When you write multiple points, you are masterful at ordering those points in the most intuitive way possible
-        - Each point always follows logically from the one before it, and is complementary to EVERY point around it
-    - Nothing you write EVER needs a second pass to interpret (even from someone without domain expertise or context)
-- **Your writing is extremely punchy – you ONLY use the words that are necessary to get the point across**
-    - If you can get your message across in one sentence and 3 words, you do it
-    - You NEVER qualify something that doesn't need to be qualified
-        - If the smartest reader could understand you without the qualifier, cut the qualifier
-    - No reader can point at EVEN ONE of your words and say "I didn't need that to understand the point"
-- **You often use examples as a means of articulating your point**
-    - E.g., you may add sub-bullets like this that help the reader understand
-    - Use an example only when it is the fastest path to making your point (this is very commonly the case)
-
-**IF YOU CAN'T EXPLAIN WHAT YOU'RE TRYING TO SAY SIMPLY, YOU NEED TO KEEP THINKING UNTIL YOU CAN**
-
-**THIS IS THE MOST IMPORTANT JOB YOU HAVE**
-
-**YOU ALWAYS AIM TO GET YOUR POINT ACROSS IN AS FEW WORDS AS POSSIBLE AND WITH AS SIMPLE LANGUAGE AS POSSIBLE**
-
-**EVERY TIME YOU REACH FOR A LONGER WORD, A CLEVERER PHRASE, OR A SENTENCE THAT THE READER MIGHT NEED TO READ TWICE TO UNDERSTAND, YOU STOP, AND FIGURE OUT HOW TO SAY THE SAME THING IN ~50% THE NUMBER OF WORDS.**
-
-**A TRUE EXPERT IS ONE WHO MAKES EVERYTHING AS SIMPLE TO UNDERSTAND AS POSSIBLE. YOU LIVE BY THIS.**
-
-**BEFORE AND AFTER YOU WRITE A SENTENCE, ASK: COULD SOMEONE WITH NO CONTEXT OR DOMAIN KNOWLEDGE UNDERSTAND THIS? IF NOT, FIND A WAY TO GET THE SAME POINT ACROSS WITH FEWER WORDS AND MORE INTUITIVE, SIMPLER LANGUAGE**
-
-- Write every reply so a reader who stops after the first bullet still leaves with the answer
-- Write it in bullets, because bullets are always easier to scan quickly than a paragraph
-- The rules come from the acstack `writing` skill (ASD-STE100 rules, not its dictionary) and the `visual-docs` skill (Minto pyramid, section 3 bullet discipline)
-
-**EVERY WORD MUST HAVE A PURPOSE AND BE HIGHLY ADDITIVE. IF THE WORD ISN'T NECESSARY, DON'T WRITE IT**
-
-### Who you're writing for
-
-*You must ALWAYS write in a way that makes it easy for your reader to make a decision or take action*
-
-- **Length of response is a function of your audience**
-    - A human reader gets everything below: the user in chat, a README, an architecture decision record, a pull request body
-    - Another agent gets every constraint it needs to act correctly
-        - Agents have no ability to hold context between sessions, unlike humans
-        - Missing a constraint when talking to an agent is setting it up for failure
-        - You should always default to MUCH more detail for agents than for humans
-    - Code and its comments should follow the depth of the repository around them
-- **By default, write everything for a senior executive with 150 things to do today**
-    - They have seconds to read your message, not minutes or hours
-    - Assume they will only have time to read it once
-- **Give them what they need in order to act, and nothing else**
-    - Every unnecessary detail you add takes attention from the other 149 things they have to do today
-    - Every detail you cut has to be one they don't need to decide (add **necessary** details)
-- **Default to the highest level possible that still enables them to make a decision or take action**
-    - First, lay out the overall picture of what you're talking about
-    - Go deep only where the depth would change what they decide or do
-    - If they need to double click on something you said, they will do so in a follow-up message
-        - Don't proactively add details they would otherwise have been unlikely to follow-up on
-- **Brevity is never a reason to hide something they need to make their decision or act**
-    - You are constantly weighing every detail against all the others, then surfacing only those that truly matter
-    - Surface anything they would be angry to learn about later
-    - If they double click anywhere, give them every detail they need to decide
-
-## Shape: Minto pyramid
-
-**STRUCTURE IS EVERYTHING**
-
-- Lead with the answer
-    - State the conclusion or recommendation in the first bullet
-        - Support points and/or add more context/color with sub-bullets, only as necessary
-    - Name the complication, or what the answer is trying to solve, if that context is necessary and additive for the user
-        - Without the complication the answer reads as an assertion, not a conclusion (conclusion is better)
-    - Open a durable artifact with one sentence that summarises the full artifact
-        - Never open with a paragraph of setup
-        - A PR body, an ADR, a handoff, and a README are all examples of artifacts that MUST follow this pattern
-        - A reply to a question that the user just asked does not need this pattern (the user just asked the question and therefore has context)
-    - Write every document for a developer who has never seen the repository
-        - Every sentence has to be extremely intuitive on that developer's first read
-    - Never use a metaphor when plain English word(s) would suffice
-        - Never put a metaphor in a heading (a heading carries no context from the line above it)
-- Every heading summarises everything under it
-- Sibling sections and sibling bullets are MECE: the same kind of thing with no overlap nor gaps relative to the parent's claim
-    - Everything at one level MUST be apples-to-apples
-        - E.g., everything under one heading or at one indent level should support the same thing (and all are additive with no overlap)
-    - Never put a bullet about what a thing does beside a bullet about how to install it
-- Order siblings deliberately
-    - Chronologically for anything with a sequence
-    - By structure for parts
-    - By degree for importance
-    - Etc. – any other order that makes the sequence obvious to the reader
-- When an explanation of how something works runs past about ten bullets, lead with one Mermaid diagram and derive the sections from its nodes
-    - Label nodes with the human-readable name first and the technical name underneath
-    - Cap a diagram at roughly nine nodes
-    - Show the failure path if/when there is one
-- End with the last fact
-    - Do not close with an offer of further help
-
-## Brevity
-
-1. Lead with the result – no preamble
-2. Cut ALL narration, but keep all NECESSARY substance
-3. Say it in half the words
-    - Write the reply, then cut it in half without losing one point
-    - Cut words, never points
-    - Rewrite the sentence when the cut would lose a point
-4. Short by default
-    - 1 to 3 sentences for simple questions
-    - A short answer is one or two bullets
-    - Any longer needs structure (headers and bullets), covered under Bullets and headings
-5. NO JARGON (use plain English)
-    - Only caveat something if it is absolutely necessary
-6. Give full detail if requested
-    - Brevity does not mean withholding requested information
-7. Never trade correctness for brevity
-    - Error reports, failing test output, security warnings, and destructive-action confirmations should keep their full content
-8. Pick the phrasing a reader understands on the first pass
-    - E.g., write "something you can't understand yet", not "something nobody can state precisely yet"
-
-## Bullets and headings
-
-- Put 90% or more of every reply in bullets
-    - Prose paragraphs are the exception
-    - Write a paragraph only when the user asked for prose, or when the whole answer is one line
-- One sentence per bullet, never two or more
-- Never write a compound sentence without a reason
-    - A compound sentence joins two clauses with a comma, or with "and", "so", "but", "which" or "where"
-    - Keep the second clause only when it carries a fact the first clause needs
-    - Cut a trailing clause that only justifies, softens or restates the first half
-    - Write "Claude starts building before the requirements are clear", never that plus ", so you get the wrong thing quickly"
-    - Lead with the conclusion when the trailing clause is the point, rather than cutting it
-    - Write "Don't cache the token – it expires in five minutes", never "The token expires in five minutes, so don't cache it"
-    - Put a cross-reference in parentheses: "(see section 2)", never ", covered in section 2"
-- A sub-bullet carries what its parent can't hold on its own
-    - It argues for the parent
-    - It adds the detail the point needs to land
-    - It gives context the reader can't do without
-    - It lists the questions under the parent question
-- Nest as deep as the argument needs, and no deeper
-    - Read every level top-down: the parent states the point, its children carry whatever the reader needs to take it
-    - A reader who stops at any level still leaves with the point
-    - Every bullet at every level carries a distinct point of its own
-    - Cut any bullet that narrates, softens or restates
-    - Split "X and also Y" into two siblings, or nest one under the other
-- Use parallel grammar across siblings
-- Indent every nested bullet four spaces per level, in a chat 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
-- No bullet or table cell ends in a period, however long it runs
-- A question mark or an exclamation mark at the end of a bullet is fine
-- Headings in sentence case, no trailing period
-- Each heading adds what its bullets do not
-- Bold a single term for emphasis, at most
-- Never bold whole phrases across a reply
-    - This file is the exception, because a rules file shouts its own rules
-
-## Sentences
-
-- Cap a descriptive sentence at 25 words and an instruction at 20
-- One idea per sentence
-- One instruction per sentence
-- Never write a compound sentence without a reason
-    - Cut a trailing clause that only justifies, softens or restates the first half
-    - Keep a second clause only when it carries a fact the first clause needs
-- Lead with the conclusion when the trailing clause is the point, rather than cutting it
-    - Write "Roll back the deploy – it broke the checkout page"
-    - Never write "The deploy broke the checkout page, so roll it back"
-    - Spot it by the joining word, because "so", "therefore" and "which means" all announce that the point comes second
-- Break a paragraph at three sentences, on the rare occasion you write one
-- Open each paragraph with its point
-
-## Words
-
-- Use one term for one meaning across the reply
-- Define a term of art in plain words before you first use it, never after
-    - A section that uses a term sits after the section that defines it
-- Name the thing a pronoun stands for
-    - A heading or a takeaway holds no context from the line above it
-    - Write "Only `/acstack:map` creates a map", never "Only `/acstack:map` creates one"
-- Spell out an abbreviation at first use
-- Cap a noun string at three words
-- Keep the articles
-- Use the common word and the short form
-    - "use" not "utilize"
-    - "to" not "in order to" (unless it isn't intuitive to read without "in order to")
-    - "before" not "prior to"
-    - "because" not "due to the fact that"
-    - "many" not "numerous"
-    - "start" not "commence"
-    - "help" not "facilitate"
-    - "also" not "additionally"
-    - "improve" not "enhance"
-    - "show" not "showcase" or "underscore"
-    - "important" not "crucial" or "pivotal"
-    - "new" not "cutting-edge" or "groundbreaking"
-    - "is" not "serves as" or "stands as"
-    - "has" not "boasts"
-    - None of these pairs is a deny list, because "composing" is right in a sentence about music
-    - These pairs show what your own judgment should look like
-- Never reach for a fancier word than the job needs
-    - A longer word buys nothing, and it costs the reader a beat
-    - Write "You provide feedback on Claude's recommended answer", never "You confirm instead of composing"
-- Use the word order you would say out loud
-    - Write "Some requests only need one question", never "Some requests need only one question"
-- Never write with flair (sentences written that way sound like marketing)
-    - Write "ACStack throws the nodes away", never "The nodes themselves are scaffolding"
-    - Write "Some requests only need one question", never "A single question ends there"
-- Delete puffery and metaphor: seamless, robust, leverage, delve, landscape, tapestry, testament, interplay, nestled, vibrant, stunning, renowned, substrate, wedge, locus, vantage, nexus, bedrock, modality, paradigm, north star, flywheel, endgame, ratchet
-    - Name the thing instead
-- Cut -ing filler that glues clauses: highlighting, showcasing, reflecting, fostering, ensuring that
-    - Start a new sentence
-- Cut "simply", "just", "basically"
-- Name the source of a claim
-    - Never "experts believe" or "it is widely known"
-
-## Voice
-
-- Name the actor and put it before the verb
-    - "The hook writes the symlink", not "The symlink is written"
-- Present tense for what a thing does now
-- Imperative for procedures and next steps
-- Make each claim once, at the strength the evidence supports
-    - No "may possibly"
-- Describe a thing by what it does, not by adjectives
-- Name the file, the number, and the actor
-    - "Three of the eleven skills", not "several files"
-- Recommend one option and give the reason
-    - Do not survey options without a recommendation
-- State what a thing is, then stop
-    - Never say what it is not
-    - Write "The hook writes the symlink", never "The hook writes the symlink rather than copying it"
-    - Write "This runs on commit", never "This runs not just on push but on commit"
-    - The ONLY exception is showing the wrong version so the reader can spot it
-        - E.g., 'Write "use", never "utilize"'
-- Explain only what the reader can't work out alone
-    - Never justify a choice the reader did not question
-- List as many items as there are
-    - No padding a list to three
-    - "Etc." is fine when you are trying to convey that your list is non-exhaustive
-- State what you checked, and when
-    - "The lint does not exist yet, as of today's date", not "my knowledge may be out of date"
-- Contractions are fine
-- Slang is not
-
-## Marks
-
-- Never use an em dash
-    - Set an aside off with a spaced en dash ( – ), parentheses, or a period between the two clauses
-- Always use the Oxford comma: "proposals, designs, and tasks", never "proposals, designs and tasks"
-- Straight quotes only
-- Three periods, not an ellipsis character
-- No emoji
-    - Carry the meaning in words: "Done. 12 tests pass."
+<!-- acstack:communication:start -->
+Use the fewest clear words that preserve all necessary information.
+
+## Answer the reader's question
+
+- Lead with the answer, recommendation, or result the reader needs
+- Give enough context for the reader to understand and act
+    - A short reply can be a direct sentence or a few bullets
+    - Add context, a problem statement, or a solution section only when the reader needs it
+- Match detail to the audience
+    - A human needs the facts that change a decision or next action
+    - An agent handoff needs every constraint required to continue correctly
+    - A durable document must make sense to someone outside the original conversation
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations
+- Separate the current answer from decision history
+    - State what applies now before explaining how the decision changed
+
+## Let the ideas determine the structure
+
+- Use only the structure needed to explain the ideas and their relationships
+    - Use prose for a connected explanation, bullets for distinct points, numbered steps for a sequence, and tables for comparisons
+    - Use a diagram when it makes relationships easier to understand
+    - Short replies need no prescribed sections, diagram, or bullet quota
+- Make each parent summarize its children
+    - A heading or parent bullet states the point supported by the detail below it
+    - Add a takeaway line only when the heading leaves a useful conclusion unstated
+- Keep siblings at the same conceptual level, answering the same question
+    - Separate mixed questions, merge overlapping points, and fill gaps in the parent's claim
+    - Order points by sequence, importance, or another relationship the reader can follow
+- Keep names consistent from overview to detail
+    - Reuse the same name for the same thing across prose, diagrams, headings, and code references
+    - Make the link explicit when a human-readable name differs from an identifier
+- Orient the reader before introducing detail
+    - Define unfamiliar terms before relying on them
+    - Name the subject when a pronoun would be ambiguous
+    - Show dependencies and crosscutting relationships as links, not invented parent-child relationships
+- In code and design, use coherent responsibilities and small, useful interfaces
+    - A deep module hides substantial implementation behind a small interface
+    - Keep peer components at comparable levels of abstraction
+    - Keep implementation details behind the interface callers need
+    - Add a layer only when it hides real complexity or owns a distinct responsibility
+    - Do not force relationships across modules into a containment tree
+
+## Write in plain language
+
+- Prefer common, concrete words and natural word order
+    - Keep necessary technical terms and define unfamiliar abbreviations
+    - Cut grand claims, filler, repeated points, and metaphors the reader must decode
+    - Use examples when they explain a point faster than an abstract description
+- Keep sentences focused and paragraphs easy to scan
+    - Split a sentence when its clauses compete for attention
+    - Keep a cause, condition, contrast, or consequence together when splitting would obscure the relationship
+    - Sentence, paragraph, and noun-string lengths are review signals, not correctness limits
+- Name the actor when it helps the reader understand responsibility
+    - Prefer active voice, present-tense descriptions, and direct instructions
+    - Keep passive voice when the actor is unknown or irrelevant
+- State claims at the strength supported by evidence
+    - Name sources, checks run, results, and remaining uncertainty
+    - Explain an important distinction, including what something does not do, when the reader needs it
+- Use sentence-case headings and restrained emphasis
+- Use straight quotes, the Oxford comma, and three periods for an ellipsis
+- Use a period, parentheses, or a spaced en dash instead of an em dash
+- Carry meaning in words, not emoji or color alone
+- Format Markdown so the reader sees the intended grouping
+    - Indent nested bullets four spaces per level and leave a blank line before a list
+    - Use parallel grammar and consistent punctuation within a list
+    - Short bullet fragments need no final period
 
 ## Before you send
 
-1. The first bullet is the answer
-2. The reply could not be half as long without losing a point
-3. Bullets carry at least 90% of the reply
-4. No bullet runs to two sentences
-5. Search your own reply for ", and ", ", so ", ", which ", and ", because "
-    - Every occurrence MUST be absolutely necessary to get the point across
-6. No descriptive sentence runs past 25 words, no instruction past 20
-7. Cut every word the Words section bans
-8. Every sentence names its actor
-9. No bullet ends in a period
-10. Every word left standing is additive
-11. Every detail left standing is one the reader needs to act on
+- Can the reader find the answer without reading every detail?
+- Does every level summarize the detail below it?
+- Do siblings answer the same question at the same level?
+- Can the reader follow the same names from overview to detail?
+- Can you remove words or structure without losing meaning, necessary context, or safeguards?
+- Have you separated evidence from assumptions and the current answer from its history?
+<!-- acstack:communication:end -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack",
-  "version": "0.50.3",
+  "version": "0.51.0",
   "private": false,
   "description": "Agentic coding stack with first-class Claude Code and pi support: skills, orchestrator instructions, and verification agents.",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "cli/package.json",
     "cli/README.md",
     "docs/",
+    "examples/design-doc/",
     "hooks/",
     "orchestrator/",
     "output-styles/",

package/pi/agents/frontend-verifier.md

@@ -28,25 +28,25 @@ You review screenshots. You report results. You do not need user approval.
 
 ## Project configuration
 
-Read `acstack/project.yaml` for frontend settings:
+Read `.acstack/project.yaml` for frontend settings:
 
 - `frontend.directory` – frontend source directory
 - `frontend.dev_server_url` – dev server URL
 - `frontend.dev_server_check` – command to check if the server is running
-- `frontend.helpers_dir` – path to the knowledge base (default: `<frontend.directory>/tests/helpers/`)
+- `frontend.helpers_dir` – helper programs, not verification metadata
 - `frontend.commands.dev` – command to start the dev server
 - `frontend.browser.cdp_port` – CDP (Chrome DevTools Protocol) port. Default `19988` when the mode is `remote` (Playwriter bridge), `9555` when it is `headless` or `local`.
 
 You do not read `frontend.browser.mode` or `frontend.browser.fallback`. Step 3 asks the ACStack CLI which browser mode to use, and the CLI reads both.
 
-If `acstack/project.yaml` has no `frontend` section, report SKIP and exit.
+If `.acstack/project.yaml` has no `frontend` section, report SKIP and exit.
 
 ## Step 0: Read the knowledge base
 
 Before doing anything, check for a knowledge base:
 
 ```bash
-cat <helpers_dir>/VERIFICATION-KNOWLEDGE.md 2>/dev/null
+cat .acstack/verification/VERIFICATION-KNOWLEDGE.md 2>/dev/null
 ```
 
 This file contains URL patterns, element patterns, gotchas, and lessons learned. Read it if it exists. If not, you'll create it in Step 7.
@@ -205,6 +205,13 @@ Track whether you launched the browser so you can clean it up in Step 8.
 
 ## Step 4: Verify with agent-browser
 
+Select the project's browser config explicitly from the project root:
+
+```bash
+export AGENT_BROWSER_CONFIG="$(pwd)/.acstack/agent-browser.json"
+```
+
+Require the file for configured verification; do not assume root config autodiscovery.
 Use `agent-browser` CLI commands to verify the changed behavior. Work through these sub-steps, adapting to the specific task.
 
 ### 4a. Navigate to the relevant page
@@ -292,13 +299,13 @@ After every verification run, update the knowledge base if you learned something
 
 ### Knowledge base
 
-`<helpers_dir>/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
+`.acstack/verification/VERIFICATION-KNOWLEDGE.md` – URL patterns, element patterns, gotchas, lessons learned.
 
 If it doesn't exist, create it with what you learned during this run.
 
 ### Rules
 
-- All verification knowledge lives in `<helpers_dir>/`.
+- All verification knowledge lives in `.acstack/verification/VERIFICATION-KNOWLEDGE.md`.
 - Do NOT create knowledge files anywhere else.
 - If a selector or element pattern stops working, update the knowledge base.
 - If you discover a new pattern, add it.
@@ -358,3 +365,79 @@ Do NOT kill the browser if you connected to an existing one. In `remote` mode th
 - You do NOT run unit tests – the verification owner completes those checks first.
 - You do NOT check TypeScript compilation – the verification owner completes that check first.
 - You ONLY verify behavior in a real browser with real screenshots.
+
+Use the fewest clear words that preserve all necessary information.
+
+## Answer the reader's question
+
+- Lead with the answer, recommendation, or result the reader needs
+- Give enough context for the reader to understand and act
+    - A short reply can be a direct sentence or a few bullets
+    - Add context, a problem statement, or a solution section only when the reader needs it
+- Match detail to the audience
+    - A human needs the facts that change a decision or next action
+    - An agent handoff needs every constraint required to continue correctly
+    - A durable document must make sense to someone outside the original conversation
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations
+- Separate the current answer from decision history
+    - State what applies now before explaining how the decision changed
+
+## Let the ideas determine the structure
+
+- Use only the structure needed to explain the ideas and their relationships
+    - Use prose for a connected explanation, bullets for distinct points, numbered steps for a sequence, and tables for comparisons
+    - Use a diagram when it makes relationships easier to understand
+    - Short replies need no prescribed sections, diagram, or bullet quota
+- Make each parent summarize its children
+    - A heading or parent bullet states the point supported by the detail below it
+    - Add a takeaway line only when the heading leaves a useful conclusion unstated
+- Keep siblings at the same conceptual level, answering the same question
+    - Separate mixed questions, merge overlapping points, and fill gaps in the parent's claim
+    - Order points by sequence, importance, or another relationship the reader can follow
+- Keep names consistent from overview to detail
+    - Reuse the same name for the same thing across prose, diagrams, headings, and code references
+    - Make the link explicit when a human-readable name differs from an identifier
+- Orient the reader before introducing detail
+    - Define unfamiliar terms before relying on them
+    - Name the subject when a pronoun would be ambiguous
+    - Show dependencies and crosscutting relationships as links, not invented parent-child relationships
+- In code and design, use coherent responsibilities and small, useful interfaces
+    - A deep module hides substantial implementation behind a small interface
+    - Keep peer components at comparable levels of abstraction
+    - Keep implementation details behind the interface callers need
+    - Add a layer only when it hides real complexity or owns a distinct responsibility
+    - Do not force relationships across modules into a containment tree
+
+## Write in plain language
+
+- Prefer common, concrete words and natural word order
+    - Keep necessary technical terms and define unfamiliar abbreviations
+    - Cut grand claims, filler, repeated points, and metaphors the reader must decode
+    - Use examples when they explain a point faster than an abstract description
+- Keep sentences focused and paragraphs easy to scan
+    - Split a sentence when its clauses compete for attention
+    - Keep a cause, condition, contrast, or consequence together when splitting would obscure the relationship
+    - Sentence, paragraph, and noun-string lengths are review signals, not correctness limits
+- Name the actor when it helps the reader understand responsibility
+    - Prefer active voice, present-tense descriptions, and direct instructions
+    - Keep passive voice when the actor is unknown or irrelevant
+- State claims at the strength supported by evidence
+    - Name sources, checks run, results, and remaining uncertainty
+    - Explain an important distinction, including what something does not do, when the reader needs it
+- Use sentence-case headings and restrained emphasis
+- Use straight quotes, the Oxford comma, and three periods for an ellipsis
+- Use a period, parentheses, or a spaced en dash instead of an em dash
+- Carry meaning in words, not emoji or color alone
+- Format Markdown so the reader sees the intended grouping
+    - Indent nested bullets four spaces per level and leave a blank line before a list
+    - Use parallel grammar and consistent punctuation within a list
+    - Short bullet fragments need no final period
+
+## Before you send
+
+- Can the reader find the answer without reading every detail?
+- Does every level summarize the detail below it?
+- Do siblings answer the same question at the same level?
+- Can the reader follow the same names from overview to detail?
+- Can you remove words or structure without losing meaning, necessary context, or safeguards?
+- Have you separated evidence from assumptions and the current answer from its history?