acstack 0.0.0-stage → 0.47.0

package/profiles/fullstack-python.yaml

@@ -0,0 +1,29 @@
+# Fullstack Python (backend) + Node/TS (frontend) profile for acstack
+# Used by /acstack:setup to generate acstack/project.yaml
+
+commands:
+  test: "pytest tests/ --tb=short -x"
+  test_collect: "pytest tests/ --co -q 2>/dev/null | tail -1 | grep -oP '\\d+'"
+  build: null
+  lint: "ruff check --fix"
+  typecheck: null
+  format: "ruff format"
+
+directories:
+  source: "src/"
+  tests: "tests/"
+
+test_markers:
+  exclude: "slow,integration"
+
+venv:
+  activate: "source .venv/bin/activate"
+
+frontend:
+  directory: "frontend/"
+  dev_server_url: "http://localhost:3000"
+  dev_server_check: "curl -s -o /dev/null -w '%{http_code}' http://localhost:3000"
+  commands:
+    build: "npx tsc --noEmit"
+    lint: "npm run lint -- --fix"
+    test: "npm test"

package/profiles/node-typescript.yaml

@@ -0,0 +1,23 @@
+# Node/TypeScript project profile for acstack
+# Used by /acstack:setup to generate acstack/project.yaml
+
+commands:
+  test: "npm test"
+  test_collect: null
+  build: "npm run build"
+  lint: "npm run lint -- --fix"
+  typecheck: "npx tsc --noEmit"
+  format: "npx prettier --write ."
+
+directories:
+  source: "src/"
+  tests: "tests/"
+
+test_markers:
+  exclude: null
+
+venv: null
+
+frontend:
+  dev_server_url: "http://localhost:3000"
+  dev_server_check: "curl -s -o /dev/null -w '%{http_code}' http://localhost:3000"

package/profiles/python.yaml

@@ -0,0 +1,24 @@
+# Python project profile for acstack
+# Used by /acstack:setup to generate acstack/project.yaml
+
+commands:
+  test: "pytest tests/ --tb=short -x"
+  test_collect: "pytest tests/ --co -q 2>/dev/null | tail -1 | grep -oP '\\d+'"
+  build: null
+  lint: "ruff check --fix"
+  typecheck: "mypy ."
+  format: "ruff format"
+
+directories:
+  source: "src/"
+  tests: "tests/"
+
+test_markers:
+  # Markers to exclude from default test runs (comma-separated for pytest -m)
+  exclude: "slow,integration"
+
+venv:
+  # If set, commands are prefixed with activation
+  activate: "source .venv/bin/activate"
+
+frontend: null

package/skills/archive/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: archive
+description: Close out a cleared map – one whose frontier is empty with no fog and no claims left – by verifying the durable residue, meaning what the effort leaves behind in living specs, ADRs and the glossary, was extracted, then closing the root and disposing of the nodes per workflow.maps.persist. Invoke when a map has just been cleared, when the last node on a map resolves, or when the user asks to archive or close out a map. Refuses and asks first if anything is still open. Also archives legacy acstack/changes/ directories from the pre-map workflow.
+argument-hint: "[map or legacy change name]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+A map is scaffolding. It exists to clear fog – the questions nobody could
+state precisely when the effort started.
+
+Once the fog clears, the answers belong in living specs, ADRs and the
+glossary, not in a second copy that drifts. That is the residue – what
+survives the map.
+
+Archive verifies the residue reached those three places. It then closes the
+map's root node and disposes of the rest.
+
+## Step 1: Locate the map
+
+If `$ARGUMENTS` names a map, use it. Otherwise list maps on the configured
+tracker (`workflow.maps.tracker`): `ls acstack/maps/` on the files backend,
+`gh label list --search "map:" --json name` on GitHub.
+
+If exactly one, use it. If several, ask. If `$ARGUMENTS` names a legacy
+`acstack/changes/` directory instead, jump to Legacy below.
+
+## Step 2: Verify no open work remains
+
+A map counts as cleared when nothing remains to work – no open nodes, no
+fog, no claims. Check all three on the files backend:
+
+```bash
+~/.claude/acstack/bin/acstack node list --map <name> --status open --json
+~/.claude/acstack/bin/acstack node list --map <name> --status fog --json
+~/.claude/acstack/bin/acstack node list --map <name> --status claimed --json
+```
+
+On GitHub, compose the same checks per `trackers/github.md` in the map skill.
+`gh issue list --label "map:<name>" --state open` must come back empty, or
+hold the issue labelled `root-node` alone. Any other open issue is open, fog
+or claimed, and all three fail the gate.
+
+Never run the files commands against a GitHub-tracked map. They come back
+empty because the directory does not exist, so the gate would pass on no
+evidence.
+
+All three must come back empty, apart from the root.
+
+The root is the map's one node with no `answers`, and on GitHub it carries the
+`root-node` label. It stays open until Step 4 closes it. Ignore it in all
+three lists – a list holding the root alone still passes the gate.
+
+Count open nodes directly rather than through the frontier query, because the
+frontier only lists nodes with no unresolved blockers. Two nodes that block
+each other show an empty frontier while both questions stay open. An empty
+frontier is therefore no proof of a cleared map.
+
+If anything remains, WARN with what it is and ask for confirmation –
+archiving an uncleared map throws away open questions.
+
+## Step 3: Extract the residue
+
+Walk the resolved nodes – read them in order, root first, then each node that
+hangs off it. On the files backend, run `acstack node walk --map <name> --full`.
+On GitHub, compose the walk per `trackers/github.md`.
+
+Check each resolution left what it should have:
+
+1. **Living specs** – behaviour the effort built should already be in
+   `acstack/specs/` via commit-time sync. Spot-check the affected domains.
+   Fix gaps on sight per the Spec Correction Protocol.
+
+2. **ADRs and glossary** – invoke `record-context` for any resolved decision
+   that meets the bar and that nobody recorded. This is the last chance.
+
+3. **Out-of-scope nodes** – report them. A scope boundary is worth the user
+   hearing once more before the map disappears.
+
+4. **The decision log** – read `<main checkout>/acstack/.decisions/<name>.tsv`
+   if it exists. The main checkout is `dirname` of `git rev-parse
+   --path-format=absolute --git-common-dir`.
+
+    afk runs append one row per decision an agent made alone. Hand each
+    lasting decision to `record-context`. A later row supersedes an earlier
+    one it contradicts.
+
+## Step 4: Close the root
+
+The root carries no status of its own – it stays open while any node below it
+still needs work. Step 2 proved nothing does. Resolve the root now.
+
+```bash
+# files backend
+~/.claude/acstack/bin/acstack node update <root id> --map <name> --status resolved
+
+# github backend
+gh issue close <root issue number> --reason completed
+```
+
+A root the map already resolved or closed stays that way. Never reopen it.
+
+## Step 5: Dispose of the nodes
+
+**Confirm first when you invoked this yourself.** A user who typed
+`/acstack:archive` has already asked for disposal – proceed.
+
+If you reached this skill on your own after a map cleared, name what you
+will delete or move. Then wait for the user's go-ahead. Deletion is
+irreversible and they never asked for it.
+
+`workflow.maps.persist` in `acstack/project.yaml` decides (default `false`):
+
+| Value             | Action                                                       |
+| ----------------- | ------------------------------------------------------------ |
+| `false` (default) | delete `acstack/maps/<name>/`                                 |
+| `true`            | move the nodes to `acstack/archive/[YYYY-MM-DD]-[name]/nodes/` |
+
+Default is delete because keeping the nodes leaves a second copy of every
+decision, and the two drift. On the GitHub tracker there is nothing to
+dispose – closed issues are already the archive.
+
+Also dispose of `acstack/handoffs/<name>/` if it exists. Consumed handoffs
+hold conversation content and should not outlive the map they served.
+
+Delete the map's decision log, `<main checkout>/acstack/.decisions/<name>.tsv`,
+on either tracker. Step 3 already extracted what it held. Leave the directory
+and its `.gitignore` for the next map.
+
+## Step 6: Report
+
+- Nodes resolved / out-of-scope counts
+- Residue: domains spot-checked, ADRs and glossary entries written
+- Disposal: deleted, or archive path
+- Reminder: commit with `/acstack:commit`
+
+## Legacy: archiving a `acstack/changes/` directory
+
+The pre-map workflow created changes that hold proposal.md, design.md and
+tasks.md. They still archive the old way, so an upgrade never strands work:
+
+1. Read the change's artifacts. Derive the affected domains from the file
+   paths in `tasks.md` via `acstack/domain-map.yaml`.
+
+2. For each domain, merge what the feature ADDED, MODIFIED or REMOVED into
+   `acstack/specs/[domain]/spec.md`.
+
+3. Write a `delta.md` into the change directory.
+
+    Then run the CLI's `acstack archive <name>`. It moves the artifacts,
+    delta included, to `acstack/changes/archive/[YYYY-MM-DD]-[change-name]/`.
+    It also removes the change from `acstack/changes/`.

package/skills/bootstrap/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: bootstrap
+description: Multi-pass AI crawl to generate initial living specs from the existing codebase. Use when acstack/specs/ domains need their initial spec.md files bootstrapped from code.
+argument-hint: "[domain-names (optional)]"
+disable-model-invocation: true
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+Consider the user input before you proceed, if it is not empty.
+
+## Purpose
+
+This skill bootstraps cumulative living specs in `acstack/specs/`. It crawls the existing codebase with multiple independent AI passes. It then merges the passes and validates the results.
+
+**IMPORTANT**: This is a one-time bootstrapping operation. Only run when `acstack/specs/` domains have no `spec.md` files yet.
+
+## Your role: orchestrator only
+
+**You do NOT read code, explore the codebase, or write specs yourself.**
+
+Your job is to:
+
+1. Run the pre-flight check (read domain-map.yaml)
+2. Launch subagents with the prompts below
+3. Pass outputs from one phase to the next
+4. Present summaries to the user for review
+5. Coordinate the phases sequentially
+
+## Pre-flight check
+
+1. Read `acstack/domain-map.yaml` to get the list of domains and their file path mappings.
+2. If `$ARGUMENTS` specifies domain names, filter to only those domains.
+3. Check if any `acstack/specs/*/spec.md` files already exist:
+    - If specs exist, warn the user. Ask for confirmation before overwriting.
+    - If no specs exist, proceed automatically.
+
+## Phase 1: independent exploration (passes 1-3)
+
+Launch **3 parallel `Explore` subagents** at once. Each gets a different exploration strategy:
+
+### Pass 1 – entry points strategy
+
+Explore from entry points (main files, route handlers, API endpoints, page components) to discover functionality domain by domain.
+
+### Pass 2 – data models strategy
+
+Explore from data models outward (database models, schemas, interfaces) to map data flow from storage through services to API to UI.
+
+### Pass 3 – tests strategy
+
+Explore from test files to understand expected behaviors by reading test names, assertions, and cross-referencing with source code.
+
+Each pass outputs domain drafts using this format:
+
+```markdown
+# [Domain Name] - Living Specification
+
+## Overview
+[1-2 paragraph description]
+
+## Key Entities
+[List major classes, services, models]
+
+## Functional Requirements
+
+### FR-001: [Requirement Name]
+- **Description**: [What the system does]
+- **Behavior**: Given [precondition], When [action], Then [result]
+- **Source**: [File path where this is implemented]
+
+### FR-002: ...
+```
+
+Write each functional requirement (FR) per the `writing` skill.
+
+```markdown
+## Integration Points
+## Configuration
+## Constraints & Invariants
+```
+
+## Phase 2: judge merge (pass 4)
+
+Launch a single subagent to merge the 3 independent drafts per domain. It resolves conflicts, deduplicates, and picks the most accurate description for each FR.
+
+## Phase 3: validation (passes 5-7)
+
+Launch 3 parallel Explore subagents to validate ALL domains independently – each checks that FRs match actual code behavior.
+
+## Phase 4: correction merge (pass 8)
+
+Launch a single subagent to apply validated corrections from Phase 3.
+
+## Phase 5: human review (pass 9)
+
+Present a summary to the user. Ask: "Review the specs in `acstack/specs/`. Want to edit any domain before finalizing?"
+
+## Phase 6: finalization (pass 10)
+
+Launch a single subagent to finalize all specs. It removes markers, makes sure the formatting is consistent, and re-numbers FR entries.
+
+## Completion
+
+Report: the number of domain specs created, the total functional requirements, and the suggested next step.

package/skills/bridge/HANDOFF.md

@@ -0,0 +1,93 @@
+# Cross-device handoff format
+
+The bridge spans two devices. When a coding agent on one side needs the
+other side to act, it emits a **handoff block** in this exact shape:
+
+```
+--- BEGIN <WINDOWS|VM>-SIDE HANDOFF ---
+Context: <one line describing what happened and why the other side must act>
+Run on <device>:
+  <exact command(s)>
+Expected result:
+  <exact success criterion>
+Report back:
+  <exact output the requesting side needs>
+--- END <WINDOWS|VM>-SIDE HANDOFF ---
+```
+
+The `WINDOWS-SIDE` or `VM-SIDE` tag names the side that **produced** the
+block, so the other side knows who asked. `Run on <device>` names who
+**executes** it.
+
+The other side pastes the block verbatim into another coding agent. If
+the user on that side has no coding agent, they paste it into a plain
+PowerShell or SSH shell instead.
+
+## Worked example 1 – Windows → VM, free a stuck port
+
+`doctor.ps1` produces this block on the Windows laptop when
+tunnel-<host>.log shows the stuck-port signature:
+
+```
+--- BEGIN WINDOWS-SIDE HANDOFF (to VM agent on vm1.example.com) ---
+Context: the Playwriter bridge tunnel to vm1.example.com is stuck.
+tunnel-vm1.example.com.log shows "remote port forwarding failed for
+listen port 19988", meaning something on the VM already holds the port.
+
+Run on vm1.example.com:
+  bash ~/.claude/acstack/bin/vm-free-port.sh
+
+Expected result:
+  ss -lnt 'sport = :19988' is empty, or vm-free-port.sh refuses and
+  tells you the port is held by your own interactive session (in which
+  case exit that session and retry).
+
+Report back:
+  The exit status of vm-free-port.sh and the final ss output.
+--- END WINDOWS-SIDE HANDOFF ---
+```
+
+After the VM side acts, the Windows side confirms recovery with:
+
+```
+Start-ScheduledTask Playwriter-Tunnel-VM1
+doctor.ps1
+```
+
+Success criterion: all rows green.
+
+## Worked example 2 – VM → Windows, restart a tunnel task
+
+A VM-side agent produces this block when `agent-browser` cannot reach
+`http://127.0.0.1:19988/json/version`:
+
+```
+--- BEGIN VM-SIDE HANDOFF (to Windows agent) ---
+Context: agent-browser on vm1.example.com cannot reach the CDP endpoint
+at 127.0.0.1:19988 (connection refused). The tunnel appears down.
+
+Run on the Windows laptop:
+  Stop-ScheduledTask Playwriter-Tunnel-VM1
+  Start-ScheduledTask Playwriter-Tunnel-VM1
+  .\doctor.ps1
+
+Expected result:
+  doctor.ps1 exits with all green rows, including "Relay listening on
+  19988" and no tunnel-*.stuck markers.
+
+Report back:
+  The doctor.ps1 output (paste the table).
+--- END VM-SIDE HANDOFF ---
+```
+
+## Rules for writing a handoff
+
+- **Exact commands.** No "figure out the right flag" – the other side
+  may be a human at a shell, not a coding agent.
+
+- **One verifiable success criterion.** Not "looks ok".
+- **Small.** One problem per block. If two things break, emit two
+  blocks.
+
+- **Scrub internal names.** No employer names, people names, internal IP
+  ranges, ticket IDs. Use placeholders like `<host>`, `vm1.example.com`.