acstack 0.0.0-stage → 0.47.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "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.47.1",
+  "author": {
+    "name": "ac8318740"
+  },
+  "repository": "https://github.com/ac8318740/spechub",
+  "license": "MIT",
+  "keywords": [
+    "tdd",
+    "acstack",
+    "agentic-coding",
+    "testing",
+    "orchestrator",
+    "workflow",
+    "modular"
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ac8318740
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,390 @@
-# Temporary Holding Version
+# ACStack
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ACStack is an agentic coding stack. It makes coding agents plan before they code, write tests before implementation, and keep docs matching the code.
+
+- **ACStack aims to solve two common failure modes coding agents introduce**
+    - The agent starts building before the requirements are clear
+    - The agent writes code, then creates tests that pass against that code
+- **ACStack has first-class support for Claude Code and pi**
+    - Claude Code installs it as a plugin
+    - pi installs it as an npm package
+- **ACStack introduces structure around how your agent works**
+    - Every change goes through a test-writer, an implementer, and a checker
+    - Every commit updates your specs from the diff
+- **Downside: this structure may make your agent take longer on small tweaks than necessary**
+
+```mermaid
+flowchart TD
+    Q{"What kind of<br/>request is this?"} -->|"clear enough to build"| IM["Build it<br/>(/acstack:implement)"]
+    Q -->|"something stopped working"| QF["Find the root cause first<br/>(/acstack:quick-fix)"]
+    Q -->|"still has open questions"| MP["Answer them first<br/>(/acstack:map)"]
+    MP -->|"once the questions are answered"| IM
+    IM --> C["Commit, and update the docs<br/>(/acstack:commit)"]
+    QF --> C
+```
+
+Every box above is section 2. The rest of this file is reference.
+
+| What you want | Where |
+| ------------- | ----- |
+| Quickstart | section 1 |
+| The three commands, and which one to use | section 2 |
+| Configure a project and a machine | section 3 |
+| The CLI | section 4 |
+| Every skill | section 5 |
+| Every agent | section 6 |
+| Output style | section 7 |
+| Terminal workspace | section 8 |
+| Design principles | section 9 |
+| Licence and credits | section 10 |
+
+## 1. Quickstart
+
+ACStack has first-class support for [Claude Code](https://claude.com/claude-code) and [pi](https://pi.dev).
+
+### 1.1. Install on Claude Code
+
+You need the Claude Code CLI and Node.js 20 or later.
+
+Install the plugin:
+
+```
+/plugin marketplace add ac8318740/spechub
+/plugin install acstack@spechub
+```
+
+Then, in your project:
+
+```
+/acstack:setup
+```
+
+- `/acstack:setup` detects the project type, then writes `acstack/project.yaml` with workflow settings
+- The SessionStart hook loads the orchestrator instructions whenever it detects an ACStack project
+- 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))
+
+### 1.2. Install on pi
+
+*The same project installs as a [pi](https://pi.dev) package. Subagents come from the `pi-subagents` package.*
+
+```
+pi install npm:pi-subagents
+pi install npm:acstack
+```
+
+Then, in your project, run `/acstack:setup`.
+
+- Every skill runs under the same name as on Claude Code, e.g. `/acstack:map`
+    - `/acstack map` does the same
+    - Both always run the ACStack skill, even when another pi package has a skill called `map`
+- ACStack's skills deliberately don't appear as `/skill:<name>` commands
+    - The package gives pi no skills, so `/skill:map` never runs ACStack's map
+    - 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 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
+        - Continuity keeps useful working context in the same session, using billion-context or host ACP compression when available
+        - Freshness uses `/acstack:handoff` when a fresh window or independent read helps more
+        - With no thresholds set, the first nudge comes at 200k tokens or half the window, whichever is lower
+        - The urgent nudge comes at 500k tokens or 80% of the window, whichever is lower
+- `pi-subagents` finds the four agents through the `pi.subagents` field in `package.json`
+    - The agents use your `pi-subagents` default model
+    - ACStack warns at session start when `pi-subagents` is missing
+- Allow delegation in `~/.pi/agent/AGENTS.md` – `pi-subagents` only delegates when your request or your instructions allow it:
+
+    ```
+    When an ACStack skill or the ACStack orchestrator says to launch a subagent, you may delegate to it.
+    ```
+
+    - Set `"toolActivation": "eager"` in `~/.pi/agent/extensions/subagent/config.json` to offer the `subagent` tool from the first turn (restart pi after)
+- pi has no output styles, so the writing style is a toggle
+    - Run `/acstack-writing-style on` to add it to every pi session
+    - Run `/acstack-writing-style off` to remove it
+
+## 2. The three commands, and which one to use
+
+*Pick by what is in your way: nothing, a bug, or an unanswered question.*
+
+Two words first, because the third command below uses them.
+
+- **A map** is a to-do graph ACStack keeps for one piece of work
+- **A node** is one entry on that graph: one question to answer, or one piece of work to do
+
+The three commands:
+
+- **The request is clear enough to build** – run `/acstack:implement`
+    - It runs the four agents of section 6 on your request
+    - A one-line change stays a one-line change
+- **Something already built stopped working** – run `/acstack:quick-fix`
+    - It makes the agent find the root cause before it edits anything
+- **The request still has open questions** – run `/acstack:map`
+    - The agent interviews you one round at a time
+    - Each round asks every question it can answer next
+    - Each question comes with the agent's recommended answer
+    - You provide feedback on the agent's recommended answer instead of prompting from scratch
+    - Some requests only need one question
+    - The agent writes that decision down as a short note under `docs/adr/`
+    - A big feature may need dozens of questions
+    - The agent stores those questions as a **map**
+    - You work through the map across several sessions
+
+### 2.1. What a map holds
+
+*`/acstack:map` builds a map only when a single conversation cannot settle every question.*
+
+Each node carries one of five statuses.
+
+| Status | Meaning |
+| ------ | ------- |
+| `fog` | anything you cannot yet articulate clearly |
+| `open` | ready to answer or build |
+| `claimed` | someone is working on it now |
+| `resolved` | done |
+| `out-of-scope` | dropped on purpose |
+
+Each node also records six things.
+
+- **Which earlier answer led to this question**
+    - You can read the decisions back in the order you made them
+- **Which other nodes have to finish before this one starts**
+    - ACStack uses that to tell you what is ready to start
+- **Who answers it**: you, or the agent working alone
+- **What kind it is**: a destination, a standing note, a decision, research, or work
+- **A short name**, which labels the node in a diagram
+- **Where it lives**: a GitHub issue by default, or a markdown file under `acstack/maps/` with no GitHub remote
+
+Almost every node explains itself with a diagram.
+
+- The entry node draws the whole map, and collapses the parts you have finished
+- Every other node draws its own question or its own change
+- A legend sits under each diagram, showing only the symbols that diagram uses
+- On GitHub you click a node in the diagram to open its issue
+
+Two things ACStack does with a finished map.
+
+- **It works through the nodes that are ready to start**, meaning the open ones with nothing unfinished blocking them
+    - ACStack calls that set the **frontier**
+- **It packs the whole map into a single brief**
+    - A fresh agent session picks up where the last one stopped
+
+Every rule in ACStack exists because something went wrong without it, over months of real product development with coding agents.
+
+For the full picture of each step and how they connect, read [docs/workflows.md](docs/workflows.md).
+
+## 3. Configure a project and a machine
+
+*The project states what to run. The machine states what it can do.*
+
+- `acstack/project.yaml` holds every project-scoped setting
+    - [docs/config-reference.md](docs/config-reference.md) gives each key, its values, its default and what changes
+- `~/.config/acstack/config.json` holds the nine `host.*` axes
+    - `/acstack:host` writes eight of them once per machine, and `/acstack:setup` writes the ninth
+    - [docs/dev-setups.md](docs/dev-setups.md) gives every axis, what reads it, and how to describe a fresh machine
+- `/acstack:setup` copies the commands and directories from one of three language profiles
+    - **python** – pytest, ruff, mypy
+    - **node-typescript** – npm test, eslint, tsc
+    - **fullstack-python** – Python backend, plus a Node or TypeScript frontend
+- `acstack config check` audits the project and the machine
+    - It exits 2 when a required host axis has no value
+
+## 4. The CLI
+
+*Four storage operations carry the whole map. One fixed path makes the CLI reachable from any agent session.*
+
+ACStack ships a Node.js CLI: `acstack config`, `acstack list`, `acstack node ...`, and `acstack archive`.
+
+- The storage behind a map provides four operations and nothing more: create, read, update, list
+    - GitHub issues are the default
+        - The first line of every issue body carries all of that node's edges
+        - One call therefore reads the whole map
+        - A sub-issue and an issue dependency mirror those edges, so GitHub's own interface draws the map
+    - Markdown files are the fallback, one per node under `acstack/maps/<name>/`
+- The CLI builds everything else on those four operations
+    - `acstack node frontier` lists what is ready to start now, closest to the original goal first
+    - `acstack node walk` packs the whole map into one brief for a fresh session, in the order the decisions happened
+    - The brief always includes the original goal, plus any node you marked as worth carrying along
+    - `acstack node diagram` draws a map, or any part of one, as a mermaid diagram with a legend under it
+    - The skills claim and resolve a node with `update` calls
+
+Two symlinks reach the CLI. The SessionStart hook maintains both.
+
+- `~/.claude/acstack/bin/acstack` is the fixed path every skill and agent calls
+    - Agents therefore do not depend on your shell `PATH`
+    - The CLI keeps working across plugin version bumps, non-interactive subshells and fresh agent contexts
+- `~/.local/bin/acstack` is for typing `acstack` at a terminal yourself
+    - Add `~/.local/bin` to your `PATH` to use it
+    - The hook prints a one-line reminder when it is absent
+    - Nothing in the plugin breaks without it
+
+If `acstack` does not run after a Claude Code install, read [TROUBLESHOOTING.md](TROUBLESHOOTING.md). A Claude Code session can read it and apply the fix directly.
+
+## 5. Every skill
+
+*Four groups, ordered by when you reach for them.*
+
+### 5.1. Implementation
+
+| Skill | Description |
+|-------|-------------|
+| `/acstack:implement` | Build what is ready to start, running the four agents of section 6, whether or not a map exists |
+
+For work with open decisions, chart it with `/acstack:map` first.
+
+### 5.2. Planning
+
+| Skill | Description |
+|-------|-------------|
+| `/acstack:map` | Answer the open questions first, building the to-do graph on the first run and working through it after |
+| `grilling` | The interview itself, asking every question it can answer next per round, each with a recommended answer (the agent invokes it) |
+| `record-context` | Writes a decision down when one lands: a short note, a glossary term, both, or neither (the agent invokes it) |
+
+### 5.3. Operations
+
+| Skill | Description |
+|-------|-------------|
+| `/acstack:commit` | Commit, and update the specs under `acstack/specs/` from the diff first |
+| `/acstack:archive` | Close a finished map, after checking the decisions reached your specs and notes, then delete the nodes |
+| `/acstack:sync` | Update the specs from code changes, outside a commit |
+| `/acstack:handoff` | Hand work to a visible agent, a new one in its own pane or one already running, with acknowledgement |
+| `/acstack:compact-and-continue` | Anchor the session's load-bearing state to survive compaction, then continue in place |
+
+What an effort leaves behind is what matters: updated specs, decision notes, and glossary entries. ACStack throws the nodes away.
+
+### 5.4. Setup and supporting
+
+| Skill | Description |
+|-------|-------------|
+| `/acstack:setup` | Set up ACStack in a project, and change how a project already set up is configured |
+| `/acstack:host` | Declare this machine's dev setup once, as the `host.*` axes |
+| `/acstack:bootstrap` | Write the first set of specs by reading your existing code |
+| `/acstack:explore` | Thinking partner mode, read-only |
+| `/acstack:quick-fix` | Structured bug fix workflow with root cause analysis |
+| `/acstack:pre-commit-review` | Deep quality review of all changes since last commit |
+| `/acstack:test-conventions` | Test placement rules and naming conventions |
+| `/acstack:code-review` | Linus Torvalds code philosophy for reviews |
+| `/acstack:browser-verify` | agent-browser command reference, CDP troubleshooting, and selector strategy |
+| `/acstack:bridge` | Set up and operate the Playwriter cross-device browser bridge |
+| `/acstack:visual-docs` | Write docs that lead with a diagram and derive structure from it (Minto pyramid) |
+| `/acstack:new-worktree` | Create a git worktree off the remote base branch and continue the task inside it |
+| `/acstack:teardown-worktree` | Retire finished worktrees and delete their merged local and remote branches |
+| `/acstack:terminal-workspace` | Set up a keyboard-only terminal for driving agents on a dev machine |
+
+## 6. Every agent
+
+*Four agents run in order. The one rule that matters: the test-writer never sees the implementation.*
+
+| Agent | Role |
+|-------|------|
+| `test-writer` | Writes tests from requirements only, before the code under strict TDD and after it under relaxed |
+| `task-executor` | TDD phase 2, making tests pass, and it cannot modify tests |
+| `task-checker` | TDD phase 3, verifying everything: mock skepticism, test baseline, regressions, TDD isolation audit |
+| `frontend-verifier` | TDD phase 4, real browser verification via agent-browser CLI, when `project.yaml` configures a frontend |
+
+- The agent session you talk to coordinates
+    - It hands every piece of research and code to these agents
+- A fail from the task-checker sends the work back to the task-executor with the reason
+- The frontend-verifier runs under three conditions: a configured frontend, changed frontend files, and verification switched on
+
+## 7. Output style
+
+*The plugin ships one output style. It applies the house standard to every chat reply.*
+
+- Claude Code shows the style as `acstack:ac-writing-style`
+- It applies the `writing` skill's plain-language rules and the `visual-docs` skill's Minto pyramid and bullet discipline
+- A reply leads with the answer and puts 90% or more of what follows in bullets
+- Each bullet holds one sentence and ends without a period
+- Sub-bullets nest as far as the point needs, indented four spaces per level
+- Every word has to earn its place: no em dash, no emoji, no puffery, and no contrast clause that does no work
+
+How to turn it on:
+
+- `/acstack:setup` offers the style on both paths
+    - On a new project it comes late
+    - It is optional there
+    - On a project already set up it is a health-check row
+- The skill writes `outputStyle` for you
+- It asks first
+- Use `~/.claude/settings.json` for every project, or `.claude/settings.local.json` for this one
+- A project value overrides the global one
+- The style applies after `/clear`, or in a new session
+- The plugin never forces it on
+
+The style also ships a per-turn reminder:
+
+- `hooks/ac-writing-style-reminder.sh` runs on every prompt and re-injects the style's own words
+- A built-in style carries a `turnReminder` field, and a file-based style cannot, so the hook supplies the equivalent
+- It emits two sections lifted straight out of `output-styles/ac-writing-style.md`
+    - "Who you are", top-level lines only, which is the persona
+    - "Before you send", in full, which is the nine-item checklist
+- It reads those sections at run time, so the reminder can never drift from the style
+- It stays silent under any other output style, and it writes nothing to the transcript
+
+## 8. Terminal workspace for driving several agents
+
+*An optional keyboard-only setup for running several agents on a remote machine. ACStack works fine without it.*
+
+- `/acstack:terminal-workspace` installs every tool and writes every config
+- [docs/terminal-workspace.md](docs/terminal-workspace.md) gives the exact config, every key, and the traps worth knowing
+- The setup builds on herdr, a terminal multiplexer that keeps each agent's terminal running after you disconnect
+    - You attach from your own machine with `herdr --remote`
+    - Your own clipboard and browser then reach the session
+    - Each agent can get its own git worktree, meaning its own checkout on its own branch
+- gh-dash then triages pull requests and diffnav reads diffs, both without leaving the terminal
+
+## 9. Design principles
+
+*Five rules explain why every default is what it is.*
+
+- **Strict TDD holds because of the order the agents run in** – relaxed TDD holds only because the instructions say so
+    - Either way the task-executor cannot edit a test file
+    - Under strict TDD the test-writer runs first
+    - There is no implementation for it to copy
+    - Under relaxed TDD it runs second
+    - Only its instructions stop it reading the code it is testing
+    - The two are not equally safe
+    - That is why strict is the default
+- **Your docs never drift from the code** – `/acstack:commit` reads the diff and updates the specs under `acstack/specs/` in the same commit
+    - Any agent that spots a spec contradicting the code fixes the spec there and then
+    - A spec describes what the code does today
+    - It never describes what someone plans to build
+- **Build no more process than the job needs** – a to-do graph appears only when one conversation cannot hold the questions
+    - A typo fix gets no machinery
+    - A month-long feature gets a map
+    - You type the same command either way
+    - ACStack works out which it is
+- **Planning gets more effort than coding** – three agents read the relevant code before anyone writes a line
+    - Mock audits, regression suites and integration checks follow the implementation
+- **Strict defaults, easy to relax** – run `acstack config set` to change how strict the TDD is, how much the agent does itself, or how it asks you questions
+
+## 10. Licence and credits
+
+*[MIT](LICENSE). Four projects shaped the design.*
+
+- **[OpenSpec](https://github.com/Fission-AI/OpenSpec)** – ACStack forks its CLI from OpenSpec
+    - OpenSpec was the core spec engine under the original workflow
+    - The map-based concepts all originate there: proposals, designs, tasks, living specs, change management, and archiving
+- **[Taskmaster AI](https://github.com/eyaltoledano/claude-task-master)** – Taskmaster's task management model inspired the orchestrator pattern and the agent coordination approach
+- **[Skills for Real Engineers](https://github.com/mattpocock/skills)** by Matt Pocock – the Wayfinder map, the round-by-round interview, and the durability rule for agent briefs
+    - ACStack's node graph is a direct adaptation of Wayfinder
+    - MIT licensed, and recorded in [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)
+- Additional inspiration comes from [Superpowers](https://github.com/obra/superpowers), [GSD](https://github.com/gsd-build/get-shit-done) and [Spec Kit](https://github.com/github/spec-kit)
+
+The optional terminal workspace installs, but does not bundle, the five tools you drive and the five behind them. Each one keeps its own licence.
+
+- [herdr](https://herdr.dev)
+- [tuicr](https://github.com/agavra/tuicr) by agavra, which reviews a pull request inside the terminal
+- [gh-dash](https://github.com/dlvhdr/gh-dash) and [diffnav](https://github.com/dlvhdr/diffnav) by dlvhdr
+- [delta](https://github.com/dandavison/delta) by dandavison
+- [lazygit](https://github.com/jesseduffield/lazygit) by jesseduffield, which stages, commits and pushes on one key
+- [harlequin](https://github.com/tconbeer/harlequin) by tconbeer, the SQL editor this setup opens on one key
+- [yazi](https://github.com/sxyazi/yazi) by sxyazi, the file manager that previews whatever the cursor sits on
+- [mermaid-ascii](https://github.com/AlexanderGrooff/mermaid-ascii) by AlexanderGrooff
+- [glow](https://github.com/charmbracelet/glow) by charmbracelet
+
+The optional fork build of tuicr compiles [agavra/tuicr#607](https://github.com/agavra/tuicr/pull/607) by [antonio2368](https://github.com/antonio2368). It also compiles [agavra/tuicr#633](https://github.com/agavra/tuicr/pull/633) and one counts fix not yet submitted upstream, both written for this fork. That build is off by default and temporary.
+
+See [docs/terminal-workspace.md](docs/terminal-workspace.md).

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,14 @@
+This project includes code derived from OpenSpec CLI, which is licensed under the MIT License.
+
+OpenSpec CLI
+Copyright (c) 2024 OpenSpec Contributors
+https://github.com/Fission-AI/OpenSpec
+License: MIT (https://opensource.org/licenses/MIT)
+
+This project includes concepts and text adapted from Skills for Real Engineers,
+which is licensed under the MIT License.
+
+Skills for Real Engineers
+Copyright (c) 2026 Matt Pocock
+https://github.com/mattpocock/skills
+License: MIT (https://opensource.org/licenses/MIT)

package/TROUBLESHOOTING.md

@@ -0,0 +1,225 @@
+# ACStack troubleshooting
+
+*This page covers the Claude Code install path. pi installs ACStack as `npm:acstack`, and uses pi's package tools instead.*
+
+**A coding agent can act on this file.** Find the symptom the user reported, run the diagnostic, then apply the fix.
+
+- **Claude Code's SessionStart hook maintains everything here**
+    - Almost every symptom below is that hook not having run
+- **Restarting Claude Code fixes most of them**
+    - The hook runs again on the new session
+- **Each section below is one symptom**, with the command to confirm it and the command to fix it
+
+```mermaid
+flowchart LR
+    H["SessionStart hook<br/>(hooks/hooks.json)"] --> A["Agent path<br/>(~/.claude/acstack/bin/acstack)"]
+    H --> U["Human path<br/>(~/.local/bin/acstack)"]
+    A --> C["The bundled CLI<br/>(cli/dist/index.js in the plugin cache)"]
+    U --> C
+    H --> O["Orchestrator instructions<br/>(orchestrator/AGENTS.md, via python3)"]
+```
+
+| The broken link | Sections |
+| --- | --- |
+| Agent path | 1, 4 |
+| Human path | 2 |
+| The bundled CLI | 3 |
+| SessionStart hook | 5 |
+| Orchestrator instructions | 6 |
+
+Where the plugin lives, and what points at it:
+
+- The plugin lives at `${CLAUDE_PLUGIN_ROOT}` once the user installs it via the marketplace
+- On most installs that resolves to `~/.claude/plugins/cache/spechub/acstack/<version>/`
+- `~/.claude/acstack/bin/acstack` is the **agent-facing** invariant path
+    - Every skill and agent in this plugin invokes the CLI through this exact path
+    - It does not depend on the user's `PATH`
+- `~/.local/bin/acstack` is the **human convenience** symlink
+    - It is useful only when `~/.local/bin` is on `PATH`
+    - No plugin functionality rests on it
+- Both symlinks refresh on every SessionStart and point at the current plugin cache version
+- Fix the agent-facing path first
+    - Nothing in the plugin works without it
+
+---
+
+## 1. Agents report `~/.claude/acstack/bin/acstack: No such file or directory`
+
+**Symptom**: a skill or agent fails because it cannot find the CLI at `~/.claude/acstack/bin/acstack`.
+
+**Diagnose**:
+
+```bash
+ls -l ~/.claude/acstack/bin/acstack 2>&1
+ls -d ~/.claude/plugins/cache/spechub/acstack/*/ 2>&1
+```
+
+**Possible causes and fixes**:
+
+- **Symlink missing** (`No such file or directory`): the SessionStart hook never ran
+    - The user has not started Claude Code on this device since they installed the plugin, or the hook silently failed
+    - Fix: ask the user to restart Claude Code so the SessionStart hook fires
+    - The hook creates the symlink and prints `acstack: linked agent CLI at ...`
+    - Create it by hand if that does not work:
+        ```bash
+        ACSTACK_VERSION=$(ls ~/.claude/plugins/cache/spechub/acstack/ | sort -V | tail -1)
+        mkdir -p ~/.claude/acstack/bin
+        ln -sfn ~/.claude/plugins/cache/spechub/acstack/$ACSTACK_VERSION/cli/bin/acstack.js ~/.claude/acstack/bin/acstack
+        ```
+
+- **Plugin cache missing entirely**: the second `ls` returned nothing
+    - Fix: the user has not installed the plugin
+    - Run `/plugin marketplace add ac8318740/spechub`, then `/plugin install acstack@spechub` in Claude Code
+
+---
+
+## 2. `acstack: command not found` (human typed it at a terminal)
+
+**Symptom**: the user runs `acstack --help` at the terminal and the shell reports `command not found`, while agents continue to work.
+
+This is a **human-ergonomics issue, not a plugin issue.** Agents use `~/.claude/acstack/bin/acstack` directly. This does not affect them. Fix it only if the user types `acstack` at terminals.
+
+**Diagnose**:
+
+```bash
+ls -l ~/.local/bin/acstack 2>&1
+echo "PATH=$PATH" | tr ':' '\n' | grep -F "$HOME/.local/bin" || echo "MISSING"
+```
+
+**Possible causes and fixes**:
+
+- **Symlink missing**: the SessionStart hook never ran, or ran and could not write
+    - Fix: ask the user to restart Claude Code
+    - The hook recreates the human symlink on every session start
+- **PATH missing** (the symlink exists but `MISSING` printed): `~/.local/bin` is not on `$PATH`
+    - Fix: add this line to the user's shell rc, then ask them to restart their shell:
+        ```bash
+        export PATH="$HOME/.local/bin:$PATH"
+        ```
+    - The shell rc by shell:
+        - zsh: `~/.zshrc`
+        - bash on Linux: `~/.bashrc`
+        - bash on macOS: `~/.bash_profile`
+        - fish: `~/.config/fish/config.fish`, and use `set -gx PATH $HOME/.local/bin $PATH`
+
+---
+
+## 3. `Error [ERR_MODULE_NOT_FOUND]: Cannot find module '.../cli/dist/index.js'`
+
+**Symptom**: the CLI runs but Node throws `ERR_MODULE_NOT_FOUND` for `dist/index.js`.
+
+**Diagnose**:
+
+```bash
+ACSTACK_VERSION=$(ls ~/.claude/plugins/cache/spechub/acstack/ | sort -V | tail -1)
+ls ~/.claude/plugins/cache/spechub/acstack/$ACSTACK_VERSION/cli/dist/index.js 2>&1
+```
+
+**Cause**: the plugin cache holds a version from before the CLI shipped bundled in the repo, meaning before 0.9.2. This should not happen on 0.9.2 or later.
+
+**Fix**:
+
+- Bump or refresh the plugin cache
+    - Run `/plugin` in Claude Code and reinstall the plugin
+    - Or delete the cache directory and let Claude Code repull:
+        ```bash
+        rm -rf ~/.claude/plugins/cache/spechub/acstack/<old-version>
+        ```
+
+- Confirm the user is on plugin version 0.9.2 or later:
+    ```bash
+    cat ~/.claude/plugins/cache/spechub/acstack/*/.claude-plugin/plugin.json | grep version
+    ```
+
+- Build the CLI in place as a one-shot, if the user is offline or cannot repull:
+    ```bash
+    cd ~/.claude/plugins/cache/spechub/acstack/<version>/cli
+    npm install
+    npm run build
+    ```
+
+---
+
+## 4. Stale symlink, pointing at an old version
+
+**Symptom**: `~/.claude/acstack/bin/acstack --version` prints an older number than expected, or commands behave like an older release.
+
+**Diagnose**:
+
+```bash
+readlink ~/.claude/acstack/bin/acstack
+ls ~/.claude/plugins/cache/spechub/acstack/
+```
+
+**Cause**: an older session set the symlink target. The plugin cache now holds a newer version. The SessionStart hook has not relinked it yet.
+
+**Fix**:
+
+- Start a new Claude Code session
+    - The SessionStart hook detects a stale symlink and relinks it, printing `acstack: updated agent CLI at ...`
+- Or relink by hand:
+    ```bash
+    NEW=$(ls ~/.claude/plugins/cache/spechub/acstack/ | sort -V | tail -1)
+    ln -sfn ~/.claude/plugins/cache/spechub/acstack/$NEW/cli/bin/acstack.js ~/.claude/acstack/bin/acstack
+    ln -sfn ~/.claude/plugins/cache/spechub/acstack/$NEW/cli/bin/acstack.js ~/.local/bin/acstack
+    ```
+
+---
+
+## 5. The SessionStart hook did not run
+
+**Symptom**: no `acstack:` lines appear in Claude Code's startup logs. `~/.claude/acstack/bin/acstack` is missing.
+
+**Diagnose**:
+
+```bash
+cat ~/.claude/plugins/cache/spechub/acstack/*/hooks/hooks.json
+```
+
+**Cause**: the user has not enabled the plugin, or they have disabled hook execution in their Claude Code settings.
+
+**Fix**:
+
+- Confirm the user has enabled the plugin, with `/plugin list`
+- Check that the user has not disabled hooks in `~/.claude/settings.json`, meaning no `"hooks": false` and no per-event suppression
+- Install the symlinks by hand as a fallback, using the commands in section 1 and section 4
+
+---
+
+## 6. `python3 not found` warning at session start
+
+**Symptom**: the hook prints `acstack: python3 not found; skipping orchestrator injection`.
+
+**Cause**: the hook uses `python3` to emit `orchestrator/AGENTS.md` as JSON for `additionalContext` injection.
+
+- Without `python3` the orchestrator instructions do not load at all
+    - Nothing else reads that file
+- Claude Code does not auto-load instructions from a plugin's own directory
+    - Injection is the only path
+- This does not affect the CLI symlinks
+    - The `acstack` command keeps working
+
+**Fix**: install Python 3. Most systems already have it.
+
+```bash
+# Debian/Ubuntu
+sudo apt install python3
+# macOS
+brew install python3
+```
+
+---
+
+## 7. When none of the above matches
+
+*This section describes the document, not the plugin. No box in the diagram holds it.*
+
+The CLI is a normal Node.js ESM package. To validate the install end to end:
+
+```bash
+ACSTACK_VERSION=$(ls ~/.claude/plugins/cache/spechub/acstack/ | sort -V | tail -1)
+node ~/.claude/plugins/cache/spechub/acstack/$ACSTACK_VERSION/cli/bin/acstack.js --help
+```
+
+- If that prints help, the CLI is fine and the issue is the symlink
+- If that errors, the issue is the cache contents (see section 3)