Skip to content

AGENTS.md

Latest commit

 

History

History
106 lines (86 loc) · 5.97 KB

AGENTS.md

File metadata and controls

106 lines (86 loc) · 5.97 KB

AGENTS.md — Rivet Project Instructions

This file was generated by rivet init --agents. Re-run the command any time artifacts change to keep this file current.

Project Overview

This project uses Rivet for SDLC artifact traceability.

  • Config: rivet.yaml
  • Schemas: common, stpa, dev
  • Artifacts: 357 across 13 types
  • Validation: rivet validate (current status: 12 errors)

Available Commands

Command Purpose Example
rivet validate Check link integrity, coverage, required fields rivet validate --format json
rivet list List artifacts with filters rivet list --type requirement --format json
rivet stats Show artifact counts by type rivet stats --format json
rivet add Create a new artifact rivet add -t requirement --title "..." --link "satisfies:SC-1"
rivet link Add a link between artifacts rivet link SOURCE -t satisfies --target TARGET
rivet serve Start the dashboard rivet serve --port 3000
rivet export Generate HTML reports rivet export --format html --output ./dist
rivet impact Show change impact rivet impact --since HEAD~1
rivet coverage Show traceability coverage rivet coverage --format json
rivet diff Compare artifact versions rivet diff --base path/old --head path/new

Artifact Types

Type Count Description
control-action 42 An action issued by a controller to a controlled process or another controller.
controlled-process 16 A process being controlled — the physical or data transformation acted upon by controllers.
controller 12 A system component (human or automated) responsible for issuing control actions. Each controller has a process model — its internal beliefs about the state of the controlled process.
controller-constraint 29 A constraint on a controller's behavior derived by inverting a UCA. Specifies what the controller must or must not do.
design-decision 20 An architectural or design decision with rationale
feature 16 A user-visible capability or feature
hazard 18 A system state or set of conditions that, together with worst-case environmental conditions, will lead to a loss.
loss 8 An undesired or unplanned event involving something of value to stakeholders. Losses define what the analysis aims to prevent.
loss-scenario 33 A causal pathway describing how a UCA could occur or how the control action could be improperly executed, leading to a hazard.
requirement 81 A functional or non-functional requirement
sub-hazard 20 A refinement of a hazard into a more specific unsafe condition.
system-constraint 11 A condition or behavior that must be satisfied to prevent a hazard. Each constraint is the inversion of a hazard.
uca 51 An Unsafe Control Action — a control action that, in a particular context and worst-case environment, leads to a hazard. Four types (provably complete): 1. Not providing the control action leads to a hazard 2. Providing the control action leads to a hazard 3. Providing too early, too late, or in the wrong order 4. Control action stopped too soon or applied too long

Working with Artifacts

File Structure

  • Artifacts are stored as YAML files in: safety/stpa, safety/requirements
  • Schema definitions: schemas/ directory
  • Documents: docs

Creating Artifacts

rivet add -t requirement --title "New requirement" --status draft --link "satisfies:SC-1"

Validating Changes

Always run rivet validate after modifying artifact YAML files. Use rivet validate --format json for machine-readable output.

Link Types

Link Type Description Inverse
acts-on Control action acts on a process or controller acted-on-by
allocated-to Source is allocated to the target (e.g. requirement to architecture component) allocated-from
caused-by-uca Loss scenario is caused by an unsafe control action causes-scenario
constrained-by Source is constrained by the target constrains
constrains-controller Constraint applies to a specific controller controller-constrained-by
depends-on Source depends on target being completed first depended-on-by
derives-from Source is derived from the target derived-into
implements Source implements the target implemented-by
inverts-uca Controller constraint inverts (is derived from) an UCA inverted-by
issued-by Control action or UCA is issued by a controller issues
leads-to-hazard UCA or loss scenario leads to a hazard hazard-caused-by
leads-to-loss Hazard leads to a specific loss loss-caused-by
mitigates Source mitigates or prevents the target mitigated-by
prevents Constraint prevents a hazard prevented-by
refines Source is a refinement or decomposition of the target refined-by
satisfies Source satisfies or fulfils the target satisfied-by
traces-to General traceability link between any two artifacts traced-from
verifies Source verifies or validates the target verified-by

Conventions

  • Artifact IDs follow the pattern: PREFIX-NNN (e.g., REQ-001, FEAT-042)
  • Use rivet add to create artifacts (auto-generates next ID)
  • Always include traceability links when creating artifacts
  • Run rivet validate before committing

Commit Traceability

This project enforces commit-to-artifact traceability.

Required git trailers:

  • Fixes -> maps to link type fixes
  • Implements -> maps to link type implements
  • Trace -> maps to link type traces-to
  • Verifies -> maps to link type verifies

Exempt artifact types (no trailer required): chore, style, ci, docs, build

To skip traceability for a commit, add: Trace: skip