okfreq
Understand, set up, author, implement, and maintain an okfreq requirements base that connects stakeholder intent to observable software behavior, source code, tests, and traceability reports. Use when the user mentions okfreq, living requirements, StRS or SwRS authoring, requirement derivation, implementation or test markers, requirement coverage, or requirements lifecycle; route explicit brownfield audits to okfreq-gardening.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- okfreq
- metadata
- { "url": "https://github.com/gsemet/okf-schema", "keywords": [ "okfreq", "requirements", "living-requirements", "traceability", "StRS", "SwRS", "implementation-markers", "test-markers", "coverage" ] }
- description
- Understand, set up, author, implement, and maintain an okfreq requirements base that connects stakeholder intent to observable software behavior, source code, tests, and traceability reports. Use when the user mentions okfreq, living requirements, StRS or SwRS authoring, requirement derivation, implementation or test markers, requirement coverage, or requirements lifecycle; route explicit brownfield audits to okfreq-gardening.
02 资源文件 1
- 参考文档references/operations.md16.1 KB
03 SKILL.md 正文
okfreq
<!-- @implements_req SwRS-OKFSCHEMA-OKFREQ-008 -->
Use okfreq to maintain a living requirements specification beside the code.
Its goal is to keep stakeholder intent connected to observable software
behavior, implementation, tests, and reviewable gap reports as the project
changes. Teach that model, identify the user's intent, then use the smallest
appropriate workflow.
This skill explains the requirements and traceability lifecycle. Use the
okf-schema skill for generic OKF conformance, schemas, frontmatter mechanics,
or implementation details of the underlying tool.
Progressive references
Keep this entrypoint as the first read. The packaged operations reference is
self-contained: agents need the installed CLI and target project, not this
package's source code or documentation website. The requirements guideline is
not shipped with this skill: okfreq init installs it into the bundle as
<bundle>/guidelines/requirements.guidelines.md, and that file is the single
guideline to follow.
| Need | Read |
|---|---|
| Commands, backfilling existing features, harness setup, reports, or troubleshooting | Standalone operations |
Installation
Install or upgrade the Python CLI tool with uv:
uv tool install okf-schema
uv tool upgrade okf-schema
This tool installation exposes the okf-schema, okfkb, and okfreq console
commands. It is separate from installing agent skill folders: use
okfreq install-skills to copy the packaged okfreq skill family into an
agent's skills directory.
Start with project rules
- Locate the requirements bundle. Prefer an explicit path, then a top-level
requirements/, then.agents/requirements/, and finally.github/requirements/. The bundle root is the directory that ownsconfig.yml; its requirement documents and schemas normally live intiers/. - Read the nearest
AGENTS.mdand any requirements guideline it registers. - Read
<bundle>/guidelines/requirements.guidelines.md, installed byokfreq init, then any other guideline file in that folder (by conventionproject.guidelines.md). The project files carry local paths, scopes, commands, and review rules and win where they specialize the shared text. Resolve project-specific paths, scopes, and quality commands fromconfig.yml,AGENTS.md, and the project itself rather than assuming that example names apply universally. - Never put project rules in
requirements.guidelines.md:okfreq init <bundle> --forcereplaces it with the packaged text, which is how a missing or outdated copy is installed or refreshed. It leaves every other file ofguidelines/untouched. - Before changing requirements, read
config.ymland every schema undertiers/_schema/. Local configuration and schemas define the actual tiers, hierarchy, IDs, lifecycle values, owners, approval locks, markers, scopes, and allowed fields.
The goal of okfreq
okfreq demonstrates an agent-friendly way to keep production-level,
structured living requirements that stay aligned with code and tests and expose
traceability gaps. It does not pretend that generated files are the ultimate
source of stakeholder truth.
Treat the requirements base as a maintained, reviewable representation of what the implemented system is expected to do. Compare it with the original intent, then explicitly accept or adapt it as implementation teaches the team more. Requirements may evolve; silent drift must not.
A useful requirement states one agreed behavior or constraint precisely enough that a developer can implement it and a tester can decide whether it is satisfied. It is not an issue title, design choice, code comment, or task.
Core model
- StRS captures stakeholder intent. It states a stakeholder-observable goal or use case and preserves the underlying user need without prescribing the implementation.
- SwRS captures observable software behavior. It refines one or more StRS requirements into bounded behavior that code can implement and tests can observe.
- Authored derivation points upward. Author
derives_from; letokfreqcompute reversederived_bylinks. Likewise authorsuperseded_by(throughokfreq supersede OLD NEW...) and letokfreqcomputesupersedes; userelates_tofor lateral links with no derivation or replacement meaning. - Leaf requirements connect to evidence. Place
@implements_req <ID>near the relevant production behavior and@tests_req <ID>near each relevant test. The same ID may repeat at distinct evidence points in one file. StRS never receives implementation markers; in the stricterlinked-swrs-and-validation-testmode, a direct@tests_req <StRS-ID>marker defines a stakeholder validation test. - Markers are links, not proof. A test marker says where verification lives, not whether the test ran or passed. Run the project's real test suite.
- Coverage and reports are generated views. Keep implementation coverage, test-link coverage, structural health, and lifecycle counts separate; do not collapse them into a misleading success score.
- Lifecycle is explicit. Creating, formatting, linking, or testing a
requirement never silently changes its lifecycle. A requirement delivered with
its code starts
proposed;draftis a proposal not implemented yet. approvedbelongs to the owner. It freezes a requirement; only the owner agrees to approve or change one, recorded inapproved_byandapproved_on. Owners and approval locks come fromconfig.ymlper tier and scope. Repair steps for an agent: references/operations.md.
Route the intent
| Intent | Action |
|---|---|
| Understand what belongs in requirements | Apply the core model and distinguish stakeholder outcomes from software behavior. |
| Set up a requirements base | Use the okfreq-setup skill when it is installed; otherwise run okfreq init <project> and review the generated configuration, schemas, and local guideline before authoring. |
| Capture stakeholder intent | Create an StRS with a stakeholder-observable SHALL statement and a preserved --user-need. |
| Refine intent into software behavior | Create an SwRS with one bounded SHALL response and at least one valid StRS --derives-from parent. |
| Implement a software requirement | Change code and focused tests together, add source/test markers near the evidence, run tests, then refresh coverage explicitly. |
| Inspect gaps or change impact | Use trace, graph, status, validation, and reports without mutating authored content. |
| Audit or reconcile a brownfield bundle | Use okfreq-gardening, which extends this skill with an explicit maintenance workflow. |
| Troubleshoot generic OKF structure or schemas | Use okf-schema. |
If a named specialized skill is unavailable, apply this skill's model and the local requirements guideline directly.
Set up safely
okfreq init <project> creates a split bundle without overwriting existing
files:
<bundle>/
├── config.yml
├── guidelines/
│ └── requirements.guidelines.md
└── tiers/
├── _schema/
├── index.md
├── log.md
├── strs/
└── swrs/
The guidelines/ and tiers/ directories are siblings under the requirements
bundle. Confirm that the project-local guideline was installed, then review and
adapt it for the repository. If initialization preserves an existing guideline,
keep using that local file; do not replace it with this skill's fallback.
Why requirement schemas declare file links
Apply the generic okf-schema annotation and checker; okfreq does not own a
separate file-link type or resolution engine. The general contract belongs to
the okf-schema skill, while this section applies it to requirements evidence.
Requirement frontmatter uses strings for IDs and arrays for evidence. A parser
or editor otherwise cannot tell whether a value is a file to open, a local
requirement relationship, or an identifier in an external tool. x-okf-link
records that meaning without changing the frontmatter shape, and without
replacing the existing requirement-ID validation.
For example, a generated schema describes exact project files separately from requirement filename stems:
properties:
implemented_in_files:
type: array
items:
type: string
x-okf-link:
resolution: project-relative
syntax: plain
basename_marker: '@implements_req'
id_marker: id
show_line_number: true
tested_in_files:
type: array
items:
type: string
x-okf-link:
resolution: project-relative
syntax: plain
basename_marker: '@tests_req'
id_marker: id
show_line_number: true
derives_from:
type: array
items:
type: string
x-okf-link:
resolution: filename-stem
syntax: plain
id_marker: id
tooltip_shows_fields: [description]
preview_shows_fields: [description]
external_id:
type: string
The corresponding SwRS frontmatter might be:
id: SwRS-demo-001
derives_from:
- StRS-demo-001
implemented_in_files:
- src/report/export.py
tested_in_files:
- tests/test_export.py
external_id: DOORS-4821
With this metadata, a consumer can open src/report/export.py and
tests/test_export.py from the project root, navigate StRS-demo-001 to the
Markdown file with that exact stem, and leave DOORS-4821 as an external
identifier. The fields are still ordinary strings and lists of strings.
The optional navigation hints make the next editor action deterministic:
basename_marker records the marker prefix to search for in the resolved source
or test file, and id_marker: id says to use the requirement's id value as
the marker identity. A consumer can then find @implements_req <id> or
@tests_req <id> and open directly on that line. For a requirement link,
id_marker: id identifies the target frontmatter id line. A basename means
the filename without its extension. These hints are x-okf-link metadata for
consumers; okfreq --check-links verifies target files but does not scan marker
lines or treat them as proof of implementation or test success.
New bundles created by okfreq init also include advisory display hints:
tooltip_shows_fields and preview_shows_fields suggest that a consumer show
the linked requirement's description, while show_line_number requests the
source or test marker line in a navigation target. The CLI does not render
tooltips or previews itself; editors and other consumers decide how to present
these hints. Existing schemas are preserved and are not migrated automatically.
When an agent needs structured navigation data, use
okf_schema.api.inspect_file_links to obtain successful resolutions and
diagnostics together. Use check_file_links for validation-only workflows.
Neither API executes tests or treats a marker as proof beyond the configured
traceability report.
implemented_in_files and tested_in_files use exact project-relative paths.
derives_from, derived_by, depends_on, superseded_by, supersedes, and
relates_to use case-sensitive Markdown
filename stems without .md. Preserve the existing requirement-ID graph
validation and use matching requirement IDs and basenames for file navigation.
external_id is not a local-file annotation. Initialization preserves existing
schemas, so inspect them rather than assuming they already contain these hints.
Existing bundles are not migrated or rewritten. Do not replace their schemas
or change authored values merely to add file-navigation annotations.
okfreq validate requirements --check-links --project-root .
okfreq lint requirements --check-links --project-root .
Checks are off by default. Explicit project roots take precedence over Git
roots; the CLI cannot infer editor workspaces. Missing exact files and missing or
ambiguous bundle-local stems fail with E10; unavailable roots and inaccessible
candidates produce explicit W15 skips. A skipped check is not a verified
link. Keep syntax separate from resolution: a wikilink can contain a heading
or label, while these generated fields use plain strings. Use the
okf-schema skill for the full annotation contract and custom scalar links.
Author and implement requirements
Use the frontmatter title as the first Markdown heading (## Title),
keeping them synchronized when renaming a requirement. EARS is the statement
format, not a generic document heading.
- Create or confirm the stakeholder outcome first. An StRS needs one stakeholder-observable normative behavior, the stakeholder's user need, and any known rationale or constraints. Do not add software scenarios or source markers. Add a direct test marker only when the configured StRS coverage mode requires an explicit validation test.
- Derive one or more SwRS requirements for independently observable software behaviors. Each SwRS needs a valid StRS parent, nominal and boundary/failure scenarios, and objective verification notes.
- Replace every scaffold placeholder before review. A remaining angle-bracket placeholder is an explicit authoring gap, not text to delete merely to make prose checks quiet.
- Implement the SwRS and focused tests. Put markers close to the behavior they identify, using the configured marker names and comment syntax appropriate for each file.
- Preview generated changes with
okfreq update-coverage <bundle> --checkor--diff, then apply them intentionally. Never hand-edit generated coverage, reverse links, indexes, or reports. - Run the local guideline's validation commands and the project's test suite. At minimum, validate and lint with prose checks and inspect trace output.
Universal guardrails
- Preserve requirement IDs, UUIDs, authored fields, unknown metadata, YAML comments, Markdown bodies, and authored relationships.
- Never invent stakeholder intent, evidence, verification results, approval, exemptions, or lifecycle transitions.
- Never renumber an existing requirement. Allocate new identities through
okfreq newunder the configured ID policy. - Never treat generated
derived_by,supersedes,implemented_in_files,tested_in_filesordefault_owner_emailas authored truth. - Keep
okfreqrequirements independent fromokfkbknowledge documents. They may coexist and both use OKF-compatible Markdown, but they have distinct purposes and lifecycles. - Preserve unrelated work and report unresolved intent or hierarchy questions instead of guessing.
Completion
Summarize requirements and evidence changed, generated fields refreshed, lifecycle changes explicitly approved, validation and test results, and any remaining gaps. Do not claim complete traceability when a non-exempt leaf lacks source or test evidence, markers reference unknown IDs, or validation/tests failed or did not run.
Maintain OKF navigation and history
After editing requirements run okfreq lint <bundle> to refresh marked indexes
at the tiers root and every tier/scope directory. Preserve authored text outside
the generated blocks and the optional bundle-root overview. Use --diff for a
read-only preview and --check for CI; lint otherwise writes generated navigation.
Append meaningful changes, affected IDs, rationale and actual verification to
<bundle>/tiers/log.md, preserving history. Logs are authored, never generated.
Read the bundled operations reference for marker delimiters and exact commands.
04 同仓库更多 Skills
Local tooling guide
Documents nested YAML and list metadata for the editor preview.
writing-for-markdown-okf-schema-studio
Write or generate a Markdown document (implementation plan, report, design note, README, spec, runbook) that renders well in Markdown OKF Schema Studio, the VS Code Markdown preview. Use when asked to write, draft or generate a .md file for Markdown OKF Schema Studio, to make a document look good in it, or to choose diagrams, charts, cards, tabs or admonitions for it.
okfreq-gardening
Audit and improve an okfreq requirements bundle by finding missing traceability, stale requirements, broken hierarchy links, coverage gaps, and configuration drift while preserving authored content and generated-field ownership.
markdown-studio-exploratory-qa
This skill runs exploratory QA campaigns for Markdown OKF-Schema Studio when requested.
markdown-studio-exploratory-qa-claude
This skill should be used when asked to run, resume, or re-validate an exploratory QA campaign on the Markdown OKF-Schema Studio VS Code extension in a real VS Code window (real mouse and keyboard through CDP), and to write one bug sheet per finding under .agents/changes/3-requests/. A Foreman picks charters from a coverage map and the PRs merged since the last campaign, hands groups of charters to QA Driver sub-agents, and each Driver runs charter agents that drive their own window with scenario files and automatic checks. It ships the driver, scenario engine, no-op sweep, a read-only spy extension, synthetic fixtures, a use-case catalogue, and the harness pitfalls learned in previous campaigns.
change-requests-factory
A 4 layers software factory able to chains and parallelize Change Requests implementation