Bedrock is a solo-maintainer project built in the open. Contributions are welcome, but the workflow is inverted from a typical OSS repo. This page describes the model first, then the mechanics.
This project is organized around prompt requests, a framing borrowed from Peter Steinberger:
I don't like pull requests (PRs) any more. A large chunk code change doesn't tell me much about the intent or why it was done.
I now prefer prompt requests. Just share the prompt you ran / want to run. If I think it's good, I'll run it myself and merge it.
The default path for an external contribution:
- Open a Discussion describing the change you want.
- Share the prompt you would run to make it happen. Not the diff, the prompt.
- If the idea lands, I run the prompt, review the output, and merge.
Intent is the scarce thing. A prompt captures it directly; a diff hides it behind output. Adjusting scope before the model runs is cheaper than adjusting it after.
Trivial or mechanical changes (typo, docs fix, one-line bug fix) can come in as a normal PR. Anything larger should start in Discussions so scope is aligned before code is written. PRs that should have been prompt requests will be closed with a pointer here.
Please do not open issues directly. External input goes through Discussions:
- Q&A for usage questions
- Ideas for feature proposals and prompt requests
- Bug reports as a Discussion with reproduction steps
I convert matured Discussions into tracked issues when work is ready to start.
For security vulnerabilities, see SECURITY.md. Never report those publicly.
A good prompt is specific enough to produce the change you want, loose enough that the model has room to pick a reasonable implementation.
Include:
- Goal. One sentence about the outcome.
- Context. File paths, relevant conventions, ADRs the change touches.
- Constraints. Public API stability, TDD discipline, dependency policy, anything that must or must not change.
- Done looks like. Which tests pass? What is manually verifiable?
Reference the rules in the rules section below directly in your prompt so the model does not need a second pass.
Proposals in any of these buckets need an Architecture Decision Record before any code runs:
- New dependencies, build tools, or cross-cutting patterns
- New architectural layers, boundaries, or abstractions
- External integrations (APIs, auth, storage backends)
- Data-model or configuration-format changes
- Breaking API changes
See ADR-006 for the full list and the collaborative Q&A process. Start the ADR in a Discussion; I will shape it into the repo format once the decision is clear.
The bar is the same whether a human or an agent writes the diff:
- Test-driven. Every line of production code is written in response to a failing test (RED -> GREEN -> REFACTOR). See ADR-003.
- 100% coverage across statements, branches, functions, and lines on
src/**. CI enforces this. - Commit style.
type(scope): kebab-case subject. Scope-enum:bedrock,e2e,global,ocale,testing,tsconfig,vite,website.ci,chore,docs,build,refactorare types, not scopes. - Public API examples. Exported symbols carry JSDoc
@exampleblocks (ADR-005).
If you want to run things locally (or to run the prompt yourself before sharing it):
git clone https://github.com/christopher-buss/bedrock.git
cd bedrock
pnpm install
pnpm build
pnpm test| Command | Purpose |
|---|---|
pnpm test |
Vitest |
pnpm lint |
ESLint (auto-fix on) |
pnpm typecheck |
TypeScript check across the workspace |
pnpm build |
Build all packages |
pnpm gen:example-tests |
Regenerate tests from @example JSDoc |
pnpm mutate:changed |
Stryker mutation tests on changed files |
The pre-commit hook (managed by hk) runs lint, typecheck, test, and build.
By participating in Discussions, issues, or PRs, you agree to the Code of Conduct.