A template for everyday, safe AI-assisted work: code on one spine, and stories and research on the other.
This README is the index for adopters. It is not a policy source. Binding rules live in constitution/. See Adapting this template.
Safe-harness is an AI-native work harness with two peer spines: Delivery (code: execute/deploy) and Studio (think/plan: stories and research). Humans set direction and keep the safety gates. Agents execute the work and produce evidence.
Who it's for: Small teams (about 1–10 people) working with AI agents who need structured governance, clear ownership, and evidence-based decisions. That includes engineering teams shipping code and teams producing non-code work such as stories and research.
What problem it solves: Agents can write code faster than humans can review it. Without a thin harness, requirements drift, decisions go unrecorded, ownership blurs, and merges become unsafe. Safe-harness is the minimum viable governance that keeps AI-assisted development safe, traceable, and human-controlled.
Who adopts it: A team that will name a human owner (HITL/POPM), a GM / lead architect, and the standing seats below, then configure dev / staging / prod for their own environments.
Useful terms (definitions only; gates and merge authority are not restated here):
| Term | Meaning |
|---|---|
| HITL / POPM | Human In The Loop / Product Owner · Product Manager. The human approval seat. |
| QAS | Quality Assurance & Acceptance. Independent of the implementer. |
| SecEng | Security review. Independent of the implementer. |
| Release · RTE | Independent final release gate under continuous deployment (no trains). |
| O2 | Named high-risk item class. Defaults and downgrade authority are in the constitution, not here. |
| Bolt | A small, bounded work package: brief, implementation, tests, evidence, gates. |
| Spine A / Spine B | Dual workflows. A = Delivery (CD execute/deploy). B = Studio (think/plan). |
| AI-DLC | Agent-first counterpart to a traditional SDLC: humans own intent and design; agents own plan-to-evidence execution. |
Safe-harness runs on two peer spines with a shared shape. Per constitution/00-north-star.md, the spines "share Round Table principles, exit states, and ownership language. They differ in gates and storage." This section is an index. The binding rules live in the linked files.
| Spine element | Spine A — Delivery (code) | Spine B — Studio (stories and research) |
|---|---|---|
| Owning seat | Delivery · Lead | Studio · Lead (stories), with Scout (story media, research) and Librarian (signals) |
| Work unit / brief | templates/delivery-bolt-brief.md |
research-brief skill (sources plus UNKNOWN markers). When knowledge becomes build: templates/studio-to-delivery-handoff.md |
| Flow | Issue → branch → implement + evidence → PR → CI + review → QAS (and SecEng when required) → Release · RTE → merge | Brief → Evidence (sources cited, no invented links) → Gate (privacy/PII/IP class) → Concur (the owner) → Ship/verify/log (ADR 0005) |
| Gates | CI, independent QAS, SecEng, Release · RTE (constitution/03-cd-and-hitl.md) |
Non-code gates: sources cited, plus privacy class via privacy-boundary (constitution/04-privacy-and-vaults.md) |
| Evidence | Portable evidence rows (portable-evidence) at the exact head |
The same portable evidence rows, plus cited sources in the brief |
| Storage | The forge (this repo) | Knowledge-base concepts and private-storage pins. Story IP is never committed to the repo (constitution/04-privacy-and-vaults.md) |
| Human in the loop | Decision pack + the owner's concur where constitution/03 requires it |
The owner's concur before ship (ADR 0005) |
| Exit | Canonical exit states in constitution/05-evidence-and-traceability.md |
Ship/verify/log, or a handoff that Delivery accepts with the checklist in studio-handoff |
Where they meet. When Studio work becomes something to build, Studio emits the handoff and Delivery accepts it before a bolt starts (ADR 0005, studio-handoff). The BSA-like seat shapes acceptance criteria across that bridge.
Adapting to your kind of work. Keep the seats, gates, and evidence. Rename what flows through them. See Adapting this template.
- Copy or generate this repository as your template. See Adapting this template.
- Configure dev, staging, and prod for your environments. This repo itself is trunk-only (
main). How those environments are gated is inconstitution/03-cd-and-hitl.md— see that file; this README grants no authority. - Map seats (next section). Fill
intent.mdandspec.mdas the human owner when you are ready. They stay human-owned placeholders until then. - Keep CODEOWNERS pointed at the human owner (or the owner's review account). Follow the owner-setup checklist in Adapting this template.
- Keep
LICENSEandNOTICE. MIT requires the original copyright and permission notice to stay with copies. Add your own copyright line under ours for your changes; do not replace ours.
- Open a GitHub Issue. Prefer
.github/ISSUE_TEMPLATE/bolt.ymlfor Delivery work. - Add a work-type label (
bolt,decision, orrequirement). - Add a risk-tier label (
tier:low,tier:medium,tier:high). - If an O2 item is in scope, add the matching
o2:*label. The O2 list itself is inconstitution/03-cd-and-hitl.md. - Name a human assignee. An agent may be a delegate; it is never the assignee.
Other issue forms: .github/ISSUE_TEMPLATE/ (requirement.yml, decision.yml). Labels: .github/labels.yml.
- Fill
templates/delivery-bolt-brief.md. - Branch
<issue#>-slugoffmain(example:42-add-auth-check). - Implement, test, and record portable evidence.
- Commit with trailers
Refs #Nand, when REQ IDs exist,Req: REQ-<CMP>-NNN. Whilespec.mdhas no REQ IDs, do not invent them. - Open a PR from
.github/pull_request_template.md. Replace the template'sRequirements:placeholder: list theREQ-<CMP>-NNNIDs the change addresses, or, whilespec.mdhas no REQ IDs, write a bareRequirements: N/Awith the rationale on the next line. - Wait for CI, independent review (QAS, and SecEng when required), and Release · RTE as the constitution requires.
- Merge only under
constitution/03-cd-and-hitl.mdandroles/release-rte.md.
Studio → Delivery handoffs use templates/studio-to-delivery-handoff.md.
Non-code work (stories and research) starts on spine B with Studio · Lead. See Two spines: code and story/research.
Safe-harness is runtime-neutral. Cursor, Claude Code, Codex, and other agents are valid runtimes. Codex reads the root AGENTS.md natively. Adapters in adapters/ map the same constitution into a runtime. A runtime that does not auto-load skills/ must import each skill as its own skill (see skills/README.md).
Name every standing seat before the first bolt. On-demand specialists (Implementer, QAS, SecEng, BSA-like, Release · RTE) sit when the bolt needs them. Do not keep idle seats warm for ceremony. Cards live in roles/ (index: roles/README.md).
- Spine A — Delivery. CD execute/deploy. Delivery · Lead owns projects end to end.
- Spine B — Studio. Think/plan. Studio · Lead owns stories and the handoff into Delivery.
- Staff. Ops · CoS (digests, concur queue), Dispatcher · Board (surfaces only), Librarian, Scout.
- Cross-lane / High. GM / lead architect. High-tier or cross-lane work only.
Lane ownership is in constitution/07-roles-and-lanes.md.
Typical Delivery loop: issue → branch → implement + evidence → PR → CI + review → QAS (and SecEng when required) → Release · RTE → merge. After QAS: APPROVE the implementer head is frozen: no commits, no pushes, and no title or body edits unless Delivery explicitly asks.
Practice guidance (not a constitutional rule), described in skills/hitl-concur-check/SKILL.md: a consequential action needs the human owner's own words, verified. An agent relaying approval is never approval.
Role and seat names only. Adopters copy this table and replace the right-hand column.
| Seat | Assignment in this repo |
|---|---|
| Human owner (HITL/POPM) | Human owner |
| GM / lead architect | GM |
| QAS | GM (never the implementer of the change under review) |
| Delivery · Lead | Delivery lead |
| Studio · Lead | Studio lead |
| Ops · CoS | Ops · CoS |
| Dispatcher · Board | Dispatcher · Board |
| Librarian | Librarian |
| Scout | Scout |
| Release · RTE | Release · RTE |
| SecEng | SecEng |
| Implementer / BSA-like | On demand |
This README does not restate merge-rule text, risk-tier behavior, or the O2 list. If a sentence here disagrees with the constitution, the constitution wins.
| Role | Card |
|---|---|
| GM / lead architect | roles/gm-architect.md |
| Delivery · Lead | roles/delivery-lead.md |
| Studio · Lead | roles/studio-lead.md |
| Ops · CoS | roles/ops-cos.md |
| Dispatcher · Board | roles/dispatcher-board.md |
| Librarian | roles/librarian.md |
| Scout | roles/scout.md |
| QAS | roles/qas.md |
| SecEng | roles/seceng.md |
| Implementer | roles/implementer.md |
| BSA-like | roles/bsa-like.md |
| Release · RTE | roles/release-rte.md |
| Model stack (tiers) | roles/model-stack.md |
| Human owner (HITL/POPM) | Defined in constitution/01-round-table.md |
Tiers, O2, and merge rules: constitution/03-cd-and-hitl.md. Release · RTE: roles/release-rte.md. Seat map: constitution/01-round-table.md. The HITL-concur label in this repo is needs-owner-concur.
| Path | Purpose |
|---|---|
skills/ |
Skills library (index of 38 skills). Canonical path skills/<slug>/SKILL.md. |
skills/INDEX.md |
Skills catalog pointer. |
adapters/claude-code/ |
Claude Code adapter (docs stub). |
adapters/claude-code/AGENTS.md |
Claude Code agent entry point. |
adapters/cursor/ |
Cursor adapter (docs stub). |
adapters/cursor/AGENTS.md |
Cursor agent entry point. |
adapters/codex/ |
Codex adapter (docs stub). |
adapters/codex/AGENTS.md |
Codex agent entry point. |
CLAUDE.md |
Pointer to root AGENTS.md. |
.cursor/rules/safe-harness.mdc |
Cursor pointer rule. |
AGENTS.md |
Root agent entry point (rules by link; local checks). |
docs/adapting.md |
Adapting this template. |
docs/runtimes.md |
How to launch Claude Code, Codex, and Cursor cloud agents from this repo. |
docs/guides/ |
Onboarding for outside teams completing this repo. |
docs/prd/PRD-TEMPLATE.md |
Optional PRD template. Longer product context; spec.md stays canonical for REQ IDs. |
docs/design/ |
Design docs, one per subsystem or topic. Template: docs/design/DESIGN-TEMPLATE.md. |
docs/decisions/ |
Architecture Decision Records (canonical home; numbered ADRs and log.md). |
docs/decisions/ADR-TEMPLATE.md |
Blank MADR 4.0 ADR template with Confirmation. |
docs/decisions/log.md |
Latest-wins decision log and Current shape. |
constitution/ |
Binding governance. |
roles/ |
Seat cards. |
templates/ |
Bolt brief and Studio→Delivery handoff. |
release/flow.md |
Continuous-deployment release flow. |
prove/ |
Evidence and bolt records. |
arch/ |
Component registry. |
requirements/ |
REQ registry (agent-authored; human review). |
trace/ |
Trace map and schema. |
intent.md / intent/ / spec.md |
Human-owned design. Root intent.md is canonical; intent/ is optional longer material. |
.github/CODEOWNERS |
Review gates (intent.md, intent/, spec.md, constitution/, requirements/, trace/, arch/, AGENTS.md, adapters/**/AGENTS.md, skills/, workflows). |
.github/workflows/ |
CI (see below). |
examples/round-table/ |
Instance operating notes and config for one Round Table instance (examples only; not filled templates). |
CODEOWNERS coverage (review gate, not ownership): intent.md, intent/, spec.md, constitution/, requirements/, trace/, arch/, AGENTS.md, adapters/**/AGENTS.md, skills/, .github/CODEOWNERS, and .github/workflows/.
| Workflow | Job | Blocks merge? |
|---|---|---|
wave0-checks.yml |
Structure & Docs Validation (required paths; relative links in markdown at the repo root and under constitution/, roles/, adapters/, templates/, prove/, trace/, docs/, and examples/; fence parity) |
Yes |
wave0-checks.yml |
Skills frontmatter & link scan | Warn-only |
trace-check.yml |
Requirements Trace Validation | Warn-only for validation findings until spec.md has REQ IDs and trace/.blocking exists. The yq preflight step still fails the required check if yq is missing. |
api-contract.yml |
API Contract Checks (oasdiff + optional Schemathesis) | Warn-only (skips when no OpenAPI spec) |
doc-drift.yml |
Doc drift | Warn-only |
Local checks before a PR: run the full list in AGENTS.md "Local checks". Flip notes: docs/ci/skills-checks.md, docs/ci/api-contract.md, docs/ci/doc-drift.md. Branch-protection intent: docs/branch-protection.md.
CodeRabbit is an optional review input. When it runs, its findings are triaged. It is not a required check.
Owner-owned placeholders.
intent.md,intent/, andspec.mdare human-owned. Agents may draft; they never merge those files. Trace-check stays warn-only untilspec.mdhas REQ IDs (and a later, code-owner-reviewed PR addstrace/.blocking). Do not invent REQ IDs during bootstrap.
Recorded architecture decisions: docs/decisions/. Latest-wins index: docs/decisions/log.md.
MIT License. See LICENSE for details.
safe-harness is maintained by ByBren, LLC. It succeeds SAW (SAFe Agentic Workflow).
If you build on this harness, please keep NOTICE and credit "Built with safe-harness by ByBren, LLC". Third-party notices (AI-DLC, MADR, CI tools, SAFe® trademark) are in NOTICE.
- Contribute:
CONTRIBUTING.md. - Release notes:
CHANGELOG.md. - Tag format and RTE ownership of notes:
roles/release-rte.md,release/flow.md.
Success metrics: constitution/00-north-star.md. Evidence and bolt records: prove/README.md.