acstack 0.54.1 → 0.54.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "acstack",
   "description": "Agentic coding stack where planning grows only as far as needed: a map of decisions, tasks, checks, and handoffs behind a pluggable tracker.",
-  "version": "0.54.1",
+  "version": "0.54.3",
   "author": {
     "name": "ac8318740"
   },

package/README.md

@@ -55,13 +55,10 @@ Install the plugin:
 /plugin install acstack@ac-agentic-coding
 ```
 
-Then, in your project:
+Then, in your Git repository, use `/acstack:implement`, `/acstack:quick-fix`, or `/acstack:pre-commit-review` directly. Without project configuration, ACStack follows repository instructions and discovers tooling from manifests, tests, and CI.
 
-```
-/acstack:setup
-```
-
-- `/acstack:setup` detects the project type, then writes `project.yaml` with workflow settings into the project folder
+- Optional: `/acstack:setup` detects the project type and writes `project.yaml` for saved workflow settings and storage-backed features such as maps and living specs
+    - Existing configuration keeps its gates; invalid configuration or project-data conflicts require repair, not an unconfigured fallback
 - All ACStack-owned project records live in one project folder per repository, shared by all of its worktrees
     - `~/.claude/acstack/bin/acstack project-data path` prints it; by default it is `~/.acstack/projects/<key>/`, outside the repository
     - Run `acstack project-data mode tracked` to keep the records in the repository's `.acstack/` and commit them instead
@@ -69,7 +66,7 @@ Then, in your project:
 - Update installed ACStack tools before migrating an older project
     - Stop old agents and reviews, run `~/.claude/acstack/bin/acstack project-data migrate`, then restart with updated tools
     - Migration aborts on collisions without overwrites or Git index changes; tracked old paths become pending deletions
-- The SessionStart hook loads the orchestrator instructions whenever it detects an ACStack project
+- The SessionStart hook loads the orchestrator instructions in Git repositories, even without project setup
 - Your CLAUDE.md stays clean for project-specific content
 - Upgrading from a version before 0.8.0 means deleting one stale `@import` line (see [docs/migrate-0.8.md](docs/migrate-0.8.md))
 
@@ -82,7 +79,7 @@ pi install npm:@tintinweb/pi-subagents
 pi install npm:acstack
 ```
 
-Then, in your project, run `/acstack:setup`.
+Then use the general workflows in your Git repository immediately. Run `/acstack:setup` only when you want saved project settings or storage-backed features, as described above.
 
 - Every skill runs under the same name as on Claude Code, e.g. `/acstack:map`
     - `/acstack map` does the same
@@ -92,7 +89,7 @@ Then, in your project, run `/acstack:setup`.
     - The extension lists the skills in the system prompt instead, so the model still reads one when the task matches
 - `pi/extension.ts` does what the Claude Code hooks do
     - It links the CLI at `~/.claude/acstack/bin/acstack`
-    - It adds the orchestrator instructions to the system prompt in an ACStack project
+    - It adds the orchestrator instructions in Git repositories, even without project setup
     - It lists ACStack's skills in the system prompt in every session
     - It re-injects a handoff after a compaction
     - It nudges with a continuity-versus-freshness checkpoint as the context fills

package/agents/codex/frontend-verifier.toml

@@ -33,7 +33,7 @@ ACStack keeps project data in the project folder, the path `~/.claude/acstack/bi
 
 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 `<project folder>/project.yaml` has no `frontend` section, report SKIP and exit.
+If `<project folder>/project.yaml` is absent or has no `frontend` section, report SKIP (no configured frontend verification) and exit. Do not create configuration or require setup for general work. Report unreadable or invalid configuration and project-data resolution errors instead of treating them as absent.
 
 ## Step 0: Read the knowledge base
 
@@ -363,17 +363,21 @@ Do NOT kill the browser if you connected to an existing one. In `remote` mode th
 
 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
+## Fit the answer to the audience
+
+- Start with what the reader knows, what they do not know, and what they need from this answer
+    - Lead with the answer, recommendation, or result they need
+    - Include only the context needed to understand it and act; repeat known information only when necessary to connect the new information
+    - Omit a detail only when it does not affect the reader's understanding, decision, or next action
+    - If unsure whether a detail matters, include its essential point briefly rather than relying on the reader to ask
+- When reporting information to the user, be extremely concise and sacrifice grammar for sake of concision
+    - A headline or three-word answer is enough when it fully answers the question
+    - Use fragments freely; skip introductions, recaps, and supporting detail the user does not need
+    - Shorten wording, not meaning; keep conditions and ownership clear
+- Match completeness to the audience, not a length target
+    - An agent handoff needs every detail required to continue correctly, without padding
+    - A durable document needs enough context and precise wording to stand alone for its intended reader; chat's grammar shortcuts do not apply
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations; concision never overrides required disclosures
 - Separate the current answer from decision history
     - State what applies now before explaining how the decision changed
 
@@ -405,7 +409,7 @@ Use the fewest clear words that preserve all necessary information.
 
 ## Write in plain language
 
-- Prefer common, concrete words and natural word order
+- Prefer common, concrete words; use natural word order when it helps understanding
     - 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
@@ -417,20 +421,24 @@ Use the fewest clear words that preserve all necessary information.
     - 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
+    - Include sources, checks run, results, and uncertainty when the reader needs them to judge the claim or act
+    - Keep verification rigorous even when its supporting detail stays out of the report
     - 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
+- Use straight quotes and three periods for an ellipsis; use the Oxford comma in durable prose
+- Prefer parentheses over spaced en dashes for asides; use a period for a separate thought, never an em dash
+    - Use short parenthetical clarifications or examples (e.g., a concrete input) when they make something complex or ambiguous easier to understand
 - 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
+    - Keep list items parallel in meaning; in durable prose, also use parallel grammar and consistent punctuation
     - Short bullet fragments need no final period
 
 ## Before you send
 
-- Can the reader find the answer without reading every detail?
+- Does this give the reader exactly what they need, given what they already know?
+- Can a headline alone answer the question? If so, stop there.
+- Have you removed unnecessary detail without hiding anything that could change the reader's understanding, decision, or next action?
 - 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?

package/agents/codex/task-checker.toml

@@ -15,7 +15,7 @@ You are read-only: do not edit source, tests, or specs.
 ## Establish scope and ownership
 
 Read the supplied requirements, affected paths, known risks, and available command results.
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates.
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates. Without it, discover tooling from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`. Do not require setup, invent commands, or bypass invalid config or resolution errors.
 
 - Distinguish focused review from ownership of completion verification
 - If the assignment is unclear, clarify it with the delegating session before duplicating checks
@@ -81,17 +81,21 @@ Never present a focused PASS as completion of the whole effort.
 
 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
+## Fit the answer to the audience
+
+- Start with what the reader knows, what they do not know, and what they need from this answer
+    - Lead with the answer, recommendation, or result they need
+    - Include only the context needed to understand it and act; repeat known information only when necessary to connect the new information
+    - Omit a detail only when it does not affect the reader's understanding, decision, or next action
+    - If unsure whether a detail matters, include its essential point briefly rather than relying on the reader to ask
+- When reporting information to the user, be extremely concise and sacrifice grammar for sake of concision
+    - A headline or three-word answer is enough when it fully answers the question
+    - Use fragments freely; skip introductions, recaps, and supporting detail the user does not need
+    - Shorten wording, not meaning; keep conditions and ownership clear
+- Match completeness to the audience, not a length target
+    - An agent handoff needs every detail required to continue correctly, without padding
+    - A durable document needs enough context and precise wording to stand alone for its intended reader; chat's grammar shortcuts do not apply
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations; concision never overrides required disclosures
 - Separate the current answer from decision history
     - State what applies now before explaining how the decision changed
 
@@ -123,7 +127,7 @@ Use the fewest clear words that preserve all necessary information.
 
 ## Write in plain language
 
-- Prefer common, concrete words and natural word order
+- Prefer common, concrete words; use natural word order when it helps understanding
     - 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
@@ -135,20 +139,24 @@ Use the fewest clear words that preserve all necessary information.
     - 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
+    - Include sources, checks run, results, and uncertainty when the reader needs them to judge the claim or act
+    - Keep verification rigorous even when its supporting detail stays out of the report
     - 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
+- Use straight quotes and three periods for an ellipsis; use the Oxford comma in durable prose
+- Prefer parentheses over spaced en dashes for asides; use a period for a separate thought, never an em dash
+    - Use short parenthetical clarifications or examples (e.g., a concrete input) when they make something complex or ambiguous easier to understand
 - 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
+    - Keep list items parallel in meaning; in durable prose, also use parallel grammar and consistent punctuation
     - Short bullet fragments need no final period
 
 ## Before you send
 
-- Can the reader find the answer without reading every detail?
+- Does this give the reader exactly what they need, given what they already know?
+- Can a headline alone answer the question? If so, stop there.
+- Have you removed unnecessary detail without hiding anything that could change the reader's understanding, decision, or next action?
 - 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?

package/agents/codex/task-executor.toml

@@ -17,7 +17,9 @@ Implement the assigned requirements under the shared Implementation discipline i
 
 ## Project configuration
 
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints. Without configuration, discover settings from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`; do not require setup or invent commands. Report invalid config and resolution errors rather than bypassing them.
+
+Configured settings:
 
 - `directories.source` – where to write source code
 - `directories.tests` – test directory, subject to assigned ownership
@@ -94,17 +96,21 @@ Say what stopped you.
 
 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
+## Fit the answer to the audience
+
+- Start with what the reader knows, what they do not know, and what they need from this answer
+    - Lead with the answer, recommendation, or result they need
+    - Include only the context needed to understand it and act; repeat known information only when necessary to connect the new information
+    - Omit a detail only when it does not affect the reader's understanding, decision, or next action
+    - If unsure whether a detail matters, include its essential point briefly rather than relying on the reader to ask
+- When reporting information to the user, be extremely concise and sacrifice grammar for sake of concision
+    - A headline or three-word answer is enough when it fully answers the question
+    - Use fragments freely; skip introductions, recaps, and supporting detail the user does not need
+    - Shorten wording, not meaning; keep conditions and ownership clear
+- Match completeness to the audience, not a length target
+    - An agent handoff needs every detail required to continue correctly, without padding
+    - A durable document needs enough context and precise wording to stand alone for its intended reader; chat's grammar shortcuts do not apply
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations; concision never overrides required disclosures
 - Separate the current answer from decision history
     - State what applies now before explaining how the decision changed
 
@@ -136,7 +142,7 @@ Use the fewest clear words that preserve all necessary information.
 
 ## Write in plain language
 
-- Prefer common, concrete words and natural word order
+- Prefer common, concrete words; use natural word order when it helps understanding
     - 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
@@ -148,20 +154,24 @@ Use the fewest clear words that preserve all necessary information.
     - 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
+    - Include sources, checks run, results, and uncertainty when the reader needs them to judge the claim or act
+    - Keep verification rigorous even when its supporting detail stays out of the report
     - 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
+- Use straight quotes and three periods for an ellipsis; use the Oxford comma in durable prose
+- Prefer parentheses over spaced en dashes for asides; use a period for a separate thought, never an em dash
+    - Use short parenthetical clarifications or examples (e.g., a concrete input) when they make something complex or ambiguous easier to understand
 - 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
+    - Keep list items parallel in meaning; in durable prose, also use parallel grammar and consistent punctuation
     - Short bullet fragments need no final period
 
 ## Before you send
 
-- Can the reader find the answer without reading every detail?
+- Does this give the reader exactly what they need, given what they already know?
+- Can a headline alone answer the question? If so, stop there.
+- Have you removed unnecessary detail without hiding anything that could change the reader's understanding, decision, or next action?
 - 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?

package/agents/codex/test-writer.toml

@@ -26,7 +26,9 @@ You write tests from requirements and application programming interface (API) co
 
 ## Project configuration
 
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints. Without configuration, discover settings from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`; do not require setup or invent commands. Report invalid config and resolution errors rather than bypassing them.
+
+Configured settings:
 
 - `directories.tests` – where to create test files
 - `directories.source` – source code root (for mirroring structure)
@@ -144,17 +146,21 @@ When complete, report:
 
 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
+## Fit the answer to the audience
+
+- Start with what the reader knows, what they do not know, and what they need from this answer
+    - Lead with the answer, recommendation, or result they need
+    - Include only the context needed to understand it and act; repeat known information only when necessary to connect the new information
+    - Omit a detail only when it does not affect the reader's understanding, decision, or next action
+    - If unsure whether a detail matters, include its essential point briefly rather than relying on the reader to ask
+- When reporting information to the user, be extremely concise and sacrifice grammar for sake of concision
+    - A headline or three-word answer is enough when it fully answers the question
+    - Use fragments freely; skip introductions, recaps, and supporting detail the user does not need
+    - Shorten wording, not meaning; keep conditions and ownership clear
+- Match completeness to the audience, not a length target
+    - An agent handoff needs every detail required to continue correctly, without padding
+    - A durable document needs enough context and precise wording to stand alone for its intended reader; chat's grammar shortcuts do not apply
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations; concision never overrides required disclosures
 - Separate the current answer from decision history
     - State what applies now before explaining how the decision changed
 
@@ -186,7 +192,7 @@ Use the fewest clear words that preserve all necessary information.
 
 ## Write in plain language
 
-- Prefer common, concrete words and natural word order
+- Prefer common, concrete words; use natural word order when it helps understanding
     - 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
@@ -198,20 +204,24 @@ Use the fewest clear words that preserve all necessary information.
     - 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
+    - Include sources, checks run, results, and uncertainty when the reader needs them to judge the claim or act
+    - Keep verification rigorous even when its supporting detail stays out of the report
     - 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
+- Use straight quotes and three periods for an ellipsis; use the Oxford comma in durable prose
+- Prefer parentheses over spaced en dashes for asides; use a period for a separate thought, never an em dash
+    - Use short parenthetical clarifications or examples (e.g., a concrete input) when they make something complex or ambiguous easier to understand
 - 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
+    - Keep list items parallel in meaning; in durable prose, also use parallel grammar and consistent punctuation
     - Short bullet fragments need no final period
 
 ## Before you send
 
-- Can the reader find the answer without reading every detail?
+- Does this give the reader exactly what they need, given what they already know?
+- Can a headline alone answer the question? If so, stop there.
+- Have you removed unnecessary detail without hiding anything that could change the reader's understanding, decision, or next action?
 - 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?

package/agents/frontend-verifier.md

@@ -33,7 +33,7 @@ ACStack keeps project data in the project folder, the path `~/.claude/acstack/bi
 
 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 `<project folder>/project.yaml` has no `frontend` section, report SKIP and exit.
+If `<project folder>/project.yaml` is absent or has no `frontend` section, report SKIP (no configured frontend verification) and exit. Do not create configuration or require setup for general work. Report unreadable or invalid configuration and project-data resolution errors instead of treating them as absent.
 
 ## Step 0: Read the knowledge base
 

package/agents/task-checker.md

@@ -15,7 +15,7 @@ You are read-only: do not edit source, tests, or specs.
 ## Establish scope and ownership
 
 Read the supplied requirements, affected paths, known risks, and available command results.
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates.
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for commands, directories, environment activation, and applicable frontend gates. Without it, discover tooling from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`. Do not require setup, invent commands, or bypass invalid config or resolution errors.
 
 - Distinguish focused review from ownership of completion verification
 - If the assignment is unclear, clarify it with the delegating session before duplicating checks

package/agents/task-executor.md

@@ -17,7 +17,9 @@ Implement the assigned requirements under the shared Implementation discipline i
 
 ## Project configuration
 
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints. Without configuration, discover settings from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`; do not require setup or invent commands. Report invalid config and resolution errors rather than bypassing them.
+
+Configured settings:
 
 - `directories.source` – where to write source code
 - `directories.tests` – test directory, subject to assigned ownership

package/agents/test-writer.md

@@ -26,7 +26,9 @@ You write tests from requirements and application programming interface (API) co
 
 ## Project configuration
 
-Read `project.yaml` in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints for project-specific settings:
+Read `project.yaml` when present in the project folder that `~/.claude/acstack/bin/acstack project-data path` prints. Without configuration, discover settings from repository instructions, manifests, existing tests, and CI under Project configuration in `orchestrator/AGENTS.md`; do not require setup or invent commands. Report invalid config and resolution errors rather than bypassing them.
+
+Configured settings:
 
 - `directories.tests` – where to create test files
 - `directories.source` – source code root (for mirroring structure)

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acstack-cli",
-  "version": "0.54.1",
+  "version": "0.54.3",
   "description": "CLI for the ACStack agentic coding stack",
   "type": "module",
   "license": "MIT",

package/docs/config-reference.md

@@ -2,13 +2,17 @@
 
 *Every key in `project.yaml`, the values it takes, its default, and what changes when you change it.*
 
-One file, `<project folder>/project.yaml`, holds every setting that belongs to a project.
+Optional `<project folder>/project.yaml` holds saved ACStack project settings.
 The project folder is the repository's ACStack data folder, the path `~/.claude/acstack/bin/acstack project-data path` prints (section 1 explains where it lives).
 
+General implementation, investigation, and review work without setup. Without this file, agents use repository instructions, manifests, existing tests, and CI to discover commands and directories. They do not invent commands or create configuration automatically. Run `/acstack:setup` when you want saved settings or storage-backed features such as maps and living specs.
+
+Existing configuration keeps its gates. Unreadable or invalid configuration, legacy data, and project-data conflicts require the reported repair; they are not absent-config fallbacks. Orphan warnings alone do not block general work.
+
 - **It names what to run**: the test, build, lint, typecheck, and format commands
 - **It names where to look**: the source and test directories, and the frontend
 - **It configures required gates**: spec sync, frontend verification, and design review
-- **Every skill and every agent reads it** before it runs anything
+- **Agents read it when present** before running project checks
 - **A key you leave out takes the default** this document gives it
 
 Three terms first.
@@ -70,7 +74,8 @@ These commands report configuration without changing settings.
 
 - `~/.claude/acstack/bin/acstack project-data path` prints the project folder's absolute path, even before the folder exists
     - It exits non-zero outside a Git repository
-    - It exits non-zero with a message naming the fix when legacy data, an orphaned entry, or a conflict needs attention
+    - It exits non-zero with a repair message for legacy, invalid, or conflicting data
+    - Orphan warnings do not block a valid current repository or adopt the orphan's settings
     - The session-start hook states the same path in the agent's context
 - This document writes a part inside it as `<project folder>/project.yaml`, `<project folder>/specs/`, and so on
 - `/acstack:setup` creates the folder with `mkdir -p "$(~/.claude/acstack/bin/acstack project-data path)"`

package/hooks/session-start.sh

@@ -186,11 +186,6 @@ if ! project_folder=$(acstack_project_folder "$cli_wrapper"); then
   exit 0
 fi
 
-if [ ! -f "$project_folder/project.yaml" ]; then
-  echo 'acstack: no project config found. Run /acstack:setup to set up.' >&2
-  exit 0
-fi
-
 claude_md="${plugin_root}/orchestrator/AGENTS.md"
 
 if [ -z "$plugin_root" ] || [ ! -r "$claude_md" ]; then

package/orchestrator/AGENTS.md

@@ -102,7 +102,15 @@ ACStack runs on Claude Code, Codex, and pi. The skills name each capability once
     - Never silently migrate data or work around legacy data by creating a partial project folder
 - Never change the Git index or force-add files to track project data
 
-All project-specific commands and paths come from `<project folder>/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`.
+Project setup is optional for general implementation, investigation, and review. Resolve the project folder first; a prospective path or a folder without `project.yaml` is not an error.
+
+- When `<project folder>/project.yaml` exists, read it before running build, test, or lint commands and preserve its configured gates
+- Without it, use repository instructions, manifests, existing tests, and CI to discover commands, directories, and environment activation
+    - Do not invent commands, assume a profile, or create configuration automatically
+    - If no useful check is discoverable, report that limit or ask for the missing command
+- An unreadable or invalid configuration is not absent configuration. Report it and stop work that depends on it; do not bypass its gates
+- Legacy, conflicting, or invalid project-data resolution also requires the reported repair, not an unconfigured fallback. Orphan warnings alone do not block work
+- Offer `/acstack:setup` when the user wants saved project settings or storage-backed features such as maps, living specs, or configured browser verification; do not require it for general work
 
 Key fields:
 
@@ -390,7 +398,7 @@ Read-only reviewers report discrepancies to the completion owner.
 
 The verification owner gathers evidence for the final revision. Opening a PR does not require running every test locally.
 
-Read `<project folder>/project.yaml` for the available commands and inspect the project's CI configuration before relying on it:
+Use `<project folder>/project.yaml` when present, otherwise discover commands under Project configuration above. Inspect the project's CI configuration before relying on it:
 
 1. Use focused local checks by default: cover changed behavior, affected callers, and relevant integration paths
 2. Run applicable build, lint, and typecheck checks; scope them when the tooling supports it

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

@@ -9,17 +9,21 @@ keep-coding-instructions: true
 <!-- acstack:communication:start -->
 Use the fewest clear words that preserve all necessary information.
 
-## Answer the reader's question
+## Fit the answer to the audience
 
-- 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
+- Start with what the reader knows, what they do not know, and what they need from this answer
+    - Lead with the answer, recommendation, or result they need
+    - Include only the context needed to understand it and act; repeat known information only when necessary to connect the new information
+    - Omit a detail only when it does not affect the reader's understanding, decision, or next action
+    - If unsure whether a detail matters, include its essential point briefly rather than relying on the reader to ask
+- When reporting information to the user, be extremely concise and sacrifice grammar for sake of concision
+    - A headline or three-word answer is enough when it fully answers the question
+    - Use fragments freely; skip introductions, recaps, and supporting detail the user does not need
+    - Shorten wording, not meaning; keep conditions and ownership clear
+- Match completeness to the audience, not a length target
+    - An agent handoff needs every detail required to continue correctly, without padding
+    - A durable document needs enough context and precise wording to stand alone for its intended reader; chat's grammar shortcuts do not apply
+- Preserve necessary qualifications, evidence, errors, security warnings, accessibility requirements, and destructive-action confirmations; concision never overrides required disclosures
 - Separate the current answer from decision history
     - State what applies now before explaining how the decision changed
 
@@ -51,7 +55,7 @@ Use the fewest clear words that preserve all necessary information.
 
 ## Write in plain language
 
-- Prefer common, concrete words and natural word order
+- Prefer common, concrete words; use natural word order when it helps understanding
     - 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
@@ -63,20 +67,24 @@ Use the fewest clear words that preserve all necessary information.
     - 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
+    - Include sources, checks run, results, and uncertainty when the reader needs them to judge the claim or act
+    - Keep verification rigorous even when its supporting detail stays out of the report
     - 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
+- Use straight quotes and three periods for an ellipsis; use the Oxford comma in durable prose
+- Prefer parentheses over spaced en dashes for asides; use a period for a separate thought, never an em dash
+    - Use short parenthetical clarifications or examples (e.g., a concrete input) when they make something complex or ambiguous easier to understand
 - 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
+    - Keep list items parallel in meaning; in durable prose, also use parallel grammar and consistent punctuation
     - Short bullet fragments need no final period
 
 ## Before you send
 
-- Can the reader find the answer without reading every detail?
+- Does this give the reader exactly what they need, given what they already know?
+- Can a headline alone answer the question? If so, stop there.
+- Have you removed unnecessary detail without hiding anything that could change the reader's understanding, decision, or next action?
 - 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?