AGENT SKILL

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

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

  1. 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 owns config.yml; its requirement documents and schemas normally live in tiers/.
  2. Read the nearest AGENTS.md and any requirements guideline it registers.
  3. Read <bundle>/guidelines/requirements.guidelines.md, installed by okfreq init, then any other guideline file in that folder (by convention project.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 from config.yml, AGENTS.md, and the project itself rather than assuming that example names apply universally.
  4. Never put project rules in requirements.guidelines.md: okfreq init <bundle> --force replaces it with the packaged text, which is how a missing or outdated copy is installed or refreshed. It leaves every other file of guidelines/ untouched.
  5. Before changing requirements, read config.yml and every schema under tiers/_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; let okfreq compute reverse derived_by links. Likewise author superseded_by (through okfreq supersede OLD NEW...) and let okfreq compute supersedes; use relates_to for 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 stricter linked-swrs-and-validation-test mode, 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; draft is a proposal not implemented yet.
  • approved belongs to the owner. It freezes a requirement; only the owner agrees to approve or change one, recorded in approved_by and approved_on. Owners and approval locks come from config.yml per 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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Preview generated changes with okfreq update-coverage <bundle> --check or --diff, then apply them intentionally. Never hand-edit generated coverage, reverse links, indexes, or reports.
  6. 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

  1. Preserve requirement IDs, UUIDs, authored fields, unknown metadata, YAML comments, Markdown bodies, and authored relationships.
  2. Never invent stakeholder intent, evidence, verification results, approval, exemptions, or lifecycle transitions.
  3. Never renumber an existing requirement. Allocate new identities through okfreq new under the configured ID policy.
  4. Never treat generated derived_by, supersedes, implemented_in_files, tested_in_files or default_owner_email as authored truth.
  5. Keep okfreq requirements independent from okfkb knowledge documents. They may coexist and both use OKF-compatible Markdown, but they have distinct purposes and lifecycles.
  6. 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

gsemet
gsemet/markdown-okf-schema-studio

Local tooling guide

Documents nested YAML and list metadata for the editor preview.

★ 6
gsemet
gsemet/markdown-okf-schema-studio

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.

★ 6
gsemet
gsemet/markdown-okf-schema-studio

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.

★ 6
gsemet
gsemet/markdown-okf-schema-studio

markdown-studio-exploratory-qa

This skill runs exploratory QA campaigns for Markdown OKF-Schema Studio when requested.

★ 6
gsemet
gsemet/markdown-okf-schema-studio

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.

★ 6
gsemet
gsemet/markdown-okf-schema-studio

change-requests-factory

A 4 layers software factory able to chains and parallelize Change Requests implementation

★ 6