Build a requirement base¶
Want to understand the why first?
Read the full Requirements traceability tutorial
to learn what requirements are, why traceability is useful, and how the StRS
and SwRS layers connect implementation to test evidence. This page is the
short, procedural setup path.
This guide sets up a small, agent-friendly requirements base. The examples use an export feature: the stakeholder describes the user outcome, the software requirement describes observable behavior, and source and test markers connect that behavior to evidence.
For the boundary between marker linkage and executed test-result evidence, see
What okfreq coverage really means.
Install
okf-schemain the project environment. Install it in the same development environment used by local checks so the command is also available in CI.Initialize the requirements bundle with
okfreq init .. This creates.agents/requirements/withconfig.ymlat its root, aguidelines/folder holding the installedrequirements.guidelines.md, and atiers/folder holding the schema, thestrs/andswrs/folders, an index, and a log. Existing files are never overwritten.Review
.agents/requirements/config.yml(orrequirements/config.ymlfor this repository). Add scopes for each independently scanned part of the project and adjustsource_dirsandtest_dirsbefore scanning. Keep these mappings scoped: implementation and test evidence can belong to different directories. Setstrs_test_coverage_modetolinked-swrsfor decomposition-based stakeholder coverage, or tolinked-swrs-and-validation-testwhen each stakeholder outcome also needs a directly marked validation-test definition.Create a stakeholder requirement:
okfreq new strs "Export report" --description "When report export is requested, the reporting capability SHALL make a portable report available." --user-need "Users need a portable report for offline review." --project demo. This creates a draftStRSwith a generated UUID and stable ID such asStRS-default-001. Adraftis a proposal not implemented yet: when the requirement describes code that already exists, add--lifecycle proposed. Name the requirement owner withtiers.StRS.owner_emailinconfig.yml; only that owner approves a requirement, on tiers whoseapproval_lockallows it. Its body separates normative stakeholder-observable behavior, the preserved user need, and rationale/constraints. It does not contain software scenarios or verification notes.Create a software requirement with its parent:
okfreq new swrs "Write CSV" --description "When export is requested, the service SHALL write the selected rows as UTF-8 CSV." --project demo --derives-from StRS-default-001. NativeSwRSdocuments must derive from at least oneStRS. Keep thederives_fromrelationship authored; reversederived_bylinks are computed. Fill both generated GIVEN-WHEN-THEN scenarios and the verification notes. SwRS documents do not contain a stakeholderuser_needsection.Ask your coding agent to implement the software requirement and add tests. Explicitly name the requirement ID and ask the agent to add
@implements_req SwRS-default-001in the implementation and@tests_req SwRS-default-001in the corresponding test file. Put a marker beside each relevant test case; the same ID may repeat in one file. The markers make the links discoverable without claiming that the tests passed.Run
okfreq trace .to inspect marker references and missing IDs, then runokfreq update-coverage . --checkto preview generated coverage fields. Use--diffto review the exact changes; only run without a preview flag when you intend to updateimplemented_in_filesandtested_in_files.Run
okfreq validate . --prosebefore committing. Structural failures make the command fail; advisory prose findings expose unfinished template gaps. Use theokfreqCLI reference and the tutorial for the concepts behind the workflow.
In CI, run okfreq validate . as a required job after the environment is
installed. Keep generated indexes and coverage updates explicit; preview
generated changes before applying them. A typical CI job is equivalent to:
$ okfreq validate . --prose
2 requirements, 0 errors
The command exits non-zero for missing required metadata, invalid UUIDs, unknown derivation targets, invalid lifecycle values, or invalid configured tiers. It does not turn a marker into a claim that the implementation or test is correct: run the normal project test suite as well.
See the design explanation and the
okfreq CLI reference for rationale and commands.
For this repository, the maintained requirements bundle is requirements/: its
configuration is requirements/config.yml, its documents are under
requirements/tiers/, its project rules are in
requirements/guidelines/project.guidelines.md, and the shared guidance is the
installed requirements/guidelines/requirements.guidelines.md.
Keep project rules out of the installed guideline. okfreq init <bundle> --force
replaces guidelines/requirements.guidelines.md with the packaged text, which is
how an existing project refreshes it; it leaves every other file of
guidelines/ and every requirement untouched. If you appended project sections
to the installed file, move them to a separate file such as
guidelines/project.guidelines.md before running --force.
To go from a project with no requirements bundle to a reviewable baseline in one
step, ask your agent to use the okfreq-setup skill (installed with
okfreq install-skills). It installs okfreq, initialises requirements/,
specifies every current behaviour as StRS and SwRS, adds @implements_req and
@tests_req markers, adds tests for untested behaviour and opens one pull
request, without asking you questions. It stops if a bundle already exists, and
it never merges. Behaviour that looks wrong is specified as it is, marked
“Known issue”, and listed in the final report as a bug candidate. Review the
pull request like any other: the markers show where evidence is linked, not that
the specification is right.
The baseline guideline installed into the project explains the rules the
specification follows. Requirements describe what the code does today, anchored
by marker pairs; one SwRS is one observable behaviour with a scenario for each
refusal and boundary; a rule shared by many features is written once and cited
with depends_on; IDs are created by okfreq new, never reused (a draft that
was never published is discarded with okfreq retire), and published
requirements are archived or superseded rather than deleted. A project may
override these rules only in its own guideline section.
For an existing or brownfield requirements base, use the okfreq-gardening
skill from the repository’s skills/okfreq-gardening/SKILL.md package to audit
gaps and configuration drift while preserving authored requirement content.
When the bundle has grown too fine or repetitive, the gardening skill proposes a
mapping to merge or supersede requirements and waits for your approval before
restructuring.