IyedBecheikhIyedBecheikh/bstack/AGENTS.md

bstack

AGENTS.md1 starsChanged 4 months agoMITView on GitHub

bstack is an evidence-gated AI engineering workflow. It is a collection of SKILL.md files that give AI agents structured roles for software development. Each skill is a specialist: CEO reviewer, eng manager, designer, QA lead, release engineer, debugger, and more. There are currently no scoped AGENTS.md files. If one is added later, the closest AGENTS.md wins for files in its subtree; that precedence overrides this root file where the instructions conflict. - New commercial idea or roadmap-level paid feature: run…

Deletes or force-pushes

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,843 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository57 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- model-overlays/claude.mdCLAUDE.md
- bstack/llms.txtllms.txt
- autoplanSkill
- benchmark-modelsSkill
- benchmarkSkill
- browseSkill
- bstack-upgradeSkill
- canarySkill
- carefulSkill
- codexSkill
- context-restoreSkill
- context-saveSkill
- csoSkill
- design-consultationSkill
- design-htmlSkill
- design-reviewSkill
- design-shotgunSkill
- devex-reviewSkill
- diagramSkill
- document-generateSkill
- document-releaseSkill
- freezeSkill
- guardSkill
- healthSkill
- investigateSkill
- ios-cleanSkill
- ios-design-reviewSkill
- ios-fixSkill
- ios-qaSkill
- ios-syncSkill
- land-and-deploySkill
- landing-reportSkill
- learnSkill
- make-pdfSkill
- measure-outcomeSkill
- office-hoursSkill
- open-bstack-browserSkill
- pair-agentSkill
- plan-ceo-reviewSkill
- plan-design-reviewSkill
- plan-devex-reviewSkill
- plan-eng-reviewSkill
- plan-tuneSkill
- preflightSkill
- qa-onlySkill
- qaSkill
- retroSkill
- reviewSkill
- scrapeSkill
- setup-browser-cookiesSkill
- setup-deploySkill
- shipSkill
- skillifySkill
- bstackSkill
- specSkill
- unfreezeSkill

The file

We split this AGENTS.md into the rules it gives an agent

2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Only a COMPLETE BUILD_NOW artifact permits an executable /spec, /autoplan, product-code edits, worktree creation, or /ship.
line 21
Very specific:
Run bun run gen:skill-docs --host codex to regenerate Codex-specific output.
line 155

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

bstack — AI Engineering Workflow

Index of scoped AGENTS.md

There are currently no scoped AGENTS.md files. If one is added later, the closest AGENTS.md wins for files in its subtree; that precedence overrides this root file where the instructions conflict.

Pre-execution contract

New commercial idea or roadmap-level paid feature: run /preflight.
Fuzzy commercial idea: run /office-hours, then /preflight.
Paying-user request: run /preflight --fast.
Only a COMPLETE BUILD_NOW artifact permits an executable /spec, /autoplan, product-code edits, worktree creation, or /ship.
VALIDATE_FIRST permits only its one recorded experiment.
PARK and REJECT block implementation.
Obvious bugs, outages, compliance emergencies, broken production behavior, and explicitly non-commercial learning work may record an exemption.
Scope beyond approved budgets or non-goals requires reduction or a new preflight.

Available skills

Skills live in .agents/skills/ (or ~/.claude/skills/bstack/ on Claude Code). Invoke them by name (e.g., /office-hours).

Plan-mode reviews

Skill	What it does
`/office-hours`	Start here. Reframes your product idea before you write code.
`/preflight`	Validate evidence, kill risks, roadmap displacement, and one of four verdicts.
`/plan-ceo-review`	CEO-level review: find the 10-star product in the request.
`/plan-eng-review`	Lock architecture, data flow, edge cases, and tests.
`/plan-design-review`	Rate each design dimension 0-10, explain what a 10 looks like.
`/plan-devex-review`	DX-mode review: TTHW, magical moments, friction points, persona traces.
`/plan-tune`	Self-tune AskUserQuestion sensitivity per question.
`/autoplan`	Conditional router that runs only risk-relevant reviews after BUILD NOW.
`/design-consultation`	Build a complete design system from scratch.
`/spec`	Turn vague intent into a precise, executable spec in five phases. Files a GitHub issue, optionally spawns a Claude Code agent in a fresh worktree, and lets `/ship` close the source issue on merge.

Implementation + review

Skill	What it does
`/review`	Pre-landing PR review. Finds bugs that pass CI but break in prod.
`/codex`	Second opinion via OpenAI Codex. Review, challenge, or consult modes.
`/investigate`	Systematic root-cause debugging. No fixes without investigation.
`/design-review`	Live-site visual audit + fix loop with atomic commits.
`/design-shotgun`	Generate multiple AI design variants, comparison board, iterate.
`/design-html`	Generate production-quality Pretext-native HTML/CSS.
`/devex-review`	Live developer experience audit (TTHW measured against the real flow).
`/qa`	Open a real browser, find bugs, fix them, re-verify.
`/qa-only`	Same methodology as /qa but report only — no code changes.
`/scrape`	Pull data from a web page. First call prototypes; codified call runs in ~200ms.
`/skillify`	Codify the most recent successful `/scrape` flow into a permanent browser-skill.

Release + deploy

Skill	What it does
`/ship`	Run tests, review, push, open PR. Workspace-aware version queue.
`/land-and-deploy`	Merge the PR, wait for CI and deploy, verify production health.
`/canary`	Post-deploy monitoring loop using the browse daemon.
`/measure-outcome`	Compare observed product results to the predeclared metric and decide next action.
`/landing-report`	Read-only dashboard for the workspace-aware ship queue.
`/document-release`	Update all docs to match what you just shipped.
`/document-generate`	Generate Diataxis docs (tutorial / how-to / reference / explanation) from code.
`/setup-deploy`	One-time deploy config detection (Fly.io, Render, Vercel, etc.).
`/bstack-upgrade`	Update bstack to the latest version.

Operational + memory

Skill	What it does
`/context-save`	Save working context (git state, decisions, remaining work).
`/context-restore`	Resume from a saved context, even across Conductor workspaces.
`/learn`	Manage what bstack learned across sessions.
`/retro`	Weekly retro with per-person breakdowns and shipping streaks.
`/health`	Code quality dashboard (type checker, linter, tests, dead code).
`/benchmark`	Performance regression detection (page load, Core Web Vitals).
`/benchmark-models`	Cross-model benchmark for skills (Claude, GPT, Gemini side-by-side).
`/cso`	OWASP Top 10 + STRIDE security audit.

Browser + agent integration

Skill	What it does
`/browse`	Headless browser — real Chromium, real clicks, ~100ms/command.
`/open-bstack-browser`	Launch the visible BStack Browser with sidebar + stealth.
`/setup-browser-cookies`	Import cookies from your real browser for authenticated testing.
`/pair-agent`	Pair a remote AI agent (OpenClaw, Codex, etc.) with your browser.

iOS QA — drive real iPhones over USB or Tailscale (v1.43.0.0+)

Skill	What it does
`/ios-qa`	Live-device iOS QA via USB CoreDevice tunnel + embedded StateServer. Optionally exposes the device over Tailscale so remote agents can drive it.
`/ios-fix`	Autonomous iOS bug fixer with regression snapshot capture.
`/ios-design-review`	Designer's-eye QA on a real iPhone — 10-dimension Apple HIG rubric.
`/ios-clean`	Convenience: strip DebugBridge + #if DEBUG wiring before a Release build.
`/ios-sync`	Regenerate the iOS debug bridge against the latest upstream templates.

Companion CLIs (run on the Mac that's plugged into the device):

Command	What it does
`bstack-ios-qa-daemon`	Mac-side broker. Loopback by default; `--tailnet` adds a Tailscale-facing listener with capability tiers and audit logging.
`bstack-ios-qa-mint`	Owner-grant CLI for the tailnet allowlist (`grant`/`revoke`/`list`).
`bstack-ios-qa-regen`	Regenerate the canonical local DebugBridge package and typed accessors (`--app-source` / `--bridge-dir`).

End-to-end walkthrough: docs/howto-ios-testing-with-bstack.md.

Safety + scoping

Skill	What it does
`/careful`	Warn before destructive commands (rm -rf, DROP TABLE, force-push).
`/freeze`	Lock edits to one directory. Hard block, not just a warning.
`/guard`	Activate both careful + freeze at once.
`/unfreeze`	Remove directory edit restrictions.
`/make-pdf`	Turn any markdown file into a publication-quality PDF.
`/diagram`	English in, diagram out: mermaid source + editable .excalidraw + SVG/PNG, offline.

Build commands

bun install              # install dependencies
bun test                 # run free tests (no API spend)
bun run test:windows     # curated Windows-safe subset (runs on windows-latest)
bun run build            # generate docs + compile binaries
bun run gen:skill-docs   # regenerate SKILL.md files from templates
bun run skill:check      # health dashboard for all skills

Platform support

macOS + Linux: full test suite supported.
Windows: curated Windows-safe subset runs on windows-latest via the windows-free-tests CI job. Setup script (./setup) requires Git Bash or MSYS today; native PowerShell support is a future expansion. The bin/bstack-paths helper resolves state roots through CLAUDE_PLUGIN_DATA / BSTACK_HOME so plugin installs work on every platform.

Key conventions

SKILL.md files are generated from .tmpl templates. Edit the template, not the output.
Run bun run gen:skill-docs --host codex to regenerate Codex-specific output.
The browse binary provides headless browser access. Use $B <command> in skills.
Safety skills (careful, freeze, guard) use inline advisory prose — always confirm before destructive operations.
State paths resolve via bin/bstack-paths (sourced via eval "$(...)"). Honors BSTACK_HOME, CLAUDE_PLUGIN_DATA, CLAUDE_PLANS_DIR.
The claude CLI binary resolves via browse/src/claude-bin.ts (Bun.which() + BSTACK_CLAUDE_BIN override). Set BSTACK_CLAUDE_BIN=wsl plus BSTACK_CLAUDE_BIN_ARGS='["claude"]' to run Claude through WSL on Windows.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free