acstack 0.0.0-stage → 0.47.0

package/skills/explore/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Invoke when the user signals they want to think rather than build – thinking out loud, weighing options, asking what if, or saying they are not ready to start yet. Explore mode never writes code, so do not invoke it on a request to build something; use implement, quick-fix or map for that.
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+Enter explore mode.
+
+Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT**: Explore mode is for thinking, not implementing.
+
+You may read files, search code, and investigate the codebase. You must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and map out the work with /acstack:map.
+
+You MAY create ACStack artifacts (map nodes, specs, ADRs) if the user asks – that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally. Don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions. Let the user follow what resonates
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads. Pivot when new information emerges
+- **Patient** - Don't rush to conclusions. Let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant. Don't just theorize
+
+---
+
+## What you might do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+
+```
++---------------------------------------------+
+|     Use ASCII diagrams liberally            |
++---------------------------------------------+
+|                                             |
+|   +--------+         +--------+             |
+|   | State  |-------->| State  |             |
+|   |   A    |         |   B    |             |
+|   +--------+         +--------+             |
+|                                             |
+|   System diagrams, state machines,          |
+|   data flows, architecture sketches,        |
+|   dependency graphs, comparison tables      |
++---------------------------------------------+
+```
+
+**Surface risks and unknowns**
+
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## ACStack awareness
+
+You have full context of the ACStack system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists – maps on the configured tracker
+(`ls acstack/maps/` on the files backend) and living specs
+(`~/.claude/acstack/bin/acstack list --specs --json`).
+
+### When no map exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start. Want me to chart it with /acstack:map?"
+- Or keep exploring – no pressure to formalize
+
+### When a map exists
+
+If the user mentions a map or you detect one is relevant:
+
+1. Orient with the packaging walk (`acstack node walk --map <name>`)
+    - On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
+      map skill's `trackers/github.md`
+2. Reference them naturally in conversation
+3. Offer to capture when a decision lands:
+
+| Insight Type               | Where to Capture             |
+| -------------------------- | ---------------------------- |
+| New requirement discovered | `specs/<domain>/spec.md`     |
+| Requirement changed        | `specs/<domain>/spec.md`     |
+| Design decision made       | an ADR via `record-context`  |
+| Term pinned down           | glossary via `record-context` |
+| New work identified        | a map node (a small tracked-work record, if a map exists) |
+| Assumption invalidated     | Relevant artifact            |
+
+4. The user decides – offer and move on. Don't pressure.
+
+---
+
+## What you don't have to do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights. Don't just do it
+- **Write for the reader** - Captured artifacts follow the `writing` skill
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own

package/skills/grilling/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: grilling
+description: Interview technique for settling open decisions in rounds. A round asks the whole frontier – every question whose prerequisites are settled – numbered, each with a recommended answer, then recomputes and repeats. Use whenever decisions need a human and requirements are foggy, with or without a map. Called by /acstack:map for charting and frontier work; also usable directly in conversation.
+---
+
+# Grilling
+
+Grilling settles open decisions by asking the user a whole round of questions
+at once. One technique at two scales.
+
+The frontier is the set of questions ready to ask – every open question with
+settled prerequisites.
+
+In conversation you work it out as you go. On a map – a stored graph of
+question and work nodes – you ask the tracker for it. You limit it to `hitl`
+nodes, meaning the ones a human must answer rather than an agent.
+
+On the files backend:
+
+`~/.claude/acstack/bin/acstack node frontier --map <name> --mode hitl`
+
+The map skill's `trackers/` docs declare other backends. Same structure
+either way – the only difference is whether the frontier outlives the
+session.
+
+## The round
+
+1. **Compute the frontier.** Every question with settled prerequisites,
+   nothing else. Never ask a question whose answer depends on one still open.
+
+2. **Facts are your job, never the user's.** Skip a question that an
+   environment fact would answer. Dispatch parallel `Explore` subagents, one
+   per distinct place to look, not a fixed count. Fold what they find into
+   the round.
+
+3. **Run it before you ask it.** Check whether running something could answer
+   the question – behaviour, timing, output, or performance. If it could,
+   dispatch a subagent to build a throwaway prototype instead of asking the
+   user:
+    - The subagent builds it in `/tmp/acstack-proto/<node-id>/`, or
+      `/tmp/acstack-proto/<short-slug>/` with no map
+    - It imports repo code by absolute path, and never creates a prototype
+      file inside the repo
+    - It returns the answer and its evidence, then deletes the folder
+    - You record both on the node, or in the conversation with no map
+
+    Questions of taste, product, or preference still go to the user. No
+    prototype code is ever copied into the repo – the real build goes
+    through the normal TDD pipeline.
+
+4. **Number the questions.** Attach a recommended answer to each, with one
+   line of reasoning. A question you cannot recommend an answer for is usually
+   two questions.
+
+5. **Present the whole round at once** (see Presentation). One round, one
+   message. Never trickle questions one at a time.
+
+6. **Record each answer.** If no option matches, the reply itself is the
+   answer, never the nearest option.
+
+7. **Recompute the frontier.** Answers surface new questions and unblock old
+   ones. Derive the next round fresh. Never continue down a list planned in
+   advance.
+
+## Presentation
+
+`workflow.grilling.questions` in `acstack/project.yaml` picks the mode:
+
+| Value            | Behaviour                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `tool` (default) | the host's question tool (AskUserQuestion on Claude Code), one call per round        |
+| `inline`         | questions as prose in the reply – also what `tool` means on a host with no such tool |
+
+**`tool` falls back to inline** for any round it cannot hold: more than 4
+questions, or any question with no discrete options. Never split one round
+across two tool calls – a round is the whole frontier, and splitting it
+reintroduces the ordering the frontier exists to prevent. In tool mode, put
+the recommended option first with "(Recommended)".
+
+**Inline format**: numbered questions, options in a table, the recommended
+option **bolded** with its one-line reason. Prose follows the `writing` skill.
+
+Whichever mode runs, an open answer survives: if the user types something no
+option covers, that text is the answer.
+
+## Stop condition
+
+Stop when the frontier is empty, or the user signals stop ("stop", "done",
+"proceed").
+
+There is no question cap. Settled prerequisites already bound the
+frontier, and provenance keeps it narrow. Every question hangs off the
+answer that surfaced it, so nothing unrelated can join the round.
+
+A cap would be a blunt proxy for a guarantee the frontier definition
+provides.
+
+## On a map
+
+When the questions are map nodes, each answer is a resolution – all through
+the tracker's `update` and `create` operations:
+
+1. Append the answer to the node body under `## Answer`. Mark the node
+   resolved. On the files backend, one `acstack node update` call does both.
+
+    Write the answer per the `writing` skill.
+
+2. Create a node for each new question the answer surfaced, with `answers`
+   naming the node that surfaced it. Questions that can be stated precisely
+   are `open`; the rest are `fog`.
+
+3. Invoke the `record-context` skill for each resolution – it decides whether
+   the decision earns an ADR, a glossary term, both, or neither.
+
+4. Redraw the resolved node's own diagram to mark the path you chose, then
+   regenerate its parent's. The map skill's `visuals.md` holds the rules and
+   the command.
+
+5. Recompute the frontier with the tracker's query and present the next
+   round.
+
+**Example** – the `## Answer` body of a node asking whether map nodes
+belong in git:
+
+```markdown
+## Answer
+
+Map nodes stay out of git. `acstack/maps/` goes in `.gitignore`, because a
+node is working state that the map throws away once it clears.
+
+The durable output is the living specs, the architecture decision records and
+the glossary. The `record-context` skill extracts each one as a node
+resolves, so nothing of lasting value leaves with the nodes.
+```

package/skills/handoff/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: handoff
+description: Hand the current work to a visible agent – a new one running in its own pane, or one already running. Writes only what nothing on disk holds – the next action, decisions already made, blockers, file ownership – and references everything else. Invoke when the user asks to hand work over or to spin the work out to another agent, or when context pressure makes continuing in this session unwise. Keeping the work in this session across a context compaction is the compact-and-continue skill's job.
+argument-hint: "[focus note – what the receiving agent must not lose]"
+---
+
+## User input
+
+```text
+$ARGUMENTS
+```
+
+Treat the argument as the focus for the receiving agent.
+
+# Hand the work over
+
+A handoff moves the current work to an agent a human can see – a named session
+in a visible pane, or a session already running. To keep the work in THIS
+session across a context compaction instead, use `compact-and-continue`.
+
+## Only the lead session runs this
+
+An agent that another agent launched stops here. One Bash call tells you
+whether you are one. Replace `<nonce>` with eight random hex characters, picked
+fresh, and never with a value already used in this session:
+
+<!-- lead-check: tests/test-skill-gates.sh extracts and runs the block below -->
+
+```bash
+n=acstack-whoami-<nonce>
+s="${CLAUDE_CODE_SESSION_ID:-none}"
+p="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/projects"
+case "${PI_SESSION_FILE:-}" in
+  */run-[0-9]*/session.jsonl|*/forks/*.jsonl) echo "child: $PI_SESSION_FILE"; exit 0;;
+  ?*) [ -z "${CLAUDE_CODE_SESSION_ID:-}" ] && { echo "lead"; exit 0; };;
+esac
+for _ in $(seq 1 20); do
+  m=$(grep -lF "$n" "$p"/*/"$s"/subagents/agent-*.jsonl 2>/dev/null </dev/null | head -1)
+  [ -n "$m" ] && { echo "child: $m"; exit 0; }
+  grep -qF "$n" "$p"/*/"$s".jsonl 2>/dev/null </dev/null && { echo "lead"; exit 0; }
+  sleep 0.5
+done
+echo "lead"
+```
+
+`lead` means carry on. `child: <path>` means stop, and tell whoever launched
+you that this skill runs only in the lead session. Report your state upward
+instead – in your final message, or through your host's agent-messaging tool
+(`SendMessage` on Claude Code). The lead then hands off or compacts.
+
+Read [`lead-check.md`](lead-check.md) before you change that command, or when
+its answer looks wrong. It says why a child must stop, and what it checks.
+
+## First: is this yours to invoke?
+
+If the user asked for a handoff, proceed. If you invoke it on your own
+initiative, first read `workflow.handoff.self_invoke` from `acstack/project.yaml`.
+
+If it is `false`, stop. Tell the user a handoff looks warranted and why. Ask
+permission.
+
+Unset means `true`.
+
+## Where the work goes
+
+herdr is the terminal workspace manager some sessions run inside. Four terms
+carry its vocabulary, defined once here.
+
+A **herdr workspace** is a git worktree. A **herdr tab** is a session working
+inside one.
+
+A **pane** is the terminal rectangle a session occupies. An **agent** is a named
+session herdr supervises.
+
+One rule decides the destination:
+
+| The work is                                  | Goes to                                                          |
+| -------------------------------------------- | ---------------------------------------------------------------- |
+| a continuation of what this session is doing | a new **tab** in this workspace – same worktree, same files       |
+| genuinely separate, or runs in parallel      | a new **worktree**, so a new **workspace**, with its own checkout |
+| better suited to an agent already running    | that agent, by message – no new pane at all                      |
+
+Ambiguous cases go to the user. Do not guess. Without herdr there are no tabs
+and no workspaces, so this table collapses to two cases – *Without herdr*, in
+[`launch-without-herdr.md`](launch-without-herdr.md), gives that variant.
+
+**Consider the agents already running before launching anything.** List live
+sessions with `claude agents --json`, which works with no terminal attached.
+
+Read [`running-agent.md`](running-agent.md) when the listing shows a live session.
+
+## The rule that governs the handoff
+
+*Reference state. Never copy it.*
+
+A handoff that restates the repo is a second copy of the repo, correct only at
+the moment you write it. Anything the receiving agent can run a command to learn,
+it should run the command.
+
+| Do not write it down        | The receiving agent gets it from                                                  |
+| --------------------------- | --------------------------------------------------------------------------------- |
+| Map state and reading order | `~/.claude/acstack/bin/acstack node walk --map <name>` (reading order of the map)  |
+| What can be worked next     | `~/.claude/acstack/bin/acstack node frontier --map <name>` (what is workable now)  |
+| Files in flight             | `git status --short` and `git diff`                                                |
+| Test baseline, last result  | `.test-baseline`, then run the suite                                               |
+| What the code does          | the living specs in `acstack/specs/`                                               |
+
+On GitHub, `--map` refuses – pipe `gh issue list` into `--stdin` per the
+map skill's `trackers/github.md`.
+
+The same applies to specs, architecture decision records, issues and commits.
+Reference them by path or URL.
+
+**You do not search the codebase for this.** Build the handoff from what is already
+in context. If you are about to search source files, stop – the conversation holds it.
+
+## What only a handoff can carry
+
+*Five things. Nothing on disk records them, so what you leave out disappears.*
+
+1. **Next action** – the single concrete thing to do first
+2. **Decisions made** – so nobody reopens and re-argues them
+3. **Open questions and blockers** – including anything waiting on the user
+4. **Agent-team file ownership** – each scope, its teammate, its non-overlapping
+   file set. Also name any shared file to touch only after the team finishes.
+   Nothing else records this
+
+5. **Suggested skills** – which skills the receiving agent should invoke, by name
+
+Omit any that do not apply. Do not pad.
+
+Prose follows the `writing` skill.
+
+## Redaction
+
+*The handoff leaves the conversation and becomes another agent's prompt.*
+
+Strip credentials, tokens, API keys, connection strings and personal data before
+writing. Reference where a secret lives, not its value. This is not optional.
+
+## Write the handoff file
+
+Write the handoff to the OS temporary directory, never the workspace – it is
+conversation content, not project state, and must not be committable. Name it
+`$TMPDIR/acstack-handoff-<slug>-<timestamp>.md` (`/tmp` when `$TMPDIR` holds
+nothing), where `<slug>` names the work and `<timestamp>` stops two handoffs
+colliding.
+
+Its first line, above every heading, repeats the acknowledgement requirement
+verbatim, with `<this-file>` replaced by the file's own path:
+
+```text
+Acknowledge before any other tool call. Run ~/.claude/acstack/bin/acstack handoff ack accept --file <this-file> "<one-line reason>", or ack decline --file <this-file> "<one-line reason>". The command writes <this-file>.ack, which the sender watches.
+```
+
+This temp file is not `acstack/HANDOFF.md`, the `compact-and-continue` anchor.
+Never put this line into that anchor, which has to start with `---` frontmatter.
+
+Head the rest with the same skeleton the `compact-and-continue` anchor uses. The
+headings are Next action, Decisions made, Open questions and blockers,
+Agent-team plan, Suggested skills, References. That skeleton is the five carried
+items above, plus the commands from the reference table instead of copied state.
+
+Drop any heading with nothing under it.
+
+The launch prompt is a **single-line pointer at that file**, never the handoff
+text itself. `herdr agent start` rejects newlines and tabs in its arguments.
+
+## Every prompt opens with an acknowledgement
+
+Every handoff prompt asks for the command.
+
+There are two prompts, because the two destinations must say different things.
+Use the matching one verbatim, and substitute only the handoff file path.
+
+Each one is a single line. `herdr agent start` rejects newlines and tabs in its
+arguments. So the instruction and the pointer at the handoff file share that one
+line.
+
+**Fresh agent** – one launched for this handoff, into a new pane, worktree or
+tab, or as a `--bg` session. Reading the handoff file is the one tool call
+allowed before the ack command. Every other tool call – a command, an edit, a
+subagent – leaves the acknowledgement still owed.
+
+> Before any other tool call, acknowledge this handoff by running ~/.claude/acstack/bin/acstack handoff ack accept --file <handoff-file> "<one-line reason>", or ack decline --file <handoff-file> "<one-line reason>". You may read <handoff-file> first to judge whether the work suits you, and nothing else until the command has run – the sender watches for the file it writes and cannot report this work as yours until it exists. Then continue that work.
+
+**Agent already running** – one reached by cross-session message. Its variant
+of the opener is in [`running-agent.md`](running-agent.md).
+
+The agent may investigate before it decides. Acknowledgement comes first, work
+second. Never start the work and acknowledge later – by then the sender has
+already had to guess.
+
+## Launch
+
+Read [`watch.md`](watch.md) first, for the pre-launch snapshot, then one of:
+
+- [`launch-herdr.md`](launch-herdr.md) – `HERDR_ENV` is `1`, a new worktree or tab
+- [`launch-without-herdr.md`](launch-without-herdr.md) – `HERDR_ENV` is not `1`
+- [`running-agent.md`](running-agent.md) – an agent already running
+
+## Watch for the acknowledgement
+
+Do not eyeball transcripts. The CLI watches for you:
+
+```bash
+~/.claude/acstack/bin/acstack handoff watch --file <handoff-file> \
+  --session-id <id> --cwd <dir> --token <token> --turns <n>
+```
+
+**Run the watcher in the background.** This session has stopped working on the
+task, but it must not lock up. The user can keep talking to it while the handoff
+lands, and the harness surfaces the watcher's exit on its own. Never sit in a
+foreground wait.
+
+[`watch.md`](watch.md) gives every flag, `--fresh` among them. When the watcher
+exits, read [`outcomes.md`](outcomes.md) for what its result means.
+
+## Silence the context-pressure nudge
+
+Once you finish the handoff, write the quiet marker. The context-pressure Stop
+hook reads it and stays silent for the rest of this session. The work has
+already moved on, so there is nothing left to nudge about:
+
+```bash
+d="${ACSTACK_CONTEXT_PRESSURE_DIR:-${TMPDIR:-/tmp}/acstack-context-pressure}"
+sid="${CLAUDE_CODE_SESSION_ID:-${PI_SESSION_ID:-}}"; [ -n "$sid" ] && mkdir -p "$d" && : > "$d/$sid.quiet" || true
+```
+
+`CLAUDE_CODE_SESSION_ID` (`PI_SESSION_ID` on pi) is this session's own id. The
+lead check at the top ruled out child sessions, so the marker lands where the hook looks.
+
+If the variable holds nothing, skip this step and say so in the report. The hook
+then keeps nudging, which is noisy but harmless.
+
+## Report
+
+Always name the target, the handoff file path, and the next action the receiving
+agent would take. The target is an agent name with its pane or workspace, or the
+existing session.
+
+Then say where the handoff stands, in the terms of [`outcomes.md`](outcomes.md).
+
+- accepted
+- declined on fit, and relaunched elsewhere
+- declined on the merits, with the objection in enough of its own words to act on
+- proceeding, unacknowledged – the target engaged, and you spent the nudge
+- unacknowledged – read `outcomes.md` for `staleAck` before you report this
+
+Never describe the work as owned by the target until the target has accepted it.