bstack

When to invoke this skill

Commercial ideas pass through bounded clarification, evidence, prioritization, and a persisted verdict before proportional planning and execution.

Preamble (run first)

_UPD=$(~/.claude/skills/bstack/bin/bstack-update-check 2>/dev/null || .claude/skills/bstack/bin/bstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD" || true
mkdir -p ~/.bstack/sessions
touch ~/.bstack/sessions/"$PPID"
_SESSIONS=$(find ~/.bstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
find ~/.bstack/sessions -mmin +120 -type f -exec rm {} + 2>/dev/null || true
_PROACTIVE=$(~/.claude/skills/bstack/bin/bstack-config get proactive 2>/dev/null || echo "true")
_PROACTIVE_PROMPTED=$([ -f ~/.bstack/.proactive-prompted ] && echo "yes" || echo "no")
_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
echo "BRANCH: $_BRANCH"
_SKILL_PREFIX=$(~/.claude/skills/bstack/bin/bstack-config get skill_prefix 2>/dev/null || echo "false")
echo "PROACTIVE: $_PROACTIVE"
echo "PROACTIVE_PROMPTED: $_PROACTIVE_PROMPTED"
echo "SKILL_PREFIX: $_SKILL_PREFIX"
source <(~/.claude/skills/bstack/bin/bstack-repo-mode 2>/dev/null) || true
REPO_MODE=${REPO_MODE:-unknown}
echo "REPO_MODE: $REPO_MODE"
_SESSION_KIND=$(~/.claude/skills/bstack/bin/bstack-session-kind 2>/dev/null || echo "interactive")
case "$_SESSION_KIND" in spawned|headless|interactive) ;; *) _SESSION_KIND="interactive" ;; esac
echo "SESSION_KIND: $_SESSION_KIND"
# Conductor host: AskUserQuestion is unreliable here (native disabled, MCP
# variant flaky), so skills render decisions as prose instead of calling the
# tool. Gated on !headless so an eval/CI run INSIDE Conductor (BSTACK_HEADLESS)
# still BLOCKs rather than rendering prose to nobody.
if [ "$_SESSION_KIND" != "headless" ] && { [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ] || [ -n "${CONDUCTOR_PORT:-}" ]; }; then
  echo "CONDUCTOR_SESSION: true"
fi
_ACTIVATED=$([ -f ~/.bstack/.activated ] && echo "yes" || echo "no")
_FIRST_LOOP_SHOWN=$([ -f ~/.bstack/.first-loop-tip-shown ] && echo "yes" || echo "no")
echo "ACTIVATED: $_ACTIVATED"
echo "FIRST_LOOP_SHOWN: $_FIRST_LOOP_SHOWN"
# First-run project detection: run the detector ONLY on the first-ever skill run
# (ACTIVATED=no, interactive) so it stays off the hot path for every run after.
_FIRST_TASK=""
if [ "$_ACTIVATED" = "no" ] && [ "$_SESSION_KIND" != "headless" ]; then
  _FIRST_TASK=$(~/.claude/skills/bstack/bin/bstack-first-task-detect 2>/dev/null || true)
fi
echo "FIRST_TASK: $_FIRST_TASK"
_LAKE_SEEN=$([ -f ~/.bstack/.completeness-intro-seen ] && echo "yes" || echo "no")
echo "LAKE_INTRO: $_LAKE_SEEN"
_RUN_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
_EXPLAIN_LEVEL=$(~/.claude/skills/bstack/bin/bstack-config get explain_level 2>/dev/null || echo "default")
if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi
echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL"
_QUESTION_TUNING=$(~/.claude/skills/bstack/bin/bstack-config get question_tuning 2>/dev/null || echo "false")
echo "QUESTION_TUNING: $_QUESTION_TUNING"
mkdir -p ~/.bstack/analytics
echo '{"skill":"bstack","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}'  >> ~/.bstack/analytics/skill-usage.jsonl 2>/dev/null || true
for _PF in $(find ~/.bstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do
  if [ -f "$_PF" ]; then
    rm -f "$_PF" 2>/dev/null || true
  fi
  break
done
eval "$(~/.claude/skills/bstack/bin/bstack-slug 2>/dev/null)" 2>/dev/null || true
_LEARN_FILE="${BSTACK_HOME:-$HOME/.bstack}/projects/${SLUG:-unknown}/learnings.jsonl"
if [ -f "$_LEARN_FILE" ]; then
  _LEARN_COUNT=$(wc -l < "$_LEARN_FILE" 2>/dev/null | tr -d ' ')
  echo "LEARNINGS: $_LEARN_COUNT entries loaded"
  if [ "$_LEARN_COUNT" -gt 5 ] 2>/dev/null; then
    ~/.claude/skills/bstack/bin/bstack-learnings-search --limit 3 2>/dev/null || true
  fi
else
  echo "LEARNINGS: 0"
fi
~/.claude/skills/bstack/bin/bstack-timeline-log '{"skill":"bstack","event":"started","branch":"'"$_BRANCH"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null &
_HAS_ROUTING="no"
if [ -f CLAUDE.md ] && grep -q "## Skill routing" CLAUDE.md 2>/dev/null; then
  _HAS_ROUTING="yes"
fi
_ROUTING_DECLINED=$(~/.claude/skills/bstack/bin/bstack-config get routing_declined 2>/dev/null || echo "false")
echo "HAS_ROUTING: $_HAS_ROUTING"
echo "ROUTING_DECLINED: $_ROUTING_DECLINED"
_VENDORED="no"
if [ -d ".claude/skills/bstack" ] && [ ! -L ".claude/skills/bstack" ]; then
  if [ -f ".claude/skills/bstack/VERSION" ] || [ -d ".claude/skills/bstack/.git" ]; then
    _VENDORED="yes"
  fi
fi
echo "VENDORED_BSTACK: $_VENDORED"
echo "MODEL_OVERLAY: claude"
_CHECKPOINT_MODE=$(~/.claude/skills/bstack/bin/bstack-config get checkpoint_mode 2>/dev/null || echo "explicit")
_CHECKPOINT_PUSH=$(~/.claude/skills/bstack/bin/bstack-config get checkpoint_push 2>/dev/null || echo "false")
echo "CHECKPOINT_MODE: $_CHECKPOINT_MODE"
echo "CHECKPOINT_PUSH: $_CHECKPOINT_PUSH"
# Plan-mode hint for skills like /spec that branch behavior on plan-mode state.
# Claude Code exposes plan mode via system reminders; we detect best-effort
# from CLAUDE_PLAN_FILE (set by the harness when plan mode is active) and
# fall back to "inactive". Codex hosts and Claude execution mode both end up
# inactive, which is the safe default (defaults to file+execute pipeline).
if [ -n "${CLAUDE_PLAN_FILE:-}${BSTACK_PLAN_MODE_FORCE:-}" ]; then
  export BSTACK_PLAN_MODE="active"
elif [ "${BSTACK_PLAN_MODE:-}" = "active" ]; then
  export BSTACK_PLAN_MODE="active"
else
  export BSTACK_PLAN_MODE="inactive"
fi
echo "BSTACK_PLAN_MODE: $BSTACK_PLAN_MODE"
[ -n "$OPENCLAW_SESSION" ] && echo "SPAWNED_SESSION: true" || true

Plan Mode Safe Operations

In plan mode, allowed because they inform the plan: $B, $D, codex exec/codex review, writes to ~/.bstack/, writes to the plan file, and open for generated artifacts.

Skill Invocation During Plan Mode

If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. Treat the skill file as executable instructions, not reference. Follow it step by step starting from Step 0; the first AskUserQuestion is the workflow entering plan mode, not a violation of it. AskUserQuestion (any variant — mcp__*__AskUserQuestion or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: headless → BLOCKED; interactive → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode.

If PROACTIVE is "false", do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?"

If SKILL_PREFIX is "true", suggest/invoke /bstack-* names. Disk paths stay ~/.claude/skills/bstack/[skill-name]/SKILL.md.

If output shows UPGRADE_AVAILABLE <old> <new>: read ~/.claude/skills/bstack/bstack-upgrade/SKILL.md and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined).

If output shows JUST_UPGRADED <from> <to>: print "Running bstack v{to} (just updated!)". If SPAWNED_SESSION is true, skip feature discovery.

Feature discovery, max one prompt per session:

• Missing ~/.claude/skills/bstack/.feature-prompted-continuous-checkpoint: AskUserQuestion for Continuous checkpoint auto-commits. If accepted, run ~/.claude/skills/bstack/bin/bstack-config set checkpoint_mode continuous. Always touch marker.
• Missing ~/.claude/skills/bstack/.feature-prompted-model-overlay: inform "Model overlays are active. MODEL_OVERLAY shows the patch." Always touch marker.

After upgrade prompts, continue workflow.

If WRITING_STYLE_PENDING is yes: ask once about writing style:

v1 prompts are simpler: first-use jargon glosses, outcome-framed questions, shorter prose. Keep default or restore terse?

Options:

• A) Keep the new default (recommended — good writing helps everyone)
• B) Restore V0 prose — set explain_level: terse

If A: leave explain_level unset (defaults to default). If B: run ~/.claude/skills/bstack/bin/bstack-config set explain_level terse.

Always run (regardless of choice):

rm -f ~/.bstack/.writing-style-prompt-pending
touch ~/.bstack/.writing-style-prompted

Skip if WRITING_STYLE_PENDING is no.

If LAKE_INTRO is no: say "bstack uses Proportional Completeness: fully cover the approved scope, including tests, edge cases, and error paths, without expanding into unrelated work."

touch ~/.bstack/.completeness-intro-seen

Always run touch after showing the one-time explanation.

If PROACTIVE_PROMPTED is no AND TEL_PROMPTED is yes: ask once:

Let bstack proactively suggest skills, like /qa for "does this work?" or /investigate for bugs?

Options:

• A) Keep it on (recommended)
• B) Turn it off — I'll type /commands myself

If A: run ~/.claude/skills/bstack/bin/bstack-config set proactive true If B: run ~/.claude/skills/bstack/bin/bstack-config set proactive false

Always run:

touch ~/.bstack/.proactive-prompted

Skip if PROACTIVE_PROMPTED is yes.

First-run guidance (one-time)

If ACTIVATED is no (first skill run on this machine) AND the preamble printed a non-empty FIRST_TASK: value that is NOT nongit: show ONE short, project-specific line mapped from the token, as a heads-up, then CONTINUE with whatever the user actually asked — do NOT halt their task. Map the token: greenfield → "Fresh commercial idea? Clarify it with /office-hours, then decide with /preflight before /spec." code_node/code_python/code_rust/code_go/code_ruby/code_ios → "There's code here — use /preflight for new commercial work, /qa for existing behavior, or /investigate for bugs." branch_ahead → "Unshipped work on this branch — /review then /ship." dirty_default → "Uncommitted changes — /review before committing." clean_default → "For new commercial work start with /preflight; otherwise choose /investigate or /qa." Then substitute the token you saw for TASK_TOKEN and run (best-effort), and mark activated:

~/.claude/skills/bstack/bin/bstack-timeline-log '{"skill":"first-task","event":"completed","outcome":"shown","task":"TASK_TOKEN"}' 2>/dev/null || true
touch ~/.bstack/.activated 2>/dev/null || true

If ACTIVATED is no but FIRST_TASK: is empty or nongit (headless, non-git, or nothing actionable): show nothing, just run touch ~/.bstack/.activated 2>/dev/null || true.

Else if ACTIVATED is yes AND FIRST_LOOP_SHOWN is no: say once as a heads-up (then continue):

Tip: bstack pays off when you complete one loop — clarify → decide → execute proportionally → measure. For commercial work: /office-hours when fuzzy, /preflight for the gate, /spec only after BUILD NOW, then /measure-outcome.

Then run touch ~/.bstack/.first-loop-tip-shown 2>/dev/null || true.

Skip this section if ACTIVATED and FIRST_LOOP_SHOWN are both yes.

If HAS_ROUTING is no AND ROUTING_DECLINED is false AND PROACTIVE_PROMPTED is yes: Check if a CLAUDE.md file exists in the project root. If it does not exist, create it.

Use AskUserQuestion:

bstack works best when your project's CLAUDE.md includes skill routing rules.

Options:

• A) Add routing rules to CLAUDE.md (recommended)
• B) No thanks, I'll invoke skills manually

If A: Append this section to the end of CLAUDE.md:

## Skill routing

When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.

Key routing rules:
- Fuzzy commercial ideas/brainstorming → invoke /office-hours, then /preflight
- Clear commercial ideas or roadmap candidates → invoke /preflight
- Strategy/scope after BUILD NOW → invoke /plan-ceo-review
- Architecture → invoke /plan-eng-review
- Design system/plan review → invoke /design-consultation or /plan-design-review
- Conditional review and execution pipeline → invoke /autoplan only after BUILD NOW
- Bugs/errors → invoke /investigate
- QA/testing site behavior → invoke /qa or /qa-only
- Code review/diff check → invoke /review
- Visual polish → invoke /design-review
- Ship/deploy/PR → invoke /ship or /land-and-deploy
- Save progress → invoke /context-save
- Resume context → invoke /context-restore
- Author a backlog-ready commercial spec/issue → invoke /spec only after BUILD NOW
- Measure a shipped product outcome → invoke /measure-outcome

Leave the change uncommitted so the user can review and commit it with the rest of their project changes.

If B: run ~/.claude/skills/bstack/bin/bstack-config set routing_declined true and say they can re-enable with bstack-config set routing_declined false.

This only happens once per project. Skip if HAS_ROUTING is yes or ROUTING_DECLINED is true.

If VENDORED_BSTACK is yes, warn once via AskUserQuestion unless ~/.bstack/.vendoring-warned-$SLUG exists:

This project has bstack vendored in .claude/skills/bstack/. Vendoring is deprecated. Migrate to team mode?

Options:

• A) Yes, migrate to team mode now
• B) No, I'll handle it myself

If A:

1. Run git rm -r .claude/skills/bstack/
2. Run echo '.claude/skills/bstack/' >> .gitignore
3. Run ~/.claude/skills/bstack/bin/bstack-team-init required (or optional)
4. Run git add .claude/ .gitignore CLAUDE.md && git commit -m "chore: migrate bstack from vendored to team mode"
5. Tell the user: "Done. Each developer now runs: cd ~/.claude/skills/bstack && ./setup --team"

If B: say "OK, you're on your own to keep the vendored copy up to date."

Always run (regardless of choice):

eval "$(~/.claude/skills/bstack/bin/bstack-slug 2>/dev/null)" 2>/dev/null || true
touch ~/.bstack/.vendoring-warned-${SLUG:-unknown}

If marker exists, skip.

If SPAWNED_SESSION is "true", you are running inside a session spawned by an AI orchestrator (e.g., OpenClaw). In spawned sessions:

• Do NOT use AskUserQuestion for interactive prompts. Auto-choose the recommended option.
• Do NOT run upgrade checks, routing injection, or lake intro.
• Focus on completing the task and reporting results via prose output.
• End with a completion report: what shipped, decisions made, anything uncertain.

Model-Specific Behavioral Patch (claude)

The following nudges are tuned for the claude model family. They are subordinate to skill workflow, STOP points, AskUserQuestion gates, plan-mode safety, and /ship review gates. If a nudge below conflicts with skill instructions, the skill wins. Treat these as preferences, not rules.

Todo-list discipline. When working through a multi-step plan, mark each task complete individually as you finish it. Do not batch-complete at the end. If a task turns out to be unnecessary, mark it skipped with a one-line reason.

Think before heavy actions. For complex operations (refactors, migrations, non-trivial new features), briefly state your approach before executing. This lets the user course-correct cheaply instead of mid-flight.

Dedicated tools over Bash. Prefer Read, Edit, Write, Glob, Grep over shell equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer.

Voice

Direct, concrete, builder-to-builder. Name the file, function, command, and user-visible impact. No filler.

No em dashes. No AI vocabulary: delve, crucial, robust, comprehensive, nuanced, multifaceted. Never corporate or academic. Short paragraphs. End with what to do.

The user has context you do not. Cross-model agreement is a recommendation, not a decision. The user decides.

Completion Status Protocol

When completing a skill workflow, report status using one of:

• DONE — completed with evidence.
• DONE_WITH_CONCERNS — completed, but list concerns.
• BLOCKED — cannot proceed; state blocker and what was tried.
• NEEDS_CONTEXT — missing info; state exactly what is needed.

Escalate after 3 failed attempts, uncertain security-sensitive changes, or scope you cannot verify. Format: STATUS, REASON, ATTEMPTED, RECOMMENDATION.

Operational Self-Improvement

Before completing, if you discovered a durable project quirk or command fix that would save 5+ minutes next time, log it:

~/.claude/skills/bstack/bin/bstack-learnings-log '{"skill":"SKILL_NAME","type":"operational","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"observed"}'

Do not log obvious facts or one-time transient errors.

Local run history (run last)

After workflow completion, record local run history. Use skill name: from frontmatter. OUTCOME is success/error/abort/unknown. These records stay under ~/.bstack/ and are never uploaded by bstack.

Run this bash:

_RUN_END=$(date +%s)
_RUN_DUR=$(( _RUN_END - _RUN_START ))
rm -f ~/.bstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
~/.claude/skills/bstack/bin/bstack-timeline-log '{"skill":"SKILL_NAME","event":"completed","branch":"'$(git branch --show-current 2>/dev/null || echo unknown)'","outcome":"OUTCOME","duration_s":"'"$_RUN_DUR"'","session":"'"$_SESSION_ID"'"}' 2>/dev/null || true
echo '{"skill":"SKILL_NAME","duration_s":"'"$_RUN_DUR"'","outcome":"OUTCOME","browse":"USED_BROWSE","session":"'"$_SESSION_ID"'","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' >> ~/.bstack/analytics/skill-usage.jsonl 2>/dev/null || true

Replace SKILL_NAME, OUTCOME, and USED_BROWSE before running.

Plan Status Footer## Plan Status Footer

Skills that run plan reviews (/plan-*-review, /codex review) include the EXIT PLAN MODE GATE blocking checklist at the end of the skill, which verifies the plan file ends with ## BSTACK REVIEW REPORT before ExitPlanMode is called. Skills that don't run plan reviews (operational skills like /ship, /qa, /review) typically don't operate in plan mode and have no review report to verify; this footer is a no-op for them. Writing the plan file is the one edit allowed in plan mode.

Route first

This is the bstack router. Its one job is to send the request to the right skill.

1. If the request is about a browser, QA, dogfooding, screenshots, or inspecting a page (open a site, test a deploy, take a screenshot, check a flow visually) → invoke /browse.
2. Otherwise, route by the rules below. If nothing matches, answer directly.

Best-effort, record which way you routed (never block on it). Set ROUTE_OUTCOME to browse (sent to /browse), routed (sent to another skill), or direct (answered directly, no skill matched):

If PROACTIVE is false: do NOT proactively invoke or suggest other bstack skills during this session. Only run skills the user explicitly invokes. This preference persists across sessions via bstack-config.

If PROACTIVE is true (default): invoke the Skill tool when the user's request matches a skill's purpose. Do NOT answer directly when a skill exists for the task. Use the Skill tool to invoke it. The skill has specialized workflows, checklists, and quality gates that produce better results than answering inline.

Routing rules — when you see these patterns, INVOKE the skill via the Skill tool:

• User describes a fuzzy commercial idea or wants to clarify the problem → invoke /office-hours, then /preflight
• User describes a clear commercial idea, asks "is this worth building now", or wants prioritization → invoke /preflight
• User has a paying-user request → invoke /preflight --fast
• User asks to spec commercial work → require BUILD NOW, then invoke /spec
• User asks about strategy or scope on approved work → invoke /plan-ceo-review
• User asks to review architecture, lock in the plan, "does this design make sense" → invoke /plan-eng-review
• User asks about design system, brand, visual identity, "how should this look" → invoke /design-consultation
• User asks to review design of a plan → invoke /plan-design-review
• User asks about developer experience of a plan, API/CLI/SDK design → invoke /plan-devex-review
• User wants all reviews done automatically, "review everything" → invoke /autoplan
• User reports a bug, error, broken behavior, "why is this broken", "this doesn't work", "wtf", "something's wrong" → invoke /investigate
• User asks to test the site, find bugs, QA, "does this work", "check the deploy" → invoke /qa
• User asks to just report bugs without fixing → invoke /qa-only
• User asks to review code, check the diff, pre-landing review, "look at my changes" → invoke /review
• User asks about visual polish, design audit of a live site, "this looks off" → invoke /design-review
• User asks to audit the live developer experience, time-to-hello-world → invoke /devex-review
• User asks to ship, deploy, push, create a PR, "let's land this", "send it" → invoke /ship
• User asks to merge + deploy + verify as one flow → invoke /land-and-deploy
• User asks to configure deployment for the project → invoke /setup-deploy
• User asks to monitor prod after shipping, post-deploy checks → invoke /canary
• User asks whether a measured release achieved its product outcome → invoke /measure-outcome
• User asks to update docs after shipping → invoke /document-release
• User asks to write docs from scratch, generate documentation, "document this feature/module" → invoke /document-generate
• User asks for a weekly retro, what did we ship, "how'd we do" → invoke /retro
• User asks for a second opinion, codex review → invoke /codex
• User asks for safety mode, careful mode → invoke /careful or /guard
• User asks to restrict edits to a directory → invoke /freeze or /unfreeze
• User asks to upgrade bstack → invoke /bstack-upgrade
• User asks to save progress, checkpoint, "save my work" → invoke /context-save
• User asks to resume, restore, "where was I" → invoke /context-restore
• User asks about security, OWASP, vulnerabilities, "is this secure" → invoke /cso
• User asks to make a PDF, document, publication → invoke /make-pdf
• User asks to launch a real browser for QA, "open the browser" → invoke /open-bstack-browser
• User asks to import cookies for authenticated testing → invoke /setup-browser-cookies
• User asks about page speed, performance regression, benchmarks → invoke /benchmark
• User asks what bstack has learned, "show learnings" → invoke /learn
• User asks to tune question sensitivity, "stop asking me that" → invoke /plan-tune
• User asks for code quality dashboard, "health check" → invoke /health

When in doubt, invoke the skill. A false positive (invoking a skill that wasn't needed) is cheaper than a false negative (answering ad-hoc when a structured workflow exists). The skill provides multi-step workflows, checklists, and quality gates that always produce better results than an ad-hoc answer. If no skill matches, answer directly as usual.

If the user opts out of suggestions, run bstack-config set proactive false. If they opt back in, run bstack-config set proactive true.