acstack 0.0.0-stage → 0.47.1

package/skills/setup/report.md

@@ -0,0 +1,68 @@
+# Setup: report
+
+`SKILL.md` decides when to read this file: every run ends at Step 14, and it runs from here.
+
+## Step 14: Report
+
+Run the health check one last time, then report what stands:
+
+```
+## ACStack setup
+
+Profile:      [profile]
+Source:       [source dir]
+Tests:        [tests dir]
+Grilling:     [question tool/inline prose]
+TDD:          [strict/relaxed]
+Orchestrator: [strict/relaxed]
+Spec sync:    [enabled/disabled]
+Frontend:     [configured/not configured]
+Browser:      [project's preferred mode / not configured]
+Design:       [on / off / not asked]
+Host:         [orchestrators + browser modes declared / not declared]
+Workspace:    [yes / yes, n updates available / not installed / declined / not asked]
+Config:       acstack/project.yaml
+Domain map:   acstack/domain-map.yaml ([n] domains / starter – fill in)
+Output style: acstack:ac-writing-style (global) | (project) | not set
+
+Health check: [n] pass, [n] fail, [n] info
+
+Next: describe what you want to build, or run /acstack:bootstrap for existing code.
+```
+
+Fill the `Host:` line and the `Orchestrator:` line from two different sources.
+`Orchestrator:` is this project's delegation policy, read from
+`workflow.tdd.orchestrator_strict` in `acstack/project.yaml`. It says whether
+the coordinator may write code itself. `Host:` is about the machine. It names
+which tool owns terminal panes and git worktrees, and which browser modes work
+here.
+
+The `host` skill declares both, and the global config holds them.
+
+Fill `Workspace:` from `host.terminal_workspace`: `yes` on `true`, `declined` on
+`false`, and `not asked` when it is unset.
+
+The key records the answer, never the install. Setup writes it before anyone
+runs the installer, so `yes` never claims this machine has the workspace. When
+Step 12 asked in this run and the user said Yes, write `yes – run
+/acstack:terminal-workspace` so the owed command stays on screen.
+
+Two rows come from what `outdated` found in Step 12. Write `yes, n updates
+available` when it reported stale or new components, with `n` as the number of
+findings. Write `not installed` when it reported a `missing` row and the user
+declined to install it.
+
+Fill `Design:` from `workflow.design_review` and the `impeccable` row together:
+
+- `on` when the key is `true` and the row is there
+- `on – install open-designer and impeccable` when the key is `true` and no row
+  is there
+
+- `off` when the key is `false`
+- `not asked` when the key states nothing, or the project has no frontend
+
+That key records the answer too, never the install. The `impeccable` row is the
+only thing here that reports what the machine has, so `on` alone never claims a
+plugin the user has yet to install.
+
+List every row still failing under the summary. Name the row and what it needs.

package/skills/setup/row-fixes.md

@@ -0,0 +1,196 @@
+# Setup: row fixes
+
+`SKILL.md` decides when to read this file: Step 9 is fixing a `browser-mode:<mode>`, `frontend-verification`, `domain-map`, `agent-browser`, `agent-browser-json`, `verification-knowledge` or `output-style` row.
+
+Five rows describe the machine: `required-axis`, `orchestrator`, `browser-mode`,
+`preferred-browser-mode` and `optional-axis`. Invoke the `host` skill for each of
+them, with one exception: `optional-axis:host.terminal_workspace` is Step 12's
+question, and the `host` skill never asks it. It is safe to re-run, and it starts from the current answers.
+
+A `preferred-browser-mode` row is the exception. It goes to the `host` skill only
+on a `fail`, and to Step 10 on an `info`.
+
+One row has second fixes: `browser-mode:<mode>`. Which one applies depends on the
+mode, and for two of the three modes the `host` skill is no fix at all.
+
+A `browser-mode:remote` failure says the machine declares the remote mode and
+nothing answered on the port. If the machine really does drive a browser that
+way, the bridge is down, so run Step 11. If it does not, the axis is wrong, so
+run the `host` skill.
+
+A `browser-mode:headless` or `browser-mode:local` failure says one thing and
+nothing else: the machine declares the mode and no Chromium or Chrome binary sits
+on PATH. The axis is right and the machine is short a browser. Re-running the
+host interview changes nothing here, and answering the axis false records a lie
+about what this machine can do.
+
+Offer to install the browser instead:
+
+```bash
+sudo apt install chromium-browser   # Ubuntu/Debian
+sudo dnf install chromium           # Fedora
+```
+
+Then re-run the health check from Step 7. The row passes once the binary is on
+PATH.
+
+A `frontend-verification` row needs no step of its own. The project configures a
+frontend and has not turned browser verification on. Turn it on:
+
+```bash
+~/.claude/acstack/bin/acstack config set workflow.frontend_verification true
+```
+
+`docs/config-reference.md` documents the key.
+
+### 9a. Generate the domain map
+
+`acstack/domain-map.yaml` maps source paths to spec domains. Spec sync,
+`/acstack:archive`, `/acstack:bootstrap` and `/acstack:pre-commit-review` all
+read it. Without it, every path through spec sync skips in silence, and the
+living specs never update.
+
+Launch an **Explore subagent** over `directories.source` to propose domains. Ask
+it for the top-level functional areas. Ask for a kebab-case name, the paths that
+belong to it, and one line saying what it owns.
+
+Guidance for the subagent:
+
+- Group by responsibility, not by layer. Use `auth`, `billing` and `search`,
+  never `models`, `controllers` and `utils`.
+
+- Prefer a directory prefix over a file list. Consumers match a path as a prefix.
+- Aim for 3 to 10 domains. Fewer, and spec sync cannot tell two changes apart.
+  More, and every commit touches several.
+
+- Leave tests, config, build files and docs unmapped. Consumers skip a path that
+  no domain covers.
+
+If `acstack/specs/` already holds domain directories, propose those names first
+and map the paths onto them. Renaming a domain here orphans its `spec.md`.
+
+Print the proposal and confirm it with the question tool (AskUserQuestion on Claude Code). Ask "Use this domain map,
+or adjust it?" and offer "Use it" against "Adjust (I'll give feedback)".
+
+Then write the file:
+
+```yaml
+# Domain Map: maps source paths to spec domains
+# Read by spec sync, /acstack:archive, /acstack:bootstrap
+
+domains:
+  <domain-name>:
+    paths:
+      - <path prefix>
+    description: <what this domain owns>
+```
+
+A greenfield project has no code to group. Say so, write the header with one
+commented example under `domains:`, and invent nothing. Tell the user to fill it
+in, or to run `/acstack:setup` again once there is code to map.
+
+### 9b. Install the browser driver
+
+`agent-browser` is the command line tool the frontend verifier drives a browser
+with. Offer to install it:
+
+```bash
+npm install -g agent-browser
+```
+
+### 9c. Write agent-browser.json
+
+This file tells `agent-browser` which port to dial. Write it in the project root:
+
+```json
+{"cdp": "<cdp_port>"}
+```
+
+Take `<cdp_port>` from `frontend.browser.cdp_port` in `acstack/project.yaml`. With
+no value there, the default is `19988` under `mode: remote` and `9555` otherwise.
+The row fails when the two files name different ports, so change one of them.
+
+### 9d. Create the knowledge base for verification
+
+The frontend verifier keeps what it learns in `VERIFICATION-KNOWLEDGE.md`, under
+the directory `frontend.helpers_dir` names. If that key states nothing, ask for a
+directory and write the key first. Then create the file:
+
+```markdown
+# Verification Knowledge Base
+
+Evolving reference for browser-based verification. Updated by the frontend-verifier agent after each run.
+
+## URL Patterns
+
+<!-- Add URL patterns and routing rules here -->
+
+## Element Patterns
+
+<!-- Add stable element identifiers discovered during testing.
+     Prefer data-testid attributes – they survive refactors.
+     Record the accessible name/role from agent-browser snapshots. -->
+
+## Gotchas & Lessons Learned
+
+<!-- Add issues and workarounds discovered during testing -->
+
+## Proven Verification Sequences
+
+<!-- Add step sequences that work reliably.
+     Example: "To verify login: open /login, snapshot, fill @username, fill @password, click @submit, wait 2s, snapshot again, check for dashboard heading" -->
+```
+
+### 9e. Offer the writing output style
+
+The plugin ships an output style. Claude Code names it `acstack:ac-writing-style`.
+It applies the `writing` skill's plain-language rules to every chat reply.
+
+Offer it. Never set it without asking.
+
+The row's message names which of the three settings files selects a style, and
+which style it selects. `.claude/settings.local.json` wins over
+`.claude/settings.json`, which wins over `~/.claude/settings.json`.
+
+Ask once:
+
+```json
+{
+  "question": "Apply the acstack:ac-writing-style output style?",
+  "options": [
+    {"label": "Global (recommended)", "description": "Write outputStyle into ~/.claude/settings.json, so it applies in every project"},
+    {"label": "This project only", "description": "Write outputStyle into .claude/settings.local.json, which overrides the global value here"},
+    {"label": "Skip", "description": "Leave the output style as it is"}
+  ]
+}
+```
+
+Load the chosen file as JSON, set the one key, then write it back. Use `python3`
+or `jq`. Never edit the file with a regular expression, because that corrupts the
+other keys.
+
+Stop and report a file holding malformed JSON. Do not overwrite it.
+
+```bash
+python3 - <<'PY'
+import json, pathlib, sys
+f = pathlib.Path("~/.claude/settings.json").expanduser()   # or .claude/settings.local.json
+f.parent.mkdir(parents=True, exist_ok=True)
+try:
+    data = json.loads(f.read_text()) if f.exists() else {}
+except json.JSONDecodeError:
+    sys.exit(f"{f}: malformed JSON, aborting")
+data["outputStyle"] = "acstack:ac-writing-style"
+f.write_text(json.dumps(data, indent=2) + "\n")
+PY
+```
+
+If the user chose global and a project file also sets `outputStyle`, say so. The
+project value overrides the global one, so offer to remove that key.
+
+Tell the user the style applies after `/clear`, or in a new session. Say that
+`/config` -> Output style writes project scope only, which is why this step
+offers the global path. Source: https://code.claude.com/docs/en/output-styles.md.
+
+Claude Code has no command line flag for this. `claude config` does not exist,
+and Claude Code dropped the `/output-style` command. Do not invent either.

package/skills/setup/terminal-workspace.md

@@ -0,0 +1,153 @@
+# Setup: terminal workspace
+
+`SKILL.md` decides when to read this file: every run reaches Step 12, and it runs from here.
+
+## Step 12: Offer the terminal workspace
+
+The terminal workspace runs several coding agents side by side in one terminal,
+on a machine the user reaches over the network. It installs herdr and the tools
+that read diffs, pull requests and files around it.
+
+ACStack needs none of it, so this step offers and never assumes.
+
+Read what this machine already decided:
+
+```bash
+~/.claude/acstack/bin/acstack config get host.terminal_workspace
+```
+
+On exit 0 the user has already answered. Read which way it went:
+
+- On `false`, say nothing and go to Step 13
+- On `true`, check whether the workspace on this machine has fallen behind
+
+```bash
+PLUGIN=$(dirname "$(dirname "$(dirname "$(readlink -f ~/.claude/acstack/bin/acstack)")")")
+SETUP="$PLUGIN/assets/terminal-workspace/setup.sh"
+bash "$SETUP" outdated
+```
+
+Resolve the script rather than guessing its path. The SessionStart hook
+repoints that CLI symlink at every start, so it names the newest installed
+version. The `terminal-workspace` skill resolves the same script the same
+way.
+
+If the file is not there, say nothing and go to Step 13.
+
+Act on what `outdated` returned:
+
+- **Exit 0** – nothing has moved on. Say nothing and go to Step 13
+- **Exit 2** – it cannot tell. Say one line naming why, then go to Step 13
+- **Exit 1** – there is something to do. Show the findings verbatim, one per line, then ask once
+
+A user deciding whether to spend two minutes on downloads needs to see what the
+findings are.
+
+Exit 1 with no tab-separated row is an older script printing its usage for a
+subcommand it does not know. Say nothing and go to Step 13.
+
+The findings decide which question to ask. A `missing` row means this machine
+never installed the workspace, and it takes the first question. Everything else
+takes the second.
+
+On a `missing` row:
+
+```json
+{
+  "question": "You said yes but the workspace was never installed here. Install it?",
+  "header": "Workspace",
+  "options": [
+    {"label": "Yes", "description": "You then run /acstack:terminal-workspace, which installs herdr and the tools around it: several agents side by side in one terminal, sessions that survive a disconnect, and diffs, pull requests and files on one key each. Twelve components, every one reversible."},
+    {"label": "No", "description": "Leave this machine as it is. Nothing in ACStack needs the workspace, and the offer comes back next time you run setup."}
+  ]
+}
+```
+
+On **Yes**, print this line and go to Step 13:
+
+```
+Run /acstack:terminal-workspace – the installer is reserved for you to start.
+```
+
+On any other finding:
+
+```json
+{
+  "question": "The terminal workspace has updates. Fetch them?",
+  "header": "Workspace",
+  "options": [
+    {"label": "Yes", "description": "You then run /acstack:terminal-workspace upgrade, which reinstalls each stale tool and adds any new component's config block to your file."},
+    {"label": "No", "description": "Leave this machine as it is. Everything installed keeps working, and the offer comes back next time you run setup."}
+  ]
+}
+```
+
+On **Yes**, print this line and go to Step 13:
+
+```
+Run /acstack:terminal-workspace upgrade – the installer is reserved for you to start.
+```
+
+Never run `upgrade` or `apply` yourself. Both install binaries and write the
+user's config, which is the work the `terminal-workspace` skill owns. Running
+`outdated` here is fine, because it only reads.
+
+On **No**, go straight to Step 13 and record nothing. The next version may add
+another component, so a "never ask" flag would silence a question nobody has
+asked the user yet.
+
+On any exit other than 0 or 2 the CLI is older than this skill and does not know
+the key. Do not ask, and do not try to write the key. Say this instead, then go
+to Step 13:
+
+```
+The acstack CLI on this machine predates host.terminal_workspace, so I cannot
+record an answer. Restart your agent session to relink the CLI, then run
+/acstack:setup again.
+```
+
+The SessionStart hook repoints `~/.claude/acstack/bin/acstack` at every start,
+so a restart is the whole fix. This only happens when a plugin update lands
+mid-session.
+
+On exit 2 nobody has answered yet. Ask once:
+
+```json
+{
+  "question": "Set up the terminal workspace on this machine?",
+  "header": "Workspace",
+  "options": [
+    {"label": "Yes", "description": "You then run /acstack:terminal-workspace, which installs herdr and the tools around it: several agents side by side in one terminal, sessions that survive a disconnect, and diffs, pull requests and files on one key each. Twelve components, every one reversible."},
+    {"label": "No", "description": "Leave this machine as it is. Nothing in ACStack needs the workspace, and /acstack:terminal-workspace installs it any time later."}
+  ]
+}
+```
+
+Write the answer, whichever way it went:
+
+```bash
+~/.claude/acstack/bin/acstack config set host.terminal_workspace true   # or false
+```
+
+Write it before doing anything else. The answer is the user's, and an installer
+they never get round to running must not bring the question back on the next
+project.
+
+On **Yes**, hand the install to the user. The `terminal-workspace` skill sets
+`disable-model-invocation: true`, so the host refuses every attempt to
+call it from here. Print this line, then go to Step 13:
+
+```
+Recorded. Run /acstack:terminal-workspace to install it – the installer is
+reserved for you to start.
+```
+
+Never replicate that skill's steps by hand. It installs binaries and writes one
+config file, and a second writer of those files collides with it.
+
+On **No**, go straight to Step 13. Name `/acstack:terminal-workspace` once, and
+do not ask again.
+
+This step is the only place that asks the axis. The `host` skill owns every
+other `host.*` question, and leaves this one here. The workspace installs
+binaries, so the offer belongs after the project works.

package/skills/sync/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: sync
+description: Update living specs in acstack/specs/ from recent code changes. Called automatically by /commit for retroactive spec updates. Can also be invoked manually.
+argument-hint: "[file-paths or 'staged']"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+This skill analyzes code changes. It updates the cumulative living specs in
+`acstack/specs/` to reflect what changed. It is the "fast path" mechanism
+that keeps specs current even when a workflow skips full spec planning.
+
+## Step 1: determine change scope
+
+1. If `$ARGUMENTS` is "staged", or `/commit` calls this skill, use `git diff --cached`
+2. If `$ARGUMENTS` contains file paths: Diff those files against HEAD
+3. If no arguments: Use `git diff HEAD` (staged + unstaged)
+
+Extract from the diff: files added/modified/deleted, functions/classes changed.
+
+## Step 2: refresh DESIGN.md
+
+`DESIGN.md` at the repo root records the project's design tokens. The
+`impeccable document` command writes that file from the code. A **token
+source** is a file that defines those tokens, meaning CSS custom properties or
+a Tailwind theme.
+
+This step runs before Step 3. Step 3 exits early when the diff touches no
+domain, and a token source such as `app/globals.css` usually sits outside every
+domain.
+
+1. Run `~/.claude/acstack/bin/acstack design-gate`
+    - It prints `on` and exits 0 when the design gate is on
+    - It prints `off: <reason>` and exits 1 when the gate is off
+    - Skip the whole step on a non-zero exit
+2. Check for `DESIGN.md` at the repo root
+    - Skip the whole step when the file is missing
+    - Sync never creates `DESIGN.md` – the open-designer plugin writes it
+3. Look for a token source in the diff Step 1 chose
+
+    A token source is exactly one of these four, matching what `impeccable
+    document` scans:
+
+    - a CSS file whose diff adds or changes a line holding `--color-`,
+      `--font-`, `--spacing-`, `--radius-`, `--shadow-`, `--ease-` or
+      `--duration-`
+    - a Tailwind config: `tailwind.config.js`, `tailwind.config.ts` or
+      `tailwind.config.mjs`
+    - a CSS-in-JS theme file: `theme.ts`, `theme.js`, `tokens.ts` or `tokens.js`
+    - a token file: `tokens.json` or `design-tokens.json`
+
+    Grep the diff for the CSS-property case:
+
+    ```bash
+    git diff --cached -U0 -- '*.css' | grep -E '^[+-].*--(color|font|spacing|radius|shadow|ease|duration)-'
+    ```
+
+    Match the diff command to what Step 1 chose. Use `git diff HEAD -U0`
+    instead when Step 1 picked `git diff HEAD`.
+
+    Skip the whole step when the diff holds no token source.
+
+4. Run the `/impeccable document` slash command
+
+    `document` is a slash-command playbook, not a command-line verb.
+
+    The playbook finds `DESIGN.md` and stops. It asks whether to refresh,
+    overwrite, or merge. Answer refresh every time.
+
+    Do not call the question tool. Do not ask the user. The code is the only
+    source of truth for design tokens.
+
+5. Stage what `document` wrote
+
+    `document` writes `DESIGN.md` and `.impeccable/design.json`. Stage both
+    with the commit, the same way this skill stages an updated spec file.
+
+## Step 3: map changes to domains
+
+1. Read `acstack/domain-map.yaml`
+2. Match changed files against domain path patterns
+3. Group changes by domain
+4. Skip files outside all domains (tests, config, docs)
+
+If the diff affects no domains, report "No spec-relevant changes". Then exit.
+
+## Step 4: generate lightweight deltas
+
+For each affected domain:
+
+1. Read `acstack/specs/[domain]/spec.md` (if it exists)
+2. Analyze changes:
+    - New functions/endpoints/components -> ADDED requirements
+    - Modified signatures or behavior -> MODIFIED requirements
+    - Deleted functions/endpoints -> REMOVED requirements
+
+Write each functional requirement (FR) entry per the `writing` skill.
+
+**Example**
+
+```markdown
+### FR-014: The handoff anchor loads once
+
+- **Description**: The SessionStart hook injects `acstack/HANDOFF.md` after a
+  compaction, then moves the file into `acstack/handoffs/`.
+- **Behavior**: Given `acstack/HANDOFF.md` carries the `acstack_handoff`
+  marker, When a session starts with source `compact`, Then the hook injects
+  the file and retires it.
+- **Source**: `hooks/session-start-handoff.sh`
+```
+
+## Step 5: apply deltas
+
+For each affected domain:
+
+- If the spec exists, merge ADDED/MODIFIED/REMOVED into it
+- If no spec exists, create a minimal spec with ADDED entries and a comment:
+  `<!-- Auto-generated from code changes. Run /bootstrap for full spec. -->`
+
+Write each merged FR per the `writing` skill.
+
+## Step 6: glossary check
+
+Glossaries live in `CONTEXT.md` at the repo root (cross-domain terms) and
+`acstack/specs/[domain]/CONTEXT.md` (domain terms). If neither exists, skip.
+
+For each glossary term, check the diff. Look for a renamed or deleted
+identifier that matches it: function, class, table, config key, route. If
+so, surface it in the report:
+
+```
+Glossary: 'ticket' may be stale – the diff renames Ticket to WorkItem
+```
+
+Never edit the glossary. Never block the commit.
+
+For specs, the code wins. For the glossary, the human wins. The glossary
+records vocabulary that humans agreed on, so only a human decision changes
+it.
+
+This check only surfaces the drift.
+
+## Step 7: report
+
+```
+Spec sync: [N] domains updated
+  - domain-a: +2 added, ~1 modified
+  - domain-b: +1 added, -1 removed
+```
+
+## Integration with /commit
+
+When `/commit` calls this skill:
+
+1. Receives the staged diff as context
+2. Runs silently (no user prompts)
+3. Returns a list of modified spec files for staging
+4. Adds `DESIGN.md` and `.impeccable/design.json` when Step 2 refreshed them
+5. Outputs minimal detail so it does not interrupt the commit flow
+
+## Spec correction (fix it when you see it)
+
+While reading existing specs to generate deltas, if you notice ANY existing FR that contradicts the code in the diff, fix it immediately.