{"id":46476029,"url":"https://github.com/claylo/building-in-the-open","last_synced_at":"2026-04-02T13:56:31.583Z","repository":{"id":337742090,"uuid":"1154916973","full_name":"claylo/building-in-the-open","owner":"claylo","description":"Add writing quality gates to your documentation, agentic handoffs, and READMEs.","archived":false,"fork":false,"pushed_at":"2026-03-26T04:23:07.000Z","size":274,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T23:54:22.905Z","etag":null,"topics":["claude-plugin","proofreading","technical-writing","writing-quality-gates"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claylo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"lovelesslabs","buy_me_a_coffee":"claylo"}},"created_at":"2026-02-10T23:14:28.000Z","updated_at":"2026-03-26T04:22:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/claylo/building-in-the-open","commit_stats":null,"previous_names":["claylo/building-in-the-open"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/claylo/building-in-the-open","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbuilding-in-the-open","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbuilding-in-the-open/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbuilding-in-the-open/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbuilding-in-the-open/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claylo","download_url":"https://codeload.github.com/claylo/building-in-the-open/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claylo%2Fbuilding-in-the-open/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307386,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-plugin","proofreading","technical-writing","writing-quality-gates"],"created_at":"2026-03-06T07:03:48.037Z","updated_at":"2026-04-02T13:56:31.577Z","avatar_url":"https://github.com/claylo.png","language":"Shell","funding_links":["https://github.com/sponsors/lovelesslabs","https://buymeacoffee.com/claylo"],"categories":[],"sub_categories":[],"readme":"# building-in-the-open\n\nAsk an AI agent to write three documents in the same session. You'll get three different voices, three different quality levels, and zero consistency.\n\nThat's fine for throwaway drafts. It's not fine for anything that reaches your repository.\n\n`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.\n\nWhether 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](https://medium.com/@jennifer.oakleytx/day-1-with-claude-code-a-technical-writers-first-impressions-8ab46cf704e8)—and so are [UX writers](https://uxwritinghub.com/claude-code-ux-writing/) and [documentation teams](https://www.mintlify.com/blog/how-mintlify-uses-claude-code-as-a-technical-writing-assistant).\n\nSeven skills. Four writer personas. One tone firewall. Zero embarrassing commits.\n\n### What this is—and isn't\n\nThis 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.\n\n## How it works\n\nThree layers, loosely coupled:\n\n```\n┌─────────────────────────────────────────────────────┐\n│  SKILLS (artifact-specific workflows)               │\n│  curating-context, capturing-decisions, writing-    │\n│  design-docs, writing-end-user-docs, writing-       │\n│  changelogs, editorial-review, building-in-the-open │\n├─────────────────────────────────────────────────────┤\n│  PERSONAS (composable voice layer)                  │\n│  technical-writer, doc-writer, marketing-           │\n│  copywriter, context-curator                        │\n├─────────────────────────────────────────────────────┤\n│  TOOLING (quality gates)                            │\n│  bito: token counter, readability scorer,      │\n│  completeness checker, path-based rules engine      │\n└─────────────────────────────────────────────────────┘\n```\n\n**Skills** define *what* to produce. **Personas** define *how* to sound. **Tooling** enforces *whether it's good enough to ship*.\n\nEach skill announces itself and its persona when invoked—so you always know which voice is active and why.\n\n## Installation\n\n```sh\nclaude plugin add claylo-marketplace/building-in-the-open\n```\n\nOr install manually:\n\n```sh\ngit clone https://github.com/claylo/building-in-the-open ~/.claude/plugins/building-in-the-open\n```\n\n**Quality gates** (optional but recommended):\n\n```sh\nbrew install claylo/brew/bito # macOS / Linux, easiest\nnpm install -g @claylo/bito   # wraps the native binary\ncargo binstall bito           # if you've got a rust environment\n```\n\nVerify: `bito doctor`\n\nSee the [installation guide](docs/installation.md) for pre-commit hooks, MCP server setup, and dialect configuration.\n\n## Quickstart\n\nSee the [quickstart walkthrough](docs/quickstart.md) for hands-on examples:\n- **Your first handoff** — capture session context with quality gates\n- **Your first ADR** — document an architectural decision\n- **The editorial review pipeline** — the full draft-review-commit loop\n\n## Skills\n\nEach skill lives in `skills/\u003cname\u003e/SKILL.md` and defines a complete workflow for one artifact type.\n\n| Skill | What it produces | Persona |\n|-------|-----------------|---------|\n| `building-in-the-open` | Routing + bito setup and configuration | — |\n| `curating-context` | Public handoffs + private memory | Context Curator |\n| `capturing-decisions` | Architecture decision records (MADR 4.0.0) | Technical Writer |\n| `writing-design-docs` | Design documents | Technical Writer |\n| `writing-end-user-docs` | Tutorials, guides, API references | Doc Writer |\n| `writing-changelogs` | CHANGELOG.md + release announcements | Technical Writer + Marketing Copywriter |\n| `editorial-review` | Pass/fail quality review | None (reviewer, not writer) |\n\nSkills are superpowers-aware—if the [superpowers](https://github.com/anthropics/superpowers) plugin is installed, workflow integration happens automatically. If not, every skill works standalone.\n\n## Personas\n\nPersonas are voice guides stored in `personas/\u003cname\u003e.md`. They tell an agent *how* to write—not what to say, but how to sound saying it.\n\n- **Technical Writer** — Rigorous, opinionated, warm. First-person plural. Explicit trade-offs. For ADRs and design docs.\n- **Context Curator** — Dense, structured, scannable. Optimized for tokens-to-insight ratio. For handoffs.\n- **Doc Writer** — Accessible, example-first, respects the reader's time. For end-user docs.\n- **Marketing Copywriter** — Benefits before features, technically credible. For READMEs and announcements.\n\nPersonas 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.\n\n## Quality gates\n\nDefine what checks run on what files in your config—no hardcoded scripts:\n\n```yaml\n# .bito.yaml\nrules:\n  - paths: [\".handoffs/*.md\"]\n    checks:\n      tokens: { budget: 2000 }\n      completeness: { template: handoff }\n\n  - paths: [\"record/decisions/*.md\"]\n    checks:\n      completeness: { template: adr }\n\n  - paths: [\"record/designs/*.md\"]\n    checks:\n      completeness: { template: design-doc }\n      readability: { max_grade: 12 }\n```\n\nRun all matching checks in one pass:\n\n```sh\nbito lint record/decisions/0001-my-adr.md\n```\n\nThe `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.\n\n## The tone firewall\n\nEverything 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.\n\nThe rule: if you wouldn't say it at a technical conference, it doesn't reach the repo.\n\n## Project structure\n\n```\n.bus-factor/        Archived handoffs (project timeline)\n.claude-plugin/     Plugin metadata\n.handoffs/          Active handoff documents (committed)\nagents/             Subagent definitions (editorial reviewer)\nrecord/decisions/     Architecture decision records\nrecord/designs/       Design documents\nhooks/              Plugin hooks + pre-commit hook\npersonas/           Writer voice definitions\nskills/             Artifact-specific workflows\ntemplates/          Document structure templates\n```\n\n## Architecture decisions\n\nThis project's own ADRs document the key design choices:\n\n- [ADR-0001](record/decisions/0001-composable-persona-layer-for-artifact-generation.md) — Composable persona layer\n- [ADR-0002](record/decisions/0002-tone-firewall-on-commit-path-not-writing-path.md) — Tone firewall on commit path\n- [ADR-0003](record/decisions/0003-real-tools-for-measurement-agents-for-judgment.md) — Real tools for measurement, agents for judgment\n- [ADR-0004](record/decisions/0004-prompted-adr-extraction-from-design-docs.md) — Prompted ADR extraction\n- [ADR-0005](record/decisions/0005-token-budget-for-public-handoffs.md) — 2,000-token handoff budget\n- [ADR-0006](record/decisions/0006-private-memory-gitignored-handoffs-committed.md) — Private memory gitignored, handoffs committed\n- [ADR-0007](record/decisions/0007-use-pluggable-tokenizer-backends-in-bito.md) — Pluggable tokenizer backends\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fbuilding-in-the-open","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaylo%2Fbuilding-in-the-open","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaylo%2Fbuilding-in-the-open/lists"}