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.

  1. Install okf-schema in the project environment. Install it in the same development environment used by local checks so the command is also available in CI.

  2. Initialize the requirements bundle with okfreq init .. This creates .agents/requirements/ with config.yml at its root, a guidelines/ folder holding the installed requirements.guidelines.md, and a tiers/ folder holding the schema, the strs/ and swrs/ folders, an index, and a log. Existing files are never overwritten.

  3. Review .agents/requirements/config.yml (or requirements/config.yml for this repository). Add scopes for each independently scanned part of the project and adjust source_dirs and test_dirs before scanning. Keep these mappings scoped: implementation and test evidence can belong to different directories. Set strs_test_coverage_mode to linked-swrs for decomposition-based stakeholder coverage, or to linked-swrs-and-validation-test when each stakeholder outcome also needs a directly marked validation-test definition.

  4. 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 draft StRS with a generated UUID and stable ID such as StRS-default-001. A draft is a proposal not implemented yet: when the requirement describes code that already exists, add --lifecycle proposed. Name the requirement owner with tiers.StRS.owner_email in config.yml; only that owner approves a requirement, on tiers whose approval_lock allows it. Its body separates normative stakeholder-observable behavior, the preserved user need, and rationale/constraints. It does not contain software scenarios or verification notes.

  5. 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. Native SwRS documents must derive from at least one StRS. Keep the derives_from relationship authored; reverse derived_by links are computed. Fill both generated GIVEN-WHEN-THEN scenarios and the verification notes. SwRS documents do not contain a stakeholder user_need section.

  6. 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-001 in the implementation and @tests_req SwRS-default-001 in 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.

  7. Run okfreq trace . to inspect marker references and missing IDs, then run okfreq update-coverage . --check to preview generated coverage fields. Use --diff to review the exact changes; only run without a preview flag when you intend to update implemented_in_files and tested_in_files.

  8. Run okfreq validate . --prose before committing. Structural failures make the command fail; advisory prose findings expose unfinished template gaps. Use the okfreq CLI 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.

Maintain navigation and record changes

After authoring or moving requirements, run okfreq lint <bundle>. It generates navigation blocks in tiers/index.md, configured tier folders and every scope ancestor. Keep your introduction outside the markers; an optional bundle-root index.md remains an authored overview. Use --diff for a read-only preview and --check for CI. okfreq index prints IDs rather than generating these files.

After substantive changes, append a dated record to <bundle>/tiers/log.md: which requirements changed, why, decisions/open questions and actual validation results. Keep previous entries. Lint never generates the authored log.