bstack

Evidence-gated product validation and proportional execution for AI coding agents.

bstack is an independent adaptation of Garry Tan's gstack. It keeps gstack's capable planning, review, QA, browser, security, and shipping tools, but changes the order of operations:

A commercial idea must earn the current execution window before it receives an executable specification or implementation work.

This repository is not an official gstack release and is not affiliated with or endorsed by Garry Tan or Y Combinator.

The bstack name also avoids confusion with the upstream author's separate persistent-knowledge project. That integration is intentionally not included: bstack's decisions, learnings, timelines, and analytics remain local files.

Why this adaptation exists

The original gstack is strong after a direction has been chosen: it can clarify a product, review plans, inspect architecture, test real interfaces, audit security, and ship changes.

This adaptation addresses an earlier failure mode: a high-quality brainstorming session can create momentum before demand, distribution, payment feasibility, opportunity cost, and roadmap fit have been established. Fast AI implementation reduces code-production cost, but it does not remove the cost of building the wrong thing, supporting it, launching it, or delaying better work.

The primary design rule is therefore:

No commercial idea may proceed to detailed planning or implementation until the system records both sufficient evidence that the idea deserves testing and a decision that it is a better use of the current execution window than competing work.

Workflow

CAPTURE → INVESTIGATE → VALIDATE → PRIORITIZE → DECIDE
                                                   │
                                      BUILD NOW only
                                                   ▼
SPECIFY → PLAN PROPORTIONALLY → BUILD THIN SLICE → REVIEW → TEST → SHIP
                                                                      │
                                                                      ▼
                         MEASURE PRODUCT OUTCOME → EXPAND / REVISE /
                                                   MAINTAIN / REMOVE

The four persisted decisions are:

• BUILD NOW — evidence and roadmap fit justify an executable spec.
• VALIDATE FIRST — run exactly one bounded experiment; product implementation stays blocked.
• PARK — save a concrete trigger for reconsideration.
• REJECT — record the primary invalidating reason and close the idea.

Quick start

Requirements:

• Git
• Bun 1.0 or newer
• A supported coding-agent host such as Claude Code or OpenAI Codex

Clone the repository and run setup:

git clone https://github.com/IyedBecheikh/bstack.git ~/.claude/skills/bstack
cd ~/.claude/skills/bstack
./setup

For Codex:

./setup --host codex

Then use the workflow:

/office-hours        # only when the idea is fuzzy
/preflight           # clear commercial idea
/preflight --fast    # known paying-user request
/spec                # only after BUILD NOW
/autoplan            # chooses risk-relevant reviews
/ship                # requires the linked approved decision or an urgent exemption
/measure-outcome     # after the predefined measurement window

Bug fixes, outages, compliance emergencies, broken production behavior, and explicitly non-commercial learning projects can record an exemption from the commercial gate.

/preflight in brief

The new skill is bounded for a solo builder by default:

• At most two focused hours of initial validation unless more is approved.
• At most three focused build days for the default MVP.
• One major build plus one minor maintenance item at a time.
• Stop research when more information is unlikely to change the decision.
• Ask one structured intake plus at most three targeted follow-ups.

It evaluates:

1. The current 30-day objective and explicit budgets.
2. External evidence, including current behavior, paid alternatives, acquisition, platform constraints, payments, regional access, legal/licensing issues, and dependencies.
3. Kill risks across value, distribution, viability, feasibility, and usability.
4. Roadmap displacement: what loses time if this idea is selected.
5. Relative priority and hard blockers.

Evidence level and confidence are deliberately separate:

Level	Evidence standard
0	Personal intuition only
1	Generic discussion or broad market statistics
2	Repeated specific complaints from independent sources
3	Paid competitors, costly workarounds, or measurable current behavior
4	Direct commitment such as a pilot, qualified signup, preorder, or payment attempt
5	Payment, repeated usage, retention, or expansion

A new commercial idea normally cannot receive BUILD NOW below level 3.

What changed from upstream, and why

The clone used for this adaptation was based on upstream commit a3259400.

Area	Change in this repository	Why
/preflight	Added a mandatory commercial decision gate with external evidence, kill risks, priority, hard blockers, roadmap displacement, and four verdicts.	Prevent brainstorming quality or implementation speed from substituting for evidence and opportunity-cost judgment.
Artifact validator	Added lib/preflight-artifact.ts and bin/bstack-preflight-check.ts.	Make the gate fail closed instead of relying on advisory prose.
Artifact schemas	Added JSON Schemas for preflight and product outcomes.	Keep persisted decisions machine-checkable and consistent across hosts.
/office-hours	Reduced it to a bounded idea brief. Removed production architecture, implementation alternatives, full roadmaps, founder-signal scoring, and YC-oriented closing from the commercial path.	Clarify the problem without turning conversation momentum into execution momentum.
/plan-ceo-review	Changed the default order to Reduction → Hold → Selective Expansion → Expansion. Added explicit expansion prerequisites.	Make subtraction and approved learning the default; require evidence and user approval for more scope.
“Boil the Ocean”	Removed from pre-execution skills and replaced with scope-discipline guidance.	AI lowers code-production cost, not wrong-direction, maintenance, support, launch, or opportunity cost.
/spec	Added a required pre-execution block and a validator gate. VALIDATE FIRST can produce only its experiment spec; PARK and REJECT block execution.	Prevent an unapproved idea from becoming implementation-ready through a different entry point.
/autoplan	Changed from a fixed completeness pipeline into a conditional review router.	Avoid full design, DX, security, documentation, or benchmark work when risk and product surface do not justify it.
/ship	Requires commercial work to link to a valid BUILD NOW spec, with a narrow documented bypass for urgent fixes.	Stop downstream shipping from silently bypassing the decision gate.
Proportional execution	Added tiny, normal, and major/high-risk work classes; thin slices; integrated tests; one review by default; targeted QA.	Spend review and QA effort according to consequence and blast radius.
/measure-outcome	Added a separate product-result artifact and EXPAND / REVISE / MAINTAIN / REMOVE decision.	Technical deployment health is necessary but does not prove product success.
/retro	Kept weekly retros and made meaningful milestones explicit; no automatic retro after every small feature.	Preserve reflection without turning small changes into process overhead.
Agent routing	Updated the root router, AGENTS.md, setup welcome, and OpenClaw handoffs.	Ensure implementation agents see the same fail-closed contract.
Tests	Added focused behavioral and workflow-contract tests.	Prove that weak evidence, missing displaced work, blockers, and non-build verdicts cannot become executable.
Branding and metadata	Rebranded the workflow as bstack, updated package metadata, commands, paths, generated skills, and this README.	Avoid presenting the project as the upstream author's official system or confusing it with the separate GBrain project.
Independent operation	Removed GBrain setup/sync, artifact federation, hosted telemetry, community dashboards, Supabase provisioning, Garry-specific operational URLs, and author-persona rules. Kept local decisions, learnings, timelines, analytics, browser QA, design, iOS, PDF, deployment, and the full detailed skill implementations.	Make bstack independently operable without external author-owned services while preserving the original system's mature engineering capabilities and workflow depth.

What remains from gstack

Most downstream capabilities remain available, including:

• Engineering, design, DX, security, and code review skills.
• Browser-based QA and authenticated testing.
• Investigation and root-cause debugging.
• Release, deployment, canary, documentation, and retrospective workflows.
• Multi-host skill generation for Claude Code, Codex, and other supported agents.
• Local cross-session decisions, learnings, timelines, and usage analytics.

Those tools are invoked only after the decision gate when commercial execution is in scope, and only in proportion to the work's risk.

Artifact locations

Preflight decisions are stored under:

$BSTACK_STATE_ROOT/projects/<project-slug>/preflight/

The JSON shape is defined in schemas/preflight.schema.json. The product-result shape is defined in schemas/product-outcome.schema.json.

Validate a decision directly:

bun bin/bstack-preflight-check.ts path/to/PF-YYYYMMDD-slug.json

Exit codes:

• 0 — valid BUILD NOW artifact; execution permitted.
• 1 — validly parsed but execution blocked.
• 2 — missing, unreadable, or malformed artifact.

Development

bun install
bun test test/preexecution-workflow.test.ts
bun run gen:skill-docs --host all
bun run skill:check
bun test

SKILL.md files are generated. Edit SKILL.md.tmpl, then regenerate.

Credit and license

This project is derived from garrytan/gstack, originally created by Garry Tan.

The upstream MIT copyright and permission notice are preserved in LICENSE. Additional attribution and adaptation notes are in NOTICE.md.

Thank you to Garry Tan and all gstack contributors for publishing the original workflow and implementation.