Building in the Open
claylo/building-in-the-open
Gates de qualidade e personas para documentação técnica sem deriva de tom
Ver no GitHubAgent Claude que impõe padrões de qualidade em documentação técnica, READMEs e handoffs através de personas de escritor consistentes e gates de qualidade automatizados. Captura decisões arquiteturais, mantém tom uniforme e bloqueia problemas antes do commit.
Instalação
npx convez-ai claylo/building-in-the-open1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar ADRs (Architecture Decision Records) com voz consistente
- Revisar e validar documentação antes de publicar
- Criar handoffs entre agentes mantendo qualidade editorial
- Documentar changelogs, design docs e guias de usuário final
- Implementar firewalls editoriais contra sarcasmo e contexto implícito
Veredito

Ferramenta especializada e bem-arquitetada para times que precisam de documentação técnica com qualidade editorial rigorosa. Resolve um problema real (deriva de voz em múltiplos agentes) com abordagem criativa de personas e gates mensuráveis, ideal para equipes que levam documentação a sério.
README
A tradução para o português deste README ainda está na fila.
building-in-the-open
Ask an AI agent to write three documents in the same session. You'll get three different voices, three different quality levels, and zero consistency.
That's fine for throwaway drafts. It's not fine for anything that reaches your repository.
building-in-the-open is a Claude Code plugin that fixes this with writer personas for consistent voice, quality gates for measurable standards, and an editorial firewall that catches tone drift, sarcasm, and assumed context before anything ships.
Whether you're a developer capturing the reasoning behind architectural decisions or a technical writer maintaining documentation—the problem is the same. AI agents need guardrails on their prose, not just their code. Technical writers are already discovering this—and so are UX writers and documentation teams.
Seven skills. Four writer personas. One tone firewall. Zero embarrassing commits.
What this is—and isn't
This produces development artifacts—the documentation that emerges during building: ADRs, design docs, handoffs, changelogs, end-user guides. If you need a documentation site generator, look at mdBook or Docusaurus. If you need the documents worth putting on that site, you're in the right place.
How it works
Three layers, loosely coupled:
┌─────────────────────────────────────────────────────┐
│ SKILLS (artifact-specific workflows) │
│ curating-context, capturing-decisions, writing- │
│ design-docs, writing-end-user-docs, writing- │
│ changelogs, editorial-review, building-in-the-open │
├─────────────────────────────────────────────────────┤
│ PERSONAS (composable voice layer) │
│ technical-writer, doc-writer, marketing- │
│ copywriter, context-curator │
├─────────────────────────────────────────────────────┤
│ TOOLING (quality gates) │
│ bito: token counter, readability scorer, │
│ completeness checker, path-based rules engine │
└─────────────────────────────────────────────────────┘
Skills define what to produce. Personas define how to sound. Tooling enforces whether it's good enough to ship.
Each skill announces itself and its persona when invoked—so you always know which voice is active and why.
Installation
claude plugin add claylo-marketplace/building-in-the-open
Or install manually:
git clone https://github.com/claylo/building-in-the-open ~/.claude/plugins/building-in-the-open
Quality gates (optional but recommended):
brew install claylo/brew/bito # macOS / Linux, easiest
npm install -g @claylo/bito # wraps the native binary
cargo binstall bito # if you've got a rust environment
Verify: bito doctor
See the installation guide for pre-commit hooks, MCP server setup, and dialect configuration.
Quickstart
See the quickstart walkthrough for hands-on examples:
- Your first handoff — capture session context with quality gates
- Your first ADR — document an architectural decision
- The editorial review pipeline — the full draft-review-commit loop
Skills
Each skill lives in skills/<name>/SKILL.md and defines a complete workflow for one artifact type.
| Skill | What it produces | Persona |
|---|---|---|
building-in-the-open | Routing + bito setup and configuration | — |
curating-context | Public handoffs + private memory | Context Curator |
capturing-decisions | Architecture decision records (MADR 4.0.0) | Technical Writer |
writing-design-docs | Design documents | Technical Writer |
writing-end-user-docs | Tutorials, guides, API references | Doc Writer |
writing-changelogs | CHANGELOG.md + release announcements | Technical Writer + Marketing Copywriter |
editorial-review | Pass/fail quality review | None (reviewer, not writer) |
Skills are superpowers-aware—if the superpowers plugin is installed, workflow integration happens automatically. If not, every skill works standalone.
Personas
Personas are voice guides stored in personas/<name>.md. They tell an agent how to write—not what to say, but how to sound saying it.
- Technical Writer — Rigorous, opinionated, warm. First-person plural. Explicit trade-offs. For ADRs and design docs.
- Context Curator — Dense, structured, scannable. Optimized for tokens-to-insight ratio. For handoffs.
- Doc Writer — Accessible, example-first, respects the reader's time. For end-user docs.
- Marketing Copywriter — Benefits before features, technically credible. For READMEs and announcements.
Personas compose. A README uses Marketing Copywriter above the fold and Doc Writer below. The writing-changelogs skill produces two outputs from the same changes—Technical Writer for the CHANGELOG, Marketing Copywriter for the release announcement. The building-in-the-open skill documents all the composition points.
Quality gates
Define what checks run on what files in your config—no hardcoded scripts:
# .bito.yaml
rules:
- paths: [".handoffs/*.md"]
checks:
tokens: { budget: 2000 }
completeness: { template: handoff }
- paths: ["record/decisions/*.md"]
checks:
completeness: { template: adr }
- paths: ["record/designs/*.md"]
checks:
completeness: { template: design-doc }
readability: { max_grade: 12 }
Run all matching checks in one pass:
bito lint record/decisions/0001-my-adr.md
The editorial-review skill adds agent-based judgment on top of these deterministic checks—catching sarcasm, implied criticism, and tone mismatches that a pattern matcher can't reach.
The tone firewall
Everything gets drafted freely. Private context (PRIVATE_MEMORY.md) stays completely unfiltered—motivations, frustrations, hunches, the real story. Only artifacts destined for the repository get filtered through the quality gates.
The rule: if you wouldn't say it at a technical conference, it doesn't reach the repo.
Project structure
.bus-factor/ Archived handoffs (project timeline)
.claude-plugin/ Plugin metadata
.handoffs/ Active handoff documents (committed)
agents/ Subagent definitions (editorial reviewer)
record/decisions/ Architecture decision records
record/designs/ Design documents
hooks/ Plugin hooks + pre-commit hook
personas/ Writer voice definitions
skills/ Artifact-specific workflows
templates/ Document structure templates
Architecture decisions
This project's own ADRs document the key design choices:
- ADR-0001 — Composable persona layer
- ADR-0002 — Tone firewall on commit path
- ADR-0003 — Real tools for measurement, agents for judgment
- ADR-0004 — Prompted ADR extraction
- ADR-0005 — 2,000-token handoff budget
- ADR-0006 — Private memory gitignored, handoffs committed
- ADR-0007 — Pluggable tokenizer backends
License
MIT