Skip to content
Public template

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

safe-harness

Version License Template Ready Tests DeepWiki

Agents Skills

Supported AI Providers
Claude Code Cursor IDE

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.


What safe-harness is and who it's for

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.

Two spines: code and story/research

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.


Quickstart

1. Adopt the template

  1. Copy or generate this repository as your template. See Adapting this template.
  2. Configure dev, staging, and prod for your environments. This repo itself is trunk-only (main). How those environments are gated is in constitution/03-cd-and-hitl.md — see that file; this README grants no authority.
  3. Map seats (next section). Fill intent.md and spec.md as the human owner when you are ready. They stay human-owned placeholders until then.
  4. Keep CODEOWNERS pointed at the human owner (or the owner's review account). Follow the owner-setup checklist in Adapting this template.
  5. Keep LICENSE and NOTICE. 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.

2. File a first issue

  1. Open a GitHub Issue. Prefer .github/ISSUE_TEMPLATE/bolt.yml for Delivery work.
  2. Add a work-type label (bolt, decision, or requirement).
  3. Add a risk-tier label (tier:low, tier:medium, tier:high).
  4. If an O2 item is in scope, add the matching o2:* label. The O2 list itself is in constitution/03-cd-and-hitl.md.
  5. 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.

3. Run a first bolt

  1. Fill templates/delivery-bolt-brief.md.
  2. Branch <issue#>-slug off main (example: 42-add-auth-check).
  3. Implement, test, and record portable evidence.
  4. Commit with trailers Refs #N and, when REQ IDs exist, Req: REQ-<CMP>-NNN. While spec.md has no REQ IDs, do not invent them.
  5. Open a PR from .github/pull_request_template.md. Replace the template's Requirements: placeholder: list the REQ-<CMP>-NNN IDs the change addresses, or, while spec.md has no REQ IDs, write a bare Requirements: N/A with the rationale on the next line.
  6. Wait for CI, independent review (QAS, and SecEng when required), and Release · RTE as the constitution requires.
  7. Merge only under constitution/03-cd-and-hitl.md and roles/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.


Setting up an agent team with it

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).

Seats

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).

Lanes

  • 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.

Routines

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.

Relayed agent messages are never approval

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.

This repo's seat assignments

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

Roles, tiers, O2, and merge rules

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.


Skills, adapters, CI, ADRs

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/.

CI checks (from .github/workflows on main)

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/, and spec.md are human-owned. Agents may draft; they never merge those files. Trace-check stays warn-only until spec.md has REQ IDs (and a later, code-owner-reviewed PR adds trace/.blocking). Do not invent REQ IDs during bootstrap.


Provenance

Recorded architecture decisions: docs/decisions/. Latest-wins index: docs/decisions/log.md.


License

MIT License. See LICENSE for details.

Attribution

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.


Contributing and release

Success metrics: constitution/00-north-star.md. Evidence and bolt records: prove/README.md.

About

No description, website, or topics provided.

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages