From building-in-the-open
Routes documentation requests to the right writing skill and configures bito quality gates — path-based lint rules, tokenizer backends, dialect enforcement, and MCP server setup. Use when asked to write docs, set up documentation tooling, configure quality gates, produce a README, or when the documentation type is ambiguous.
npx claudepluginhub claylo/building-in-the-open --plugin building-in-the-openThis skill is limited to using the following tools:
This is the entry point for the building-in-the-open plugin. If you know exactly what artifact to produce, use the specific skill directly. If the request is ambiguous ("write docs", "set up documentation", "configure quality gates"), start here.
Implements Playwright E2E testing patterns: Page Object Model, test organization, configuration, reporters, artifacts, and CI/CD integration for stable suites.
Guides Next.js 16+ Turbopack for faster dev via incremental bundling, FS caching, and HMR; covers webpack comparison, bundle analysis, and production builds.
Discovers and evaluates Laravel packages via LaraPlugins.io MCP. Searches by keyword/feature, filters by health score, Laravel/PHP compatibility; fetches details, metrics, and version history.
This is the entry point for the building-in-the-open plugin. If you know exactly what artifact to produce, use the specific skill directly. If the request is ambiguous ("write docs", "set up documentation", "configure quality gates"), start here.
| User wants... | Use this skill |
|---|---|
| Capture session context for the next person/agent | curating-context (handoff) |
| Record a technical decision | capturing-decisions |
| Formalize a design before or during implementation | writing-design-docs |
| Write tutorials, guides, or API references for end users | writing-end-user-docs |
| Produce CHANGELOG entries or release announcements | writing-changelogs |
| Review an artifact before committing | editorial-review |
| Set up quality gates for the first time | Run bash ${CLAUDE_PLUGIN_ROOT}/skills/building-in-the-open/scripts/scaffold-config.sh to drop a .bito.yaml in the project root |
| Configure or troubleshoot bito | Continue below |
The plugin's quality gates run through bito. Without it, skills still produce artifacts, but nothing is measured.
cargo binstall bito # pre-built binary, fastest
brew install claylo/brew/bito # macOS / Linux
npm install -g @claylo/bito # wraps the native binary
Verify: bito doctor
The plugin ships a template at ${CLAUDE_PLUGIN_ROOT}/defaults/bito.yaml with rules pre-wired for handoffs, ADRs, designs, and general docs. Drop it into a project with:
bash ${CLAUDE_PLUGIN_ROOT}/skills/building-in-the-open/scripts/scaffold-config.sh
Behavior:
.bito.yaml / .bito.toml / .bito.json (or .bito-lint.*) already exists. Pass --force to overwrite..config/bito.yaml if a .config/ directory exists, otherwise .bito.yaml at the project root.DIALECT (en-us), DOC_OUTPUT_DIR (record), MAX_GRADE (12.0), PASSIVE_MAX_PERCENT (15.0). The CLAUDE_PLUGIN_OPTION_* equivalents are also accepted.Edit the generated file afterwards — it's a starting point, not a permanent contract.
bito discovers config files by walking up from the current directory to the nearest .git boundary. Supported names: .bito.yaml, .bito.toml, .bito.json (also .bito-lint.* for backwards compatibility).
# .bito.yaml — project-wide defaults (all fields optional)
dialect: en-us # en-us | en-gb | en-ca | en-au — spelling enforcement
token_budget: 2000 # default budget for `bito tokens`
max_grade: 12.0 # default Flesch-Kincaid ceiling for `bito readability`
passive_max_percent: 15.0 # max passive voice % for `bito grammar`
style_min_score: 70 # min style score for `bito analyze`
tokenizer: claude # claude (conservative, overcounts ~4%) | openai (exact cl100k_base)
# Custom completeness templates beyond the built-in adr, handoff, design-doc
templates:
runbook: ["## Overview", "## Prerequisites", "## Steps", "## Rollback"]
Discovery order (highest precedence first):
--config <path> CLI flag.bito.yaml / .bito.toml / .bito.json (or .bito-lint.*) in current or ancestor directory (up to .git boundary)~/.config/bito/config.toml (user-level defaults)Environment variable overrides — any field can be set via BITO_ prefix:
BITO_DIALECT=en-gb
BITO_TOKEN_BUDGET=3000
BITO_TOKENIZER=openai
Instead of hardcoding check logic in hook scripts, declare what checks run on what files in your config. The rules array maps glob patterns to checks with per-rule settings:
# .bito.yaml
rules:
- paths: [".handoffs/*.md"]
checks:
completeness:
template: handoff
tokens:
budget: 2000
grammar:
passive_max: 15.0
- paths: ["record/decisions/*.md"]
checks:
completeness:
template: adr
analyze:
max_grade: 10.0
- paths: ["record/designs/*.md"]
checks:
completeness:
template: design-doc
readability:
max_grade: 12.0
- paths: ["docs/**/*.md", "README.md"]
checks:
readability:
max_grade: 8.0
grammar:
passive_max: 20.0
Rule resolution:
{PROJECT_ROOT}/record/decisions/*.md (2 literal segments) beats record/**/*.md (1 literal)Running rules: Use bito lint <file> to match a file against configured rules and run all resolved checks in one pass:
bito lint record/decisions/0001-my-adr.md # human-readable output
bito lint record/decisions/0001-my-adr.md --json # machine-readable
No matching rule = clean exit (exit 0). Any failing threshold = exit 1.
| Check | Settings | Description |
|---|---|---|
analyze | checks, exclude, max_grade, passive_max, style_min, dialect | Full 18-check writing analysis |
readability | max_grade | Flesch-Kincaid grade level gate |
grammar | passive_max | Passive voice percentage gate |
completeness | template (required) | Template section validation |
tokens | budget, tokenizer | Token count gate |
Suppress specific checks for sections that intentionally break rules:
<!-- bito disable grammar -->
This section uses passive voice on purpose.
<!-- bito enable grammar -->
<!-- bito disable-next-line readability -->
This extraordinarily sesquipedalian sentence is intentional.
<!-- bito disable grammar,cliches -->
Multiple checks suppressed at once.
<!-- bito enable grammar,cliches -->
An unclosed disable suppresses for the rest of the file.
For real-time quality feedback during writing sessions, configure bito as an MCP server. This lets writing skills call quality gate tools directly without shelling out.
Add to your project's .mcp.json:
{
"mcpServers": {
"bito": {
"command": "bito",
"args": ["serve"]
}
}
}
The MCP server exposes: count_tokens, check_readability, check_completeness, analyze, check_grammar, and lint_file (runs path-based rules). When available, writing skills should prefer MCP tool calls over shell commands.
bito ships two tokenizer backends:
Set the backend via config (tokenizer: claude), env var (BITO_TOKENIZER=openai), or CLI flag (--tokenizer openai).
| Check | Command | What it measures |
|---|---|---|
| Lint (rules) | bito lint <file> | Run all checks matching file path rules |
| Token count | bito tokens <file> --budget 2000 | Tokens vs budget (handoffs) |
| Readability | bito readability <file> --max-grade 12 | Flesch-Kincaid grade level |
| Completeness | bito completeness <file> --template adr | Required sections present |
| Grammar | bito grammar <file> | Passive voice, sentence issues |
| Full analysis | bito analyze <file> --dialect en-us | All checks + style score |
Built-in completeness templates: adr, handoff, design-doc. Define custom templates in config.
Each persona is a voice guide in ${CLAUDE_PLUGIN_ROOT}/personas/. The same artifact type always gets the same voice.
| Artifact | Skill | Persona | Persona file |
|---|---|---|---|
| Handoff | curating-context | Context Curator | context-curator.md |
| ADR | capturing-decisions | Technical Writer | technical-writer.md |
| Design doc | writing-design-docs | Technical Writer | technical-writer.md |
| End-user doc | writing-end-user-docs | Doc Writer | doc-writer.md |
| CHANGELOG entry | writing-changelogs | Technical Writer | technical-writer.md |
| Release announcement | writing-changelogs | Marketing Copywriter | marketing-copywriter.md |
| README (above the fold) | — | Marketing Copywriter | marketing-copywriter.md |
| README (below the fold) | writing-end-user-docs | Doc Writer | doc-writer.md |
Multi-persona artifacts: The heading structure is the boundary. README transitions at ## Installation. CHANGELOG + release announcement are handled natively by writing-changelogs. Rule of thumb: "attract or instruct?" Attract = Marketing Copywriter. Instruct = Doc Writer or Technical Writer.
Skill chaining: writing-design-docs → capturing-decisions (ADR extraction), curating-context → capturing-decisions (session decisions), any writing skill → editorial-review (tone firewall).
The plugin includes a git pre-commit hook that runs quality gates on staged documentation files. To install it:
cp hooks/pre-commit-docs .git/hooks/pre-commit
Or source it from an existing hook:
# In your existing .git/hooks/pre-commit
source ~/.claude/plugins/building-in-the-open/hooks/pre-commit-docs
With path-based rules configured, the pre-commit hook can use bito lint instead of per-file check logic — the config becomes the single source of truth for what checks run where.