bf (Build Feature)

Why bf?

Most AI coding tools jump straight to writing code. That works for small tasks — but for anything non-trivial, skipping the thinking phase is where bugs, rework, and scope creep come from.

bf enforces a structured workflow between you and Claude: clarify the idea first, produce a spec, review the design for architectural gaps, plan the implementation as a TDD blueprint, execute it, verify tests and lint pass, then open the PR. Each step is a checkpoint — Claude moves forward automatically where it can, and stops for your approval where it matters.

The result: less rework, fewer review surprises, and a paper trail (spec, plan, todo list) that survives context resets.

Three modes:

• Full — for new features: brainstorm → spec → design review → plan → execute → verify → PR
• Quick — for bugfixes and small changes: refine → research → plan → execute → verify → audit → review → PR
• Micro — for focused refactors: clarify only if needed, execute with complexity and quality guards

Also includes a standalone design tool (/bf:design) for producing shareable system design documents — useful before any code is written, or when you need to align with teammates first.

What's inside

Skill	Kind	What it does	When to use
/bf:feature <idea>	Workflow	Full brainstorm → spec → design → plan → execute → verify flow with checkpoints	You have a new idea and want to think it through before touching code
/bf:quick <idea>	Workflow	refine → research → plan → execute → verify → audit → review → finalize; skips only brainstorm and design review	You know roughly what needs doing and just want it done
/bf:micro <idea>	Workflow	Focused refactor with complexity and quality guards	Small, scoped change — one function, one file, clean it up
/bf:bug-fix <symptoms>	Workflow	Parallel root-cause hunt, decide-gated diagnose → fix; no user prompts except a stop for out-of-repo or destructive fixes	Something is broken and you want a fast autonomous fix
/bf:poc <idea>	Workflow	Interview + brainstorm → coherence-checked brief → fast build under dev conventions → smoke run → code/brief sync check; no git, every decision in a BRIEF.md ADR log	You want to prove an idea fast, and keep the decisions in case it becomes the real thing
/bf:autopilot [skill] <args>	Workflow	Runs a core bf workflow (feature, quick, micro, review, design) end-to-end, resolving every decision the wrapped workflow would ask you (setup collisions still prompt)	You want to go fully hands-off — decide oracle handles every decision
/bf:decide <question>	Oracle	Single decisive verdict with rationale — weighs options, picks one, cites evidence	You need a quick call on one thing and trust a single opinion
/bf:discuss <question>	Oracle	Open dialogue to explore a question before committing to a direction	You're not ready to decide yet — you want to think out loud first
/bf:consilium <question>	Oracle	3-critic council: one answers, two challenge from opposing angles, majority wins	The decision is high-stakes or contested and one opinion isn't enough
/bf:design <idea>	Utility	Shareable system-design doc with diagrams, via interactive Q&A	You need a design artifact — standalone, no git or PR involved
/bf:visualize <doc>	Utility	Turns an arch-audit or design doc into an interactive LikeC4 drill-down (context → container → component, plus request-flow views) in one local HTML file	You want to explore a system's structure instead of reading about it
/bf:adr-writer [title]	Utility	Interactive Q&A to draft a numbered ADR citing only tracked source files	You need to record an architecture decision as a real project doc
/bf:review [--focus <lens>] [PR# | files]	Utility	Code review against bf conventions and the complexity gate; --focus (or asking for an angle) runs only that lens's checks	Before merging — or whenever you want a second set of eyes
/bf:coherence [scope]	Utility	Checks whether a change left the code it touched coherent, against the guidelines' breakage kinds	Right after editing existing code — the fast counterpart to /bf:review
/bf:walkthrough [scope]	Utility	Guided read of a finished change — tours the hunks that carried a decision, one at a time, and collects your comments	Right after a build, while you can still say why you did it that way
/bf:arch-audit [scope]	Utility	Descends a repo layer by layer — one round per build unit — into a nested document describing every layer and the structural problems at it	You need to understand how an existing system is built, or where its bottlenecks are
/bf:pr-comments [pr]	Utility	Triages PR review feedback on its merits — fixes the whole class each comment sampled, argues back, or defers, then posts replies and resolutions as one approved batch	A PR has review comments (human or bot) and you want them judged, not obeyed
/bf:gh	Utility	Create, pick, or verify a GitHub issue — verify re-checks an issue's items against the code and hands off what's still open	Starting work from an issue tracker, or checking whether a stale issue is still real
/bf:jira	Utility	Pick a Jira ticket and kick off a workflow	Starting work from Jira
/bf:write-skill [name]	Utility	Author a new bf-style skill from scratch	You want to extend bf with a new skill
/bf:onboard-skill <url> <instructions>	Utility	Fetch an external skill, analyze what to port, adapt to bf conventions, and hand off to bf:write-skill	You want to steal a skill from another plugin and adapt it for bf
/bf:kit <purpose>	Utility	Builds a standalone, git-initialised plugin "kit" for one domain: interviews for its main context, ingests your materials, agrees a skill roster, drafts the skills you pick, and ships write-skill, adopt-skill and update-context so the kit grows itself	You want a separate plugin for a course, role, or recurring kind of work (e.g. a CTO-course kit) instead of adding skills to bf
/bf:self-audit [scope]	Utility	Sweeps every skill, script, and convention for drift, stale references, and token waste, then files the findings as GitHub issues	You want to know what has rotted in the plugin itself — pairs with /bf:self-heal, which fixes what it files
/bf:self-heal [repo | ids]	Utility	Harvests the plugin's own open issues, scores them on token frugality, quality, and speed, argues for the top 3, fixes them, and ships one PR	The backlog has accumulated skill-improvement suggestions and you want the best three paid down in one go
/bf:scan-conventions [task]	Utility	Discovers and filters user-defined custom conventions relevant to the current task.	Before acting on a task where project/user convention files beyond the predefined set might apply
/bf:typesafe [status | on | off]	Utility	Opt-in TypeSafe (System One / Jev) boosting — verifies your API key with a live smoke call, then flips one flag in ~/.bf/config.json	You want typed model judgments backing the places bf currently guesses with regex — entirely optional, bf behaves identically without it
/bf:session-summary	Utility	Summary of what happened this session	End of a work session — capture what changed and why
/bf:gather <feature or PRD>	Utility	Iterative requirements gathering and versioned PRD distillation across sessions	You have a fuzzy PRD and need to track open questions, scope a POC, and build a versioned source of truth
/bf:research <topic>	Utility	Decision-oriented researcher: clarifies usecase → issue → focus, gathers cited evidence, produces an Options + Recommendation report	You need prior art, library comparison, or decision support before building — and want a cited report saved to .bf/research/
/bf:teach <topic>	Utility	Stateful multi-session tutor: mission-grounded HTML lessons, reference docs, learning records, resources, and a glossary in a per-topic workspace, plus an optional learning profile that tailors lesson delivery	You want to deliberately learn a topic over time, not just get a one-off explanation
/bf:onboard-project [role or first task]	Utility	Surveys the repo and generates a complete bf:teach onboarding course in one run — purpose, domain, architecture, stack, running it locally, data, APIs, dependencies, config, testing, delivery, ops, workflow, first task	You just joined a project and want the whole codebase taught end to end, then continued with /bf:teach
/bf:session-lesson [optional focus]	Utility	Mines this session for study topics — tech, or your own repeated English mistakes — and writes one bf:teach lesson with a cheat sheet	At the end of a working session, to keep what it taught you

Workflow scenarios

The table above lists what each skill does on its own. In practice you chain them: one skill's output is the next one's input. Every arrow below is a real handoff. Each skill either offers the next step, or writes an artifact the next skill reads. You type each command; nothing chains silently.

Ship a feature from a vague idea

/bf:research <topic>       cited Options + Recommendation report in .bf/research/
/bf:consilium <question>   3-critic council settles the contested call the report surfaced
/bf:feature <idea>         brainstorm → spec → review-design → plan → [you approve] → execute
                           → verify → audit stack → review → commit, push, PR
/bf:walkthrough            tour the hunks that carried a decision, while you still remember why

Use /bf:decide instead of /bf:consilium when one opinion is enough. Skip research when you already know the prior art.

Align on requirements before anyone writes code

/bf:gather <PRD or idea>   versioned requirements doc, open questions tracked across sessions
/bf:design <feature>       shareable system-design doc with diagrams (no git, no PR)
/bf:visualize <design-doc> optional: interactive drill-down to show the team
/bf:feature <feature>      builds from the settled docs instead of brainstorming from scratch

Choose this when other people have to agree first, or the idea spans more than one session. If you only want to think out loud, use /bf:discuss and go straight to /bf:feature.

Understand an unfamiliar codebase and draw it

/bf:arch-audit [scope]     layer-by-layer document of every build unit, plus structural findings
/bf:visualize <audit-doc>  LikeC4 drill-down (context → container → component), one local HTML file
/bf:adr-writer <title>     record a decision the audit exposed, citing only tracked files
/bf:feature <finding>      act on the finding worth fixing first

arch-audit never edits code, so findings stay comparable. Use /bf:onboard-project instead if the goal is to learn the repo, not to judge it.

Join a new project (or onboard a teammate)

/bf:onboard-project <role or first task>   full course: domain, architecture, stack, run locally, ops…
/bf:teach <slug>                           continue the course: questions, deeper lessons, glossary
/bf:session-lesson                         after a real work session, turn what it taught into a lesson

Hand a teammate the generated workspace. /bf:teach picks up from there. For a single topic rather than a whole repo, start directly with /bf:teach <topic>.

Fix a regression

/bf:bug-fix <symptoms>     parallel root-cause hunt → decide-gated fix → sibling sweep, no prompts
/bf:coherence              did the fix leave the code it touched coherent?
/bf:review                 full pre-merge review; then commit and open the PR yourself

bug-fix stops at a summary and does not commit. If you would rather steer each phase and have the PR opened for you, use /bf:quick <fix>.

Work through PR review feedback

/bf:review --focus security <PR#>   optional: your own focused pass before reviewers arrive
/bf:pr-comments <PR#>               judge every comment: fix the whole class, argue back, or defer.
                                    Contested ones escalate to the council. One approved batch.
/bf:gh                              file the deferred items as an issue so they aren't lost

Use this when comments come from people or bots and some are wrong. Fixing them blindly costs more than triaging them.

Prove an idea before committing to it

/bf:poc <idea>             interview → brief → smallest working build → smoke run; no git
/bf:feature <BRIEF.md>     graduate it: the brief seeds the real feature

Choose this over /bf:feature when the question is "can this work at all?" rather than "how should we build it?".

Pick up a stale issue

/bf:gh                     pick an issue, or verify one: re-checks each item against the code
                           → hands only the still-open items to /bf:quick or /bf:feature
/bf:walkthrough            read back what changed before you merge

Verify first when the issue is old: some items are often already fixed. For a one-file cleanup that doesn't need an issue, /bf:micro <change> runs refactor → guards → PR.

Keep the plugin healthy

/bf:session-summary        end of session; optionally files skill-improvement suggestions as an issue
/bf:self-audit             sweep skills, scripts and conventions for drift; file findings as issues
/bf:self-heal              score the backlog, argue for the top 3, fix them, ship one PR

Run self-audit on a schedule and self-heal whenever the backlog grows. Extending bf is a different job: use /bf:write-skill or /bf:onboard-skill <url>.

Build your own plugin for a domain

/bf:kit <what it's for>          interview → your materials → skill roster → drafted skills, as a
                                 standalone, git-initialised plugin outside bf
/<kit>:update-context <change>   refine its context, or add notes, docs and URLs to its knowledge
/<kit>:write-skill               no argument: draft the next skill from the kit's BACKLOG.md
/<kit>:adopt-skill <url | path>  pull an existing skill into the kit and adapt it

Choose this when the skills serve a subject, such as a course, a role or a recurring kind of work, rather than bf itself. The kit grows on its own afterwards, so extend it with its own skills, not /bf:kit.

Hands-off

Any of feature, quick, micro, review or design can run under /bf:autopilot, for example /bf:autopilot quick fix the flaky retry test. The decide/consilium oracles answer every question the workflow would have asked you, and you read the decisions in the session log afterwards.

Getting started

Add the marketplace

Register the bf marketplace with Claude Code (one-time setup):

/plugin marketplace add fxmaxvl/bf

Install

/plugin install bf@fxmaxvl

Then run /reload-plugins to activate it.

Stay up to date

Turn on auto-update (recommended). Claude Code refreshes marketplaces that have auto-update enabled shortly after a session's first message, and installs any new plugin version it finds. It is off by default for third-party marketplaces like this one, and there is no manifest field that can switch it on for you — each user enables it once:

/plugin → Marketplaces → select fxmaxvl → Enable auto-update

Administrators can set it for a whole fleet instead, with "autoUpdate": true on the extraKnownMarketplaces entry in managed settings.

Update by hand. Without auto-update, pull new versions yourself:

/plugin marketplace update fxmaxvl      # refresh the catalog, in a session
claude plugin update bf@fxmaxvl         # update the plugin, from a shell

A new copy arrives only when the plugin's version changes, so bf bumps version in .claude-plugin/plugin.json on every release.

Uninstall

/plugin uninstall bf@fxmaxvl

Test locally without installing

claude --plugin-dir ./path/to/bf

Conventions

The conventions/ directory contains language- and action-specific guidelines Claude reads before acting:

• guidelines.md — behavioral guardrails; unconditional, applies to every phase of every skill
• dev.md — writing and modifying code
• testing.md — writing and modifying tests
• git.md — commit messages (Conventional Commits)
• architecture.md — architectural decisions
• code-review.md — reviewing code
• typescript.md — TypeScript/JavaScript specifics
• python.md — Python specifics
• verification.md — evidence rules the decide and discuss oracles run on

Overriding conventions: bf supports a 3-level lookup for each convention file (first match wins, fully replaces the plugin default):

1. <project_root>/.bf/conventions/<name>.md — project-local override
2. ~/.bf/conventions/<name>.md — user-global override
3. Plugin default (bundled in conventions/)

To override a convention, create the .bf/conventions/ directory in the appropriate location and drop in files using the same names as above (e.g., dev.md, git.md). A matching file fully replaces the plugin default — there is no merging.

Optional: TypeSafe boosting

bf works fully without this. Skip the section and nothing is missing — no skill requires it, no prompt nags you, and every code path below runs the same deterministic logic it always has.

A few places in bf have to answer a question that regex is genuinely bad at. Today each one guesses with a pattern or a hardcoded list, and each guess has a known failure:

• /bf:self-heal reads a backlog issue as one lump when the body uses neither ### headings nor - ** bullets. Selection and scoring work per item, so an unsplit issue wins or loses whole — and the issues that fail this way are the ones a human wrote, not the ones /bf:self-audit filed.
• /bf:self-audit files false findings from a word list (path, to, foo, your, …) that decides whether some-skill/SKILL.md in a doc is a broken reference or just prose. The list cannot be completed; every false finding becomes a GitHub issue self-heal then pays to reject.
• A quality gate opens silently when a report says **STATUS:** BLOCK instead of STATUS: BLOCK. The grep misses, the caller gets NOT_FOUND, and NOT_FOUND is also what a missing report returns — so nothing distinguishes "clean" from "never ran".
• /bf:autopilot fix the login bug runs the full feature workflow, brainstorm and all, because only an exact first word routes anywhere else.
• /bf:research asks what your prompt already said, and grades its own citations direct/doc/inference with nothing checking the tag against the quote.

Connecting TypeSafe replaces those guesses with typed judgments (yes/no probabilities and single-choice picks, not generated text). The shape is always the same: code enumerates the candidates, the model picks among them, code slices the original text — so a boosted run can pick wrong, but it can never invent content that was not in the source.

export TYPESAFE_API_KEY=...   # in your shell profile
/bf:typesafe on               # smoke-calls the API, then flips one flag
/bf:typesafe off              # back to deterministic, any time

on writes typesafe.enabled to ~/.bf/config.json only if the smoke call answers, so a typo'd key fails loudly at setup instead of silently degrading every later run. The key itself is never written to disk — only the name of the env var holding it.

When boosting is off, unconfigured, rate-limited, or the API is unreachable, every call site falls back to the deterministic path and the run continues. That is a design rule, not a courtesy: a boost that breaks when removed is a dependency, and does not ship. See docs/typesafe-opportunities.md for the call sites and the ones still on the list.

Requirements

• Claude Code
• gh CLI (for /bf:gh and PR creation)
• Jira MCP server configured (for /bf:jira)
• Excalidraw MCP server (optional, for diagrams in /bf:design)
• TypeSafe API key (optional — see TypeSafe boosting)