@erclx/aitk 0.8.0

package/scripts/tooling/create.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+trap close_timeline EXIT
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  log_step "Tooling create usage"
+  echo -e "${GREY}│${NC}  ${WHITE}Usage:${NC} aitk tooling create [stack]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  Creates a new stack with stub manifest, reference, configs, and seeds."
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Arguments:${NC}"
+  echo -e "${GREY}│${NC}    stack   Name of the new stack to create"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+main() {
+  if [[ "$1" == "-h" || "$1" == "--help" ]]; then
+    show_help
+  fi
+
+  local stack="$1"
+
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}│${NC} ${WHITE}aitk tooling create${NC}"
+
+  if [ -z "$stack" ]; then
+    ask "Stack name?" "stack"
+  fi
+
+  if [ -z "$stack" ]; then
+    log_error "Stack name is required"
+  fi
+
+  if is_tooling_stack_excluded "$stack"; then
+    log_error "Reserved name: $stack. Managed by \`aitk claude\`, not \`aitk tooling\`."
+  fi
+
+  local dest="$PROJECT_ROOT/tooling/$stack"
+
+  if [ -d "$dest" ]; then
+    log_error "Stack already exists: $stack"
+  fi
+
+  log_step "Creating"
+  log_add "tooling/$stack/configs/"
+  log_add "tooling/$stack/seeds/"
+  log_add "tooling/$stack/manifest.toml"
+  log_add "tooling/$stack/reference.md"
+
+  select_option "Create stack at tooling/$stack?" "Yes" "No"
+
+  if [ "$SELECTED_OPTION" = "No" ]; then
+    log_warn "Cancelled"
+    exit 0
+  fi
+
+  log_step "Applying"
+
+  mkdir -p "$dest/configs"
+  log_add "tooling/$stack/configs/"
+
+  mkdir -p "$dest/seeds"
+  log_add "tooling/$stack/seeds/"
+
+  cat >"$dest/manifest.toml" <<EOF
+[stack]
+name = "$stack"
+extends = ""
+runtime = ""
+scaffold = ""
+
+[dependencies.dev]
+packages = []
+
+[scripts]
+"script-key" = "command --flag"
+
+[gitignore]
+"# $stack" = ["pattern/", ".file"]
+EOF
+  log_add "tooling/$stack/manifest.toml"
+  cat >"$dest/reference.md" <<EOF
+# Tooling $stack reference
+
+## Overview
+
+[One or two sentences: what this stack provides and its purpose.]
+
+EOF
+  log_add "tooling/$stack/reference.md"
+
+  trap - EXIT
+  echo -e "${GREY}└${NC}\n"
+  echo -e "${GREEN}✓ Stack created${NC}"
+}
+
+main "$@"

package/scripts/tooling/ref.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+trap close_timeline EXIT
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  log_step "Tooling ref usage"
+  echo -e "${GREY}│${NC}  ${WHITE}Usage:${NC} aitk tooling ref [stack] [target-path]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  Drops reference docs only. No config or dependency changes."
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Arguments:${NC}"
+  echo -e "${GREY}│${NC}    stack         Name of the tooling stack (e.g., base, vite-react)"
+  echo -e "${GREY}│${NC}    target-path   Target directory (default: current directory)"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    -h, --help    ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+select_stack() {
+  local stacks=()
+  mapfile -t stacks < <(list_tooling_stacks)
+
+  if [ ${#stacks[@]} -eq 0 ]; then
+    log_error "No tooling stacks found in $PROJECT_ROOT/tooling"
+  fi
+
+  select_option "Select tooling stack:" "${stacks[@]}"
+  echo "$SELECTED_OPTION"
+}
+
+collect_references() {
+  local stack="$1"
+  local target="$2"
+  local -n _pending=$3
+
+  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
+  [ ! -f "$manifest" ] && return
+
+  local extends
+  extends=$(grep '^extends' "$manifest" 2>/dev/null | cut -d'"' -f2)
+
+  if [ -n "$extends" ]; then
+    collect_references "$extends" "$target" "$3"
+  fi
+
+  local reference_file="$PROJECT_ROOT/tooling/$stack/reference.md"
+  [ ! -f "$reference_file" ] && return
+
+  local dest="$target/.claude/tooling/$stack.md"
+
+  if [ -f "$dest" ] && diff -q "$reference_file" "$dest" >/dev/null 2>&1; then
+    log_info ".claude/tooling/$stack.md"
+    return
+  fi
+
+  log_add ".claude/tooling/$stack.md"
+  _pending+=("$stack")
+}
+
+apply_references() {
+  local target="$1"
+  shift
+  local stacks=("$@")
+
+  mkdir -p "$target/.claude/tooling"
+
+  for stack in "${stacks[@]}"; do
+    local src="$PROJECT_ROOT/tooling/$stack/reference.md"
+    cp "$src" "$target/.claude/tooling/$stack.md"
+    log_add ".claude/tooling/$stack.md"
+    rm -f "$target/tooling/$stack.md"
+  done
+  rmdir "$target/tooling" 2>/dev/null || true
+}
+
+main() {
+  if [[ "$1" == "-h" || "$1" == "--help" ]]; then
+    show_help
+  fi
+
+  local stack="$1"
+  local target="${2:-.}"
+
+  echo -e "${GREY}┌${NC}" >&2
+  echo -e "${GREY}│${NC} ${WHITE}aitk tooling ref${NC}" >&2
+
+  if [ -z "$stack" ]; then
+    stack=$(select_stack)
+  fi
+
+  if is_tooling_stack_excluded "$stack"; then
+    log_error "Claude is managed by \`aitk claude\`, not \`aitk tooling\`."
+  fi
+
+  if [ ! -d "$PROJECT_ROOT/tooling/$stack" ]; then
+    log_error "Stack not found: $stack"
+  fi
+
+  guard_root "$target"
+
+  local pending=()
+
+  echo -e "${GREY}├${NC} ${WHITE}Scanning references: $stack${NC}" >&2
+  collect_references "$stack" "$target" pending
+
+  if [ "${#pending[@]}" -eq 0 ]; then
+    trap - EXIT
+    echo -e "${GREY}└${NC}\n" >&2
+    echo -e "${GREEN}✓ References up to date${NC}" >&2
+    exit 0
+  fi
+
+  local dest_display="$target/.claude/tooling/"
+  dest_display="${dest_display#./}"
+
+  select_option "Sync ${#pending[@]} reference(s) to $dest_display?" "Yes" "No"
+
+  if [ "$SELECTED_OPTION" = "No" ]; then
+    log_warn "Cancelled"
+    exit 0
+  fi
+
+  log_step "Applying changes"
+  apply_references "$target" "${pending[@]}"
+
+  trap - EXIT
+  echo -e "${GREY}└${NC}\n" >&2
+  echo -e "${GREEN}✓ References synced${NC}" >&2
+}
+
+main "$@"

package/scripts/tooling/verify.sh

@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(dirname "$(dirname "$SCRIPT_DIR")")}"
+
+source "$PROJECT_ROOT/scripts/lib/ui.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+
+show_help() {
+  echo -e "${GREY}┌${NC}"
+  echo -e "${GREY}├${NC} ${WHITE}Usage:${NC} aitk tooling verify <stack> [options]"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  ${WHITE}Options:${NC}"
+  echo -e "${GREY}│${NC}    --keep       ${GREY}# Keep tmp dir after run for inspection${NC}"
+  echo -e "${GREY}│${NC}    -h, --help   ${GREY}# Show this help message${NC}"
+  echo -e "${GREY}│${NC}"
+  echo -e "${GREY}│${NC}  Scaffolds <stack> into .claude/.tmp/verify-<stack>/, syncs the full"
+  echo -e "${GREY}│${NC}  layer chain, and runs check + test:e2e + screenshot."
+  echo -e "${GREY}└${NC}"
+  exit 0
+}
+
+read_manifest_field() {
+  local toml="$1"
+  local section="$2"
+  local field="$3"
+  awk -v s="$section" -v f="$field" '
+    $0 == "[" s "]" { in_section = 1; next }
+    in_section && /^\[/ { exit }
+    in_section && match($0, "^" f "[[:space:]]*=") {
+      val = substr($0, RLENGTH + 1)
+      sub(/^[[:space:]]+/, "", val)
+      sub(/^"/, "", val)
+      sub(/"$/, "", val)
+      print val
+      exit
+    }
+  ' "$toml"
+}
+
+run_phase() {
+  local name="$1"
+  shift
+  log_step "$name"
+  if "$@" >/tmp/verify-phase.log 2>&1; then
+    log_info "$name passed"
+    RESULTS+=("$name:pass")
+    return 0
+  fi
+  log_warn "$name failed"
+  tail -20 /tmp/verify-phase.log >&2
+  RESULTS+=("$name:fail")
+  FAILED=1
+  return 1
+}
+
+main() {
+  local stack=""
+  local keep=0
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+    -h | --help) show_help ;;
+    --keep)
+      keep=1
+      shift
+      ;;
+    -*)
+      log_error "Unknown option: $1"
+      ;;
+    *)
+      if [ -z "$stack" ]; then
+        stack="$1"
+        shift
+      else
+        log_error "Unexpected argument: $1"
+      fi
+      ;;
+    esac
+  done
+
+  [ -z "$stack" ] && log_error "Stack required. See --help."
+
+  if is_tooling_stack_excluded "$stack"; then
+    log_error "Stack '$stack' is excluded from tooling."
+  fi
+
+  local manifest="$PROJECT_ROOT/tooling/$stack/manifest.toml"
+  [ ! -f "$manifest" ] && log_error "No manifest at $manifest"
+
+  local scaffold
+  scaffold=$(read_manifest_field "$manifest" "stack" "scaffold")
+  [ -z "$scaffold" ] && log_error "Stack '$stack' has no scaffold command in manifest."
+
+  local prepare
+  prepare=$(read_manifest_field "$manifest" "verify" "prepare")
+
+  open_timeline "aitk tooling verify $stack"
+  trap close_timeline EXIT
+
+  local tmp_root="$PROJECT_ROOT/.claude/.tmp"
+  local tmp_dir="$tmp_root/verify-$stack"
+
+  mkdir -p "$tmp_root"
+  rm -rf "$tmp_dir"
+
+  local project_name="verify-$stack"
+  local scaffold_cmd="${scaffold//\{\{name\}\}/$project_name}"
+
+  RESULTS=()
+  FAILED=0
+
+  log_step "Scaffolding $stack"
+  (cd "$tmp_root" && eval "$scaffold_cmd") >/tmp/verify-scaffold.log 2>&1 || {
+    log_warn "Scaffold failed"
+    tail -20 /tmp/verify-scaffold.log >&2
+    FAILED=1
+  }
+
+  if [ ! -d "$tmp_dir" ]; then
+    log_error "Scaffold did not produce $tmp_dir"
+  fi
+
+  (cd "$tmp_dir" && git init -q && git add . && git commit -m "chore: verify scaffold" -q --no-verify)
+
+  if [ -n "$prepare" ]; then
+    run_phase "Prepare" bash -c "cd '$tmp_dir' && $prepare"
+  fi
+
+  run_phase "Sync" bash -c "cd '$tmp_dir' && AITK_NON_INTERACTIVE=1 aitk tooling sync $stack ."
+
+  if [ -f "$tmp_dir/package.json" ]; then
+    run_phase "lint:fix" bash -c "cd '$tmp_dir' && bun run lint:fix"
+    run_phase "check" bash -c "cd '$tmp_dir' && bun run check"
+
+    if grep -q '"test:e2e"' "$tmp_dir/package.json"; then
+      run_phase "test:e2e" bash -c "cd '$tmp_dir' && bun run test:e2e"
+    fi
+
+    if grep -q '"screenshot"' "$tmp_dir/package.json"; then
+      if run_phase "screenshot" bash -c "cd '$tmp_dir' && timeout 60 bun run screenshot"; then
+        local shots
+        shots=$(find "$tmp_dir/screenshots" -type f -name '*.png' 2>/dev/null | wc -l)
+        if [ "$shots" -eq 0 ]; then
+          log_warn "screenshot produced no png files"
+          RESULTS+=("screenshot-artifacts:fail")
+          FAILED=1
+        else
+          RESULTS+=("screenshot-artifacts:pass")
+        fi
+      fi
+    fi
+  fi
+
+  log_step "Results"
+  for r in "${RESULTS[@]}"; do
+    local name="${r%:*}"
+    local status="${r##*:}"
+    if [ "$status" = "pass" ]; then
+      log_info "$name"
+    else
+      log_warn "$name"
+    fi
+  done
+
+  if [ "$keep" -eq 0 ] && [ "$FAILED" -eq 0 ]; then
+    rm -rf "$tmp_dir"
+  else
+    log_info "Kept $tmp_dir"
+  fi
+
+  if [ "$FAILED" -ne 0 ]; then
+    exit 1
+  fi
+}
+
+main "$@"

package/snippets/claude/decision-memo.md

@@ -0,0 +1,39 @@
+Produce a decision memo for a research or should-we question. This is the decision-heavy counterpart to `claude-feature`, which plans a build. Write one file per independent concern under `.claude/plans/feature-<slug>.md`, or answer inline when the plan is small. Use the same plans folder as `claude-feature`.
+
+Read the current state from the code and docs before recommending. Do not assume it.
+
+Output this shape per memo:
+
+```markdown
+# <slug title>
+
+<the question in one or two lines>
+
+## Summary
+
+- <goal in one line>
+- <deliverables in one line>
+- <key tradeoff in one line>
+
+## Finding
+
+<what the current state actually is, from reading the code and docs>
+
+## Item A: <decision>
+
+**Current state.** <what exists today>
+
+**Recommendation.** <the pick, with the tradeoff in one sentence>
+
+**Options.** <the real alternatives, only when the choice is the user's to make>
+
+**Feasibility.** <what is not buildable as asked and why, omit when all options are buildable>
+
+**Questions.**
+
+1. <question>
+   - Suggested: <best-practice default derived from context>
+   - Answer:
+```
+
+Repeat the `## Item` block per decision. Keep chat to the file pointer plus the questions. Recommend, do not enumerate, unless the user's preference is the deciding factor.

package/snippets/claude/feature-recap.md

@@ -0,0 +1,19 @@
+Recap the implementation just completed. Read the plan file referenced in the session (usually `.claude/plans/feature-<slug>.md`) and produce a verification block.
+
+Output this shape, nothing else:
+
+```markdown
+**Deliverable 1**: <name from the plan>
+
+- `path/to/file`: one-line reason
+
+**Deliverable 2**: <name from the plan>
+
+- `path/to/file`: one-line reason
+
+**Verified**: <what was smoke-tested or `Nothing tested in session.`>
+
+**Open**: <unresolved questions, deferred items, or `None.`>
+```
+
+Group files by deliverable, not by directory. Keep each line scannable. Do not restate the plan body.

package/snippets/claude/figma-steps.md

@@ -0,0 +1,18 @@
+Read the relevant spec from `.claude/DESIGN.md` and any other design files needed. Write step-by-step Figma instructions to produce the component exactly.
+
+For each step, specify:
+
+- The exact tool or keyboard shortcut to activate
+- Which panel or field to click
+- The exact value to enter
+
+When a step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
+
+Cover in order:
+
+- Frame or group setup (dimensions, corner radius, fill)
+- Each layer or shape (type, size, position, fill, stroke)
+- Alignment and spacing rules
+- Export settings
+
+Use exact values from the spec. Do not restate design rationale. Use Title Case for all layer and frame names. Use Figma terminology throughout, not code or CSS equivalents. Reuse existing frames or components from the same Figma document by name instead of rebuilding from scratch.

package/snippets/claude/orchestrator-resume.md

@@ -0,0 +1,23 @@
+Resume as orchestrator after a compaction. Read the board and the groundwork behind the live work before answering anything, because a compaction summary keeps conclusions and drops the reasoning that produced them.
+
+1. Resolve the main worktree root with `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, falling back to `pwd`. Every path below resolves against it.
+2. Read `.claude/tasks/priority.md` for the ordering and what each task waits on. Read `.claude/tasks/session.md` when it exists, and treat it as this session's scratch rather than a source.
+3. Read the task file for every entry under `## Run now`, plus any entry a live pull request names.
+4. Read the groundwork folder each of those tasks cites. Read `README.md` for the file map, then `06-decision.md` when the track is closed, or `07-next-session.md` and the numbered topic files when it is open. A task's Findings section is a lossy summary of its track, so planning against the summary re-derives what the folder already settled.
+5. Run `gh pr list --state open` and `git log --oneline -5` to see what shipped since the folder was written.
+6. Report in this shape and stop:
+
+```plaintext
+Read: <task files>, <groundwork folders>
+Shipped since: <commits or PRs>
+Stale in the groundwork: <lean or number the shipped work overturned>
+Next: <the one or two tasks ready to hand a worker>
+```
+
+Treat a groundwork folder as three kinds of content with different shelf lives. Trust the reasoning and the method, which stay correct. Re-measure every count, size, and cost, because they were true when written. Check every `Leaning:` against what has shipped, because work spawned by a track routinely overturns the lean that spawned it and nothing writes back. A plan a live task cites goes stale the same way, and `claude-orchestrate` states the check that catches it.
+
+After each merge, place every finding the work produced before starting anything else. A finding that changes a standard goes to the standard, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. Findings recorded in a pull request thread and nowhere else are lost at merge.
+
+Cite a file and line for any claim taken from a groundwork folder, so a later reader can tell a read from a recall.
+
+Do not read every groundwork folder. Read the ones the live tasks cite. A speculative sweep of the whole folder is the cost this rule exists to bound.

package/snippets/claude/orchestrator-sweep.md

@@ -0,0 +1,10 @@
+Sweep the board as orchestrator after merging. Run this once per batch of merges, before answering what to do next, because the surfaces that record what shipped are the ones nothing updates on its own.
+
+1. Pull into the main worktree rather than fetching. A fetch leaves the local branch behind, so `git log` reports a state that has not arrived. A repository that adds a post-merge hook to name archive candidates gets it on a pull and never on a fetch.
+2. Follow `## Refilling the ready queue` in `claude-orchestrate`, every step in order. It owns the procedure. Do not restate it here and do not run it from memory.
+3. Re-verify every plan already written, not only the ones this sweep writes. A queued plan goes stale from whatever merged while it waited, and the loop's verify step fires at handoff rather than after a merge, so nothing else catches it. Grep each construct the plan names and count the sites against its claim, then open each file rather than trusting its account.
+4. Re-check any precondition a plan states about live state outside the repository. A remote branch, an open issue, or an installed version was true when the plan was written and is not a fact about the tree.
+
+Place every finding the merged work produced before promoting anything. A finding that changes a rule goes to the standard or the rule that states it, one that changes another task goes to that task's Findings, and one that overturns a groundwork lean gets marked answered in that folder. A pull request body counts as nowhere, since the thread stops being read the moment it merges.
+
+Report what closed, what moved, and what is ready to hand a worker. Name the file set each ready task touches, so the reader can check the disjointness claim rather than take it.

package/snippets/compact-summary.md

@@ -0,0 +1,5 @@
+Summarize the research or findings above into a compact, scannable block.
+
+- State the main takeaways directly
+- Skip background context the reader already has
+- Use short headings and tight bullets where multiple items exist

package/snippets/create-snippet.md

@@ -0,0 +1,7 @@
+Draft a new snippet following these conventions:
+
+- Filename is the slug: kebab-case, no capitals, no underscores
+- Plain markdown only, no YAML frontmatter, no headers or nested structure
+- One focused purpose, self-contained with no external file references
+
+Output the slug and the full file content.

package/snippets/decision-help.md

@@ -0,0 +1,6 @@
+Apply senior-level judgment. Pick the best option from the discussion so far. State the pick in one sentence, then the reason and the main tradeoff in one or two sentences.
+
+- Minimal and necessary only
+- No nice-to-haves
+- No padding
+- No alternatives unless they change the recommendation

package/snippets/meta-prompt.md

@@ -0,0 +1,14 @@
+Turn the idea below into a production-grade system prompt.
+
+Give it a role of one to three lines, a constraints section, and an output format carrying a template plus one worked example. Add a validation checklist when the prompt involves multi-step logic, edge cases, or error handling. Omit that checklist for a single-purpose prompt.
+
+Group constraints under domain headings when they span two or more domains and total five or more. Use flat must-do and must-not-do lists otherwise. Keep dos and don'ts together under the topic they belong to.
+
+Use `{{DOUBLE_BRACES}}` for values the end user fills in at runtime.
+
+Constraints:
+
+- Use imperative voice. Write `Do X`, never `You should` or `Try to`.
+- Make every constraint verifiable from the output. Reject subjective qualifiers like `appropriate`, `concise`, or `well-structured`.
+- Match prompt length to task complexity. A single-purpose task gets a minimal prompt.
+- Never write `maybe`, `consider`, or `depending on`. Be definitive.

package/snippets/research-prompt.md

@@ -0,0 +1,7 @@
+Generate a self-contained research prompt for another AI chat. Include:
+
+- State what I am trying to do and why
+- List what I have already tried and the results
+- Specify questions that need answers
+
+Write it in first person. Assume the reader has no context from this session.

package/snippets/session-notes.md

@@ -0,0 +1,11 @@
+Write session notes for this conversation using this format:
+
+```markdown
+# Session notes: <topic>
+
+## <title>
+
+<what was decided and why>
+```
+
+Only include decisions made in this session. Output only the markdown block, nothing else.

package/snippets/snippets.toml

@@ -0,0 +1,6 @@
+[essentials]
+names = [
+    "decision-help",
+    "compact-summary",
+    "step-by-step",
+]

package/snippets/step-by-step.md

@@ -0,0 +1,10 @@
+Give me step-by-step instructions.
+
+For each step:
+
+- State what to do in one sentence.
+- Include the exact value, command, or input where precision matters.
+- Note any output to save or verify before moving on.
+- When the step has multiple sub-actions or lists several items, use nested bullets instead of stacking them in one sentence.
+
+Group related steps under a heading if the process has distinct phases. Flag any step that is irreversible or that blocks later steps.

package/snippets/web-research.md

@@ -0,0 +1,21 @@
+Search the web for the topic or question added after this snippet. Fetch the most relevant pages. Synthesize findings into a decision-ready block using this format:
+
+```markdown
+Topic: [what was researched]
+Recommendation: [one clear answer or choice]
+
+Options considered:
+
+- [Option A]: why considered, why chosen or rejected
+- [Option B]: why considered, why chosen or rejected
+
+Key constraints:
+
+- [constraint that shaped the decision]
+
+Sources:
+
+- [URL]: what it confirmed
+```
+
+Output only the block. Do not add commentary before or after it.