[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7ENCE0C7JS06RBQPJ64YGNZ":3,"skill-same:01M7ENCE0C7JS06RBQPJ64YGNZ":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":35,"commitSha":36,"skillDirectory":37,"forksCount":38,"repositoryHtmlUrl":39,"repositoryHomepageUrl":6,"ownerHtmlUrl":40,"ownerBlogUrl":6,"ownerDescription":41,"updatedAt":42,"install":43,"resources":56},"01M7ENCE0C7JS06RBQPJ64YGNZ","okfreq",null,"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.","gsemet\u002Fmarkdown-okf-schema-studio","gsemet","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F133498?v=4","01M7ENBEXKFDNNNXEN1YNE0CJ4","Gaetan Semet","01M7ENBEY56X9KMNA0YHQF56EN",6,"MIT","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fokfreq\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: okfreq\ndescription: '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.'\nmetadata:\n  keywords: [okfreq, requirements, living-requirements, traceability, StRS, SwRS, implementation-markers, test-markers, coverage]\n  url: https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fokf-schema\n---\n\n# okfreq\n\n\u003C!-- @implements_req SwRS-OKFSCHEMA-OKFREQ-008 -->\n\nUse `okfreq` to maintain a living requirements specification beside the code.\nIts goal is to keep stakeholder intent connected to observable software\nbehavior, implementation, tests, and reviewable gap reports as the project\nchanges. Teach that model, identify the user's intent, then use the smallest\nappropriate workflow.\n\nThis skill explains the **requirements and traceability lifecycle**. Use the\n`okf-schema` skill for generic OKF conformance, schemas, frontmatter mechanics,\nor implementation details of the underlying tool.\n\n## Progressive references\n\nKeep this entrypoint as the first read. The packaged operations reference is\nself-contained: agents need the installed CLI and target project, not this\npackage's source code or documentation website. The requirements guideline is\nnot shipped with this skill: `okfreq init` installs it into the bundle as\n`\u003Cbundle>\u002Fguidelines\u002Frequirements.guidelines.md`, and that file is the single\nguideline to follow.\n\n| Need | Read |\n|---|---|\n| Commands, backfilling existing features, harness setup, reports, or troubleshooting | [Standalone operations](references\u002Foperations.md) |\n\n## Installation\n\nInstall or upgrade the Python CLI tool with `uv`:\n\n```bash\nuv tool install okf-schema\nuv tool upgrade okf-schema\n```\n\nThis tool installation exposes the `okf-schema`, `okfkb`, and `okfreq` console\ncommands. It is separate from installing agent skill folders: use\n`okfreq install-skills` to copy the packaged `okfreq` skill family into an\nagent's skills directory.\n\n## Start with project rules\n\n1. Locate the requirements bundle. Prefer an explicit path, then a top-level\n   `requirements\u002F`, then `.agents\u002Frequirements\u002F`, and finally\n   `.github\u002Frequirements\u002F`. The bundle root is the directory that owns\n   `config.yml`; its requirement documents and schemas normally live in\n   `tiers\u002F`.\n2. Read the nearest `AGENTS.md` and any requirements guideline it registers.\n3. Read `\u003Cbundle>\u002Fguidelines\u002Frequirements.guidelines.md`, installed by\n   `okfreq init`, then any other guideline file in that folder (by convention\n   `project.guidelines.md`). The project files carry local paths, scopes,\n   commands, and review rules and win where they specialize the shared text.\n   Resolve project-specific paths, scopes, and quality commands from\n   `config.yml`, `AGENTS.md`, and the project itself rather than assuming that\n   example names apply universally.\n4. Never put project rules in `requirements.guidelines.md`:\n   `okfreq init \u003Cbundle> --force` replaces it with the packaged text, which is\n   how a missing or outdated copy is installed or refreshed. It leaves every\n   other file of `guidelines\u002F` untouched.\n5. Before changing requirements, read `config.yml` and every schema under\n   `tiers\u002F_schema\u002F`. Local configuration and schemas define the actual tiers,\n   hierarchy, IDs, lifecycle values, owners, approval locks, markers, scopes, and\n   allowed fields.\n\n## The goal of okfreq\n\n`okfreq` demonstrates an agent-friendly way to keep production-level,\nstructured living requirements that stay aligned with code and tests and expose\ntraceability gaps. It does not pretend that generated files are the ultimate\nsource of stakeholder truth.\n\nTreat the requirements base as a maintained, reviewable representation of what\nthe implemented system is expected to do. Compare it with the original intent,\nthen explicitly accept or adapt it as implementation teaches the team more.\nRequirements may evolve; silent drift must not.\n\nA useful requirement states one agreed behavior or constraint precisely enough\nthat a developer can implement it and a tester can decide whether it is\nsatisfied. It is not an issue title, design choice, code comment, or task.\n\n## Core model\n\n- **StRS captures stakeholder intent.** It states a stakeholder-observable goal\n  or use case and preserves the underlying user need without prescribing the\n  implementation.\n- **SwRS captures observable software behavior.** It refines one or more StRS\n  requirements into bounded behavior that code can implement and tests can\n  observe.\n- **Authored derivation points upward.** Author `derives_from`; let `okfreq`\n  compute reverse `derived_by` links. Likewise author `superseded_by` (through\n  `okfreq supersede OLD NEW...`) and let `okfreq` compute `supersedes`; use\n  `relates_to` for lateral links with no derivation or replacement meaning.\n- **Leaf requirements connect to evidence.** Place `@implements_req \u003CID>` near\n   the relevant production behavior and `@tests_req \u003CID>` near each relevant\n   test. The same ID may repeat at distinct evidence points in one file.\n   StRS never receives implementation markers; in the stricter\n   `linked-swrs-and-validation-test` mode, a direct `@tests_req \u003CStRS-ID>` marker\n   defines a stakeholder validation test.\n- **Markers are links, not proof.** A test marker says where verification lives,\n  not whether the test ran or passed. Run the project's real test suite.\n- **Coverage and reports are generated views.** Keep implementation coverage,\n  test-link coverage, structural health, and lifecycle counts separate; do not\n  collapse them into a misleading success score.\n- **Lifecycle is explicit.** Creating, formatting, linking, or testing a\n  requirement never silently changes its lifecycle. A requirement delivered with\n  its code starts `proposed`; `draft` is a proposal not implemented yet.\n- **`approved` belongs to the owner.** It freezes a requirement; only the owner\n  agrees to approve or change one, recorded in `approved_by` and `approved_on`.\n  Owners and approval locks come from `config.yml` per tier and scope. Repair\n  steps for an agent: [references\u002Foperations.md](references\u002Foperations.md#lifecycle-ownership-and-approval).\n\n## Route the intent\n\n| Intent | Action |\n|---|---|\n| Understand what belongs in requirements | Apply the core model and distinguish stakeholder outcomes from software behavior. |\n| Set up a requirements base | Use the `okfreq-setup` skill when it is installed; otherwise run `okfreq init \u003Cproject>` and review the generated configuration, schemas, and local guideline before authoring. |\n| Capture stakeholder intent | Create an StRS with a stakeholder-observable `SHALL` statement and a preserved `--user-need`. |\n| Refine intent into software behavior | Create an SwRS with one bounded `SHALL` response and at least one valid StRS `--derives-from` parent. |\n| Implement a software requirement | Change code and focused tests together, add source\u002Ftest markers near the evidence, run tests, then refresh coverage explicitly. |\n| Inspect gaps or change impact | Use `trace`, `graph`, `status`, validation, and reports without mutating authored content. |\n| Audit or reconcile a brownfield bundle | Use `okfreq-gardening`, which extends this skill with an explicit maintenance workflow. |\n| Troubleshoot generic OKF structure or schemas | Use `okf-schema`. |\n\nIf a named specialized skill is unavailable, apply this skill's model and the\nlocal requirements guideline directly.\n\n## Set up safely\n\n`okfreq init \u003Cproject>` creates a split bundle without overwriting existing\nfiles:\n\n```text\n\u003Cbundle>\u002F\n├── config.yml\n├── guidelines\u002F\n│   └── requirements.guidelines.md\n└── tiers\u002F\n    ├── _schema\u002F\n    ├── index.md\n    ├── log.md\n    ├── strs\u002F\n    └── swrs\u002F\n```\n\nThe `guidelines\u002F` and `tiers\u002F` directories are siblings under the requirements\nbundle. Confirm that the project-local guideline was installed, then review and\nadapt it for the repository. If initialization preserves an existing guideline,\nkeep using that local file; do not replace it with this skill's fallback.\n\n## Why requirement schemas declare file links\n\nApply the generic `okf-schema` annotation and checker; `okfreq` does not own a\nseparate file-link type or resolution engine. The general contract belongs to\nthe `okf-schema` skill, while this section applies it to requirements evidence.\n\nRequirement frontmatter uses strings for IDs and arrays for evidence. A parser\nor editor otherwise cannot tell whether a value is a file to open, a local\nrequirement relationship, or an identifier in an external tool. `x-okf-link`\nrecords that meaning without changing the frontmatter shape, and without\nreplacing the existing requirement-ID validation.\n\nFor example, a generated schema describes exact project files separately from\nrequirement filename stems:\n\n```yaml\nproperties:\n   implemented_in_files:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: project-relative\n            syntax: plain\n            basename_marker: '@implements_req'\n            id_marker: id\n            show_line_number: true\n   tested_in_files:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: project-relative\n            syntax: plain\n            basename_marker: '@tests_req'\n            id_marker: id\n            show_line_number: true\n   derives_from:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: filename-stem\n            syntax: plain\n            id_marker: id\n            tooltip_shows_fields: [description]\n            preview_shows_fields: [description]\n   external_id:\n      type: string\n```\n\nThe corresponding `SwRS` frontmatter might be:\n\n```yaml\nid: SwRS-demo-001\nderives_from:\n  - StRS-demo-001\nimplemented_in_files:\n  - src\u002Freport\u002Fexport.py\ntested_in_files:\n  - tests\u002Ftest_export.py\nexternal_id: DOORS-4821\n```\n\nWith this metadata, a consumer can open `src\u002Freport\u002Fexport.py` and\n`tests\u002Ftest_export.py` from the project root, navigate `StRS-demo-001` to the\nMarkdown file with that exact stem, and leave `DOORS-4821` as an external\nidentifier. The fields are still ordinary strings and lists of strings.\n\nThe optional navigation hints make the next editor action deterministic:\n`basename_marker` records the marker prefix to search for in the resolved source\nor test file, and `id_marker: id` says to use the requirement's `id` value as\nthe marker identity. A consumer can then find `@implements_req \u003Cid>` or\n`@tests_req \u003Cid>` and open directly on that line. For a requirement link,\n`id_marker: id` identifies the target frontmatter `id` line. A basename means\nthe filename without its extension. These hints are `x-okf-link` metadata for\nconsumers; `okfreq --check-links` verifies target files but does not scan marker\nlines or treat them as proof of implementation or test success.\n\nNew bundles created by `okfreq init` also include advisory display hints:\n`tooltip_shows_fields` and `preview_shows_fields` suggest that a consumer show\nthe linked requirement's `description`, while `show_line_number` requests the\nsource or test marker line in a navigation target. The CLI does not render\ntooltips or previews itself; editors and other consumers decide how to present\nthese hints. Existing schemas are preserved and are not migrated automatically.\n\nWhen an agent needs structured navigation data, use\n`okf_schema.api.inspect_file_links` to obtain successful resolutions and\ndiagnostics together. Use `check_file_links` for validation-only workflows.\nNeither API executes tests or treats a marker as proof beyond the configured\ntraceability report.\n\n`implemented_in_files` and `tested_in_files` use exact project-relative paths.\n`derives_from`, `derived_by`, `depends_on`, `superseded_by`, `supersedes`, and\n`relates_to` use case-sensitive Markdown\nfilename stems without `.md`. Preserve the existing requirement-ID graph\nvalidation and use matching requirement IDs and basenames for file navigation.\n`external_id` is not a local-file annotation. Initialization preserves existing\nschemas, so inspect them rather than assuming they already contain these hints.\nExisting bundles are not migrated or rewritten. Do not replace their schemas\nor change authored values merely to add file-navigation annotations.\n\n```bash\nokfreq validate requirements --check-links --project-root .\nokfreq lint requirements --check-links --project-root .\n```\n\nChecks are off by default. Explicit project roots take precedence over Git\nroots; the CLI cannot infer editor workspaces. Missing exact files and missing or\nambiguous bundle-local stems fail with `E10`; unavailable roots and inaccessible\ncandidates produce explicit `W15` skips. A skipped check is not a verified\nlink. Keep syntax separate from resolution: a `wikilink` can contain a heading\nor label, while these generated fields use `plain` strings. Use the\n`okf-schema` skill for the full annotation contract and custom scalar links.\n\n## Author and implement requirements\n\nUse the frontmatter `title` as the first Markdown heading (`## Title`),\nkeeping them synchronized when renaming a requirement. EARS is the statement\nformat, not a generic document heading.\n\n1. Create or confirm the stakeholder outcome first. An StRS needs one\n   stakeholder-observable normative behavior, the stakeholder's user need, and\n   any known rationale or constraints. Do not add software scenarios or source\n   markers. Add a direct test marker only when the configured StRS coverage mode\n   requires an explicit validation test.\n2. Derive one or more SwRS requirements for independently observable software\n   behaviors. Each SwRS needs a valid StRS parent, nominal and boundary\u002Ffailure\n   scenarios, and objective verification notes.\n3. Replace every scaffold placeholder before review. A remaining angle-bracket\n   placeholder is an explicit authoring gap, not text to delete merely to make\n   prose checks quiet.\n4. Implement the SwRS and focused tests. Put markers close to the behavior they\n   identify, using the configured marker names and comment syntax appropriate\n   for each file.\n5. Preview generated changes with `okfreq update-coverage \u003Cbundle> --check` or\n   `--diff`, then apply them intentionally. Never hand-edit generated coverage,\n   reverse links, indexes, or reports.\n6. Run the local guideline's validation commands and the project's test suite.\n   At minimum, validate and lint with prose checks and inspect trace output.\n\n## Universal guardrails\n\n1. Preserve requirement IDs, UUIDs, authored fields, unknown metadata, YAML\n   comments, Markdown bodies, and authored relationships.\n2. Never invent stakeholder intent, evidence, verification results, approval,\n   exemptions, or lifecycle transitions.\n3. Never renumber an existing requirement. Allocate new identities through\n   `okfreq new` under the configured ID policy.\n4. Never treat generated `derived_by`, `supersedes`, `implemented_in_files`,\n   `tested_in_files` or `default_owner_email` as authored truth.\n5. Keep `okfreq` requirements independent from `okfkb` knowledge documents.\n   They may coexist and both use OKF-compatible Markdown, but they have distinct\n   purposes and lifecycles.\n6. Preserve unrelated work and report unresolved intent or hierarchy questions\n   instead of guessing.\n\n## Completion\n\nSummarize requirements and evidence changed, generated fields refreshed,\nlifecycle changes explicitly approved, validation and test results, and any\nremaining gaps. Do not claim complete traceability when a non-exempt leaf lacks\nsource or test evidence, markers reference unknown IDs, or validation\u002Ftests\nfailed or did not run.\n\n## Maintain OKF navigation and history\n\nAfter editing requirements run `okfreq lint \u003Cbundle>` to refresh marked indexes\nat the tiers root and every tier\u002Fscope directory. Preserve authored text outside\nthe generated blocks and the optional bundle-root overview. Use `--diff` for a\nread-only preview and `--check` for CI; lint otherwise writes generated navigation.\nAppend meaningful changes, affected IDs, rationale and actual verification to\n`\u003Cbundle>\u002Ftiers\u002Flog.md`, preserving history. Logs are authored, never generated.\nRead the bundled operations reference for marker delimiters and exact commands.\n","# okfreq\n\n\u003C!-- @implements_req SwRS-OKFSCHEMA-OKFREQ-008 -->\n\nUse `okfreq` to maintain a living requirements specification beside the code.\nIts goal is to keep stakeholder intent connected to observable software\nbehavior, implementation, tests, and reviewable gap reports as the project\nchanges. Teach that model, identify the user's intent, then use the smallest\nappropriate workflow.\n\nThis skill explains the **requirements and traceability lifecycle**. Use the\n`okf-schema` skill for generic OKF conformance, schemas, frontmatter mechanics,\nor implementation details of the underlying tool.\n\n## Progressive references\n\nKeep this entrypoint as the first read. The packaged operations reference is\nself-contained: agents need the installed CLI and target project, not this\npackage's source code or documentation website. The requirements guideline is\nnot shipped with this skill: `okfreq init` installs it into the bundle as\n`\u003Cbundle>\u002Fguidelines\u002Frequirements.guidelines.md`, and that file is the single\nguideline to follow.\n\n| Need | Read |\n|---|---|\n| Commands, backfilling existing features, harness setup, reports, or troubleshooting | [Standalone operations](references\u002Foperations.md) |\n\n## Installation\n\nInstall or upgrade the Python CLI tool with `uv`:\n\n```bash\nuv tool install okf-schema\nuv tool upgrade okf-schema\n```\n\nThis tool installation exposes the `okf-schema`, `okfkb`, and `okfreq` console\ncommands. It is separate from installing agent skill folders: use\n`okfreq install-skills` to copy the packaged `okfreq` skill family into an\nagent's skills directory.\n\n## Start with project rules\n\n1. Locate the requirements bundle. Prefer an explicit path, then a top-level\n   `requirements\u002F`, then `.agents\u002Frequirements\u002F`, and finally\n   `.github\u002Frequirements\u002F`. The bundle root is the directory that owns\n   `config.yml`; its requirement documents and schemas normally live in\n   `tiers\u002F`.\n2. Read the nearest `AGENTS.md` and any requirements guideline it registers.\n3. Read `\u003Cbundle>\u002Fguidelines\u002Frequirements.guidelines.md`, installed by\n   `okfreq init`, then any other guideline file in that folder (by convention\n   `project.guidelines.md`). The project files carry local paths, scopes,\n   commands, and review rules and win where they specialize the shared text.\n   Resolve project-specific paths, scopes, and quality commands from\n   `config.yml`, `AGENTS.md`, and the project itself rather than assuming that\n   example names apply universally.\n4. Never put project rules in `requirements.guidelines.md`:\n   `okfreq init \u003Cbundle> --force` replaces it with the packaged text, which is\n   how a missing or outdated copy is installed or refreshed. It leaves every\n   other file of `guidelines\u002F` untouched.\n5. Before changing requirements, read `config.yml` and every schema under\n   `tiers\u002F_schema\u002F`. Local configuration and schemas define the actual tiers,\n   hierarchy, IDs, lifecycle values, owners, approval locks, markers, scopes, and\n   allowed fields.\n\n## The goal of okfreq\n\n`okfreq` demonstrates an agent-friendly way to keep production-level,\nstructured living requirements that stay aligned with code and tests and expose\ntraceability gaps. It does not pretend that generated files are the ultimate\nsource of stakeholder truth.\n\nTreat the requirements base as a maintained, reviewable representation of what\nthe implemented system is expected to do. Compare it with the original intent,\nthen explicitly accept or adapt it as implementation teaches the team more.\nRequirements may evolve; silent drift must not.\n\nA useful requirement states one agreed behavior or constraint precisely enough\nthat a developer can implement it and a tester can decide whether it is\nsatisfied. It is not an issue title, design choice, code comment, or task.\n\n## Core model\n\n- **StRS captures stakeholder intent.** It states a stakeholder-observable goal\n  or use case and preserves the underlying user need without prescribing the\n  implementation.\n- **SwRS captures observable software behavior.** It refines one or more StRS\n  requirements into bounded behavior that code can implement and tests can\n  observe.\n- **Authored derivation points upward.** Author `derives_from`; let `okfreq`\n  compute reverse `derived_by` links. Likewise author `superseded_by` (through\n  `okfreq supersede OLD NEW...`) and let `okfreq` compute `supersedes`; use\n  `relates_to` for lateral links with no derivation or replacement meaning.\n- **Leaf requirements connect to evidence.** Place `@implements_req \u003CID>` near\n   the relevant production behavior and `@tests_req \u003CID>` near each relevant\n   test. The same ID may repeat at distinct evidence points in one file.\n   StRS never receives implementation markers; in the stricter\n   `linked-swrs-and-validation-test` mode, a direct `@tests_req \u003CStRS-ID>` marker\n   defines a stakeholder validation test.\n- **Markers are links, not proof.** A test marker says where verification lives,\n  not whether the test ran or passed. Run the project's real test suite.\n- **Coverage and reports are generated views.** Keep implementation coverage,\n  test-link coverage, structural health, and lifecycle counts separate; do not\n  collapse them into a misleading success score.\n- **Lifecycle is explicit.** Creating, formatting, linking, or testing a\n  requirement never silently changes its lifecycle. A requirement delivered with\n  its code starts `proposed`; `draft` is a proposal not implemented yet.\n- **`approved` belongs to the owner.** It freezes a requirement; only the owner\n  agrees to approve or change one, recorded in `approved_by` and `approved_on`.\n  Owners and approval locks come from `config.yml` per tier and scope. Repair\n  steps for an agent: [references\u002Foperations.md](references\u002Foperations.md#lifecycle-ownership-and-approval).\n\n## Route the intent\n\n| Intent | Action |\n|---|---|\n| Understand what belongs in requirements | Apply the core model and distinguish stakeholder outcomes from software behavior. |\n| Set up a requirements base | Use the `okfreq-setup` skill when it is installed; otherwise run `okfreq init \u003Cproject>` and review the generated configuration, schemas, and local guideline before authoring. |\n| Capture stakeholder intent | Create an StRS with a stakeholder-observable `SHALL` statement and a preserved `--user-need`. |\n| Refine intent into software behavior | Create an SwRS with one bounded `SHALL` response and at least one valid StRS `--derives-from` parent. |\n| Implement a software requirement | Change code and focused tests together, add source\u002Ftest markers near the evidence, run tests, then refresh coverage explicitly. |\n| Inspect gaps or change impact | Use `trace`, `graph`, `status`, validation, and reports without mutating authored content. |\n| Audit or reconcile a brownfield bundle | Use `okfreq-gardening`, which extends this skill with an explicit maintenance workflow. |\n| Troubleshoot generic OKF structure or schemas | Use `okf-schema`. |\n\nIf a named specialized skill is unavailable, apply this skill's model and the\nlocal requirements guideline directly.\n\n## Set up safely\n\n`okfreq init \u003Cproject>` creates a split bundle without overwriting existing\nfiles:\n\n```text\n\u003Cbundle>\u002F\n├── config.yml\n├── guidelines\u002F\n│   └── requirements.guidelines.md\n└── tiers\u002F\n    ├── _schema\u002F\n    ├── index.md\n    ├── log.md\n    ├── strs\u002F\n    └── swrs\u002F\n```\n\nThe `guidelines\u002F` and `tiers\u002F` directories are siblings under the requirements\nbundle. Confirm that the project-local guideline was installed, then review and\nadapt it for the repository. If initialization preserves an existing guideline,\nkeep using that local file; do not replace it with this skill's fallback.\n\n## Why requirement schemas declare file links\n\nApply the generic `okf-schema` annotation and checker; `okfreq` does not own a\nseparate file-link type or resolution engine. The general contract belongs to\nthe `okf-schema` skill, while this section applies it to requirements evidence.\n\nRequirement frontmatter uses strings for IDs and arrays for evidence. A parser\nor editor otherwise cannot tell whether a value is a file to open, a local\nrequirement relationship, or an identifier in an external tool. `x-okf-link`\nrecords that meaning without changing the frontmatter shape, and without\nreplacing the existing requirement-ID validation.\n\nFor example, a generated schema describes exact project files separately from\nrequirement filename stems:\n\n```yaml\nproperties:\n   implemented_in_files:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: project-relative\n            syntax: plain\n            basename_marker: '@implements_req'\n            id_marker: id\n            show_line_number: true\n   tested_in_files:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: project-relative\n            syntax: plain\n            basename_marker: '@tests_req'\n            id_marker: id\n            show_line_number: true\n   derives_from:\n      type: array\n      items:\n         type: string\n         x-okf-link:\n            resolution: filename-stem\n            syntax: plain\n            id_marker: id\n            tooltip_shows_fields: [description]\n            preview_shows_fields: [description]\n   external_id:\n      type: string\n```\n\nThe corresponding `SwRS` frontmatter might be:\n\n```yaml\nid: SwRS-demo-001\nderives_from:\n  - StRS-demo-001\nimplemented_in_files:\n  - src\u002Freport\u002Fexport.py\ntested_in_files:\n  - tests\u002Ftest_export.py\nexternal_id: DOORS-4821\n```\n\nWith this metadata, a consumer can open `src\u002Freport\u002Fexport.py` and\n`tests\u002Ftest_export.py` from the project root, navigate `StRS-demo-001` to the\nMarkdown file with that exact stem, and leave `DOORS-4821` as an external\nidentifier. The fields are still ordinary strings and lists of strings.\n\nThe optional navigation hints make the next editor action deterministic:\n`basename_marker` records the marker prefix to search for in the resolved source\nor test file, and `id_marker: id` says to use the requirement's `id` value as\nthe marker identity. A consumer can then find `@implements_req \u003Cid>` or\n`@tests_req \u003Cid>` and open directly on that line. For a requirement link,\n`id_marker: id` identifies the target frontmatter `id` line. A basename means\nthe filename without its extension. These hints are `x-okf-link` metadata for\nconsumers; `okfreq --check-links` verifies target files but does not scan marker\nlines or treat them as proof of implementation or test success.\n\nNew bundles created by `okfreq init` also include advisory display hints:\n`tooltip_shows_fields` and `preview_shows_fields` suggest that a consumer show\nthe linked requirement's `description`, while `show_line_number` requests the\nsource or test marker line in a navigation target. The CLI does not render\ntooltips or previews itself; editors and other consumers decide how to present\nthese hints. Existing schemas are preserved and are not migrated automatically.\n\nWhen an agent needs structured navigation data, use\n`okf_schema.api.inspect_file_links` to obtain successful resolutions and\ndiagnostics together. Use `check_file_links` for validation-only workflows.\nNeither API executes tests or treats a marker as proof beyond the configured\ntraceability report.\n\n`implemented_in_files` and `tested_in_files` use exact project-relative paths.\n`derives_from`, `derived_by`, `depends_on`, `superseded_by`, `supersedes`, and\n`relates_to` use case-sensitive Markdown\nfilename stems without `.md`. Preserve the existing requirement-ID graph\nvalidation and use matching requirement IDs and basenames for file navigation.\n`external_id` is not a local-file annotation. Initialization preserves existing\nschemas, so inspect them rather than assuming they already contain these hints.\nExisting bundles are not migrated or rewritten. Do not replace their schemas\nor change authored values merely to add file-navigation annotations.\n\n```bash\nokfreq validate requirements --check-links --project-root .\nokfreq lint requirements --check-links --project-root .\n```\n\nChecks are off by default. Explicit project roots take precedence over Git\nroots; the CLI cannot infer editor workspaces. Missing exact files and missing or\nambiguous bundle-local stems fail with `E10`; unavailable roots and inaccessible\ncandidates produce explicit `W15` skips. A skipped check is not a verified\nlink. Keep syntax separate from resolution: a `wikilink` can contain a heading\nor label, while these generated fields use `plain` strings. Use the\n`okf-schema` skill for the full annotation contract and custom scalar links.\n\n## Author and implement requirements\n\nUse the frontmatter `title` as the first Markdown heading (`## Title`),\nkeeping them synchronized when renaming a requirement. EARS is the statement\nformat, not a generic document heading.\n\n1. Create or confirm the stakeholder outcome first. An StRS needs one\n   stakeholder-observable normative behavior, the stakeholder's user need, and\n   any known rationale or constraints. Do not add software scenarios or source\n   markers. Add a direct test marker only when the configured StRS coverage mode\n   requires an explicit validation test.\n2. Derive one or more SwRS requirements for independently observable software\n   behaviors. Each SwRS needs a valid StRS parent, nominal and boundary\u002Ffailure\n   scenarios, and objective verification notes.\n3. Replace every scaffold placeholder before review. A remaining angle-bracket\n   placeholder is an explicit authoring gap, not text to delete merely to make\n   prose checks quiet.\n4. Implement the SwRS and focused tests. Put markers close to the behavior they\n   identify, using the configured marker names and comment syntax appropriate\n   for each file.\n5. Preview generated changes with `okfreq update-coverage \u003Cbundle> --check` or\n   `--diff`, then apply them intentionally. Never hand-edit generated coverage,\n   reverse links, indexes, or reports.\n6. Run the local guideline's validation commands and the project's test suite.\n   At minimum, validate and lint with prose checks and inspect trace output.\n\n## Universal guardrails\n\n1. Preserve requirement IDs, UUIDs, authored fields, unknown metadata, YAML\n   comments, Markdown bodies, and authored relationships.\n2. Never invent stakeholder intent, evidence, verification results, approval,\n   exemptions, or lifecycle transitions.\n3. Never renumber an existing requirement. Allocate new identities through\n   `okfreq new` under the configured ID policy.\n4. Never treat generated `derived_by`, `supersedes`, `implemented_in_files`,\n   `tested_in_files` or `default_owner_email` as authored truth.\n5. Keep `okfreq` requirements independent from `okfkb` knowledge documents.\n   They may coexist and both use OKF-compatible Markdown, but they have distinct\n   purposes and lifecycles.\n6. Preserve unrelated work and report unresolved intent or hierarchy questions\n   instead of guessing.\n\n## Completion\n\nSummarize requirements and evidence changed, generated fields refreshed,\nlifecycle changes explicitly approved, validation and test results, and any\nremaining gaps. Do not claim complete traceability when a non-exempt leaf lacks\nsource or test evidence, markers reference unknown IDs, or validation\u002Ftests\nfailed or did not run.\n\n## Maintain OKF navigation and history\n\nAfter editing requirements run `okfreq lint \u003Cbundle>` to refresh marked indexes\nat the tiers root and every tier\u002Fscope directory. Preserve authored text outside\nthe generated blocks and the optional bundle-root overview. Use `--diff` for a\nread-only preview and `--check` for CI; lint otherwise writes generated navigation.\nAppend meaningful changes, affected IDs, rationale and actual verification to\n`\u003Cbundle>\u002Ftiers\u002Flog.md`, preserving history. Logs are authored, never generated.\nRead the bundled operations reference for marker delimiters and exact commands.\n",{"name":5,"metadata":24,"description":7},{"url":25,"keywords":26},"https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fokf-schema",[5,27,28,29,30,31,32,33,34],"requirements","living-requirements","traceability","StRS","SwRS","implementation-markers","test-markers","coverage","main","e8b7d463f623160cf740b763ece656ded8592052",".agents\u002Fskills\u002Fokfreq",0,"https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio","https:\u002F\u002Fgithub.com\u002Fgsemet","Senior SW Engineer & AI practitioner • Agentic coding, Python, scaling IA • Work at Ampere Software Technologies, making Renault Electric cars","2026-11-15 01:07:51",{"source":8,"skillName":5,"commands":44,"prompt":54,"zipAvailable":55},[45,48,51],{"tool":46,"command":47},"npx","npx skills add gsemet\u002Fmarkdown-okf-schema-studio --skill okfreq",{"tool":49,"command":50},"bunx","bunx skills add gsemet\u002Fmarkdown-okf-schema-studio --skill okfreq",{"tool":52,"command":53},"pnpm","pnpm dlx skills add gsemet\u002Fmarkdown-okf-schema-studio --skill okfreq","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fokfreq\u002FSKILL.md",true,[57],{"path":58,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Foperations.md","REFERENCE","参考文档",16502,"https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fokfreq\u002Freferences\u002Foperations.md",[64,71,78,85,92,99],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M7ENCR7A88JV6EAHSP2VHNG1","Local tooling guide","Documents nested YAML and list metadata for the editor preview.","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002Ftest\u002Fvisual\u002Ffixtures\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M7ENCKB75WDXQ1EZGQ0B9K1N","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.","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-for-markdown-okf-schema-studio\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M7ENC8X330E0AVBD5AMZE5W9","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.","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fokfreq-gardening\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7ENC5MRRCB2CQ446J26Z5Y8","markdown-studio-exploratory-qa","This skill runs exploratory QA campaigns for Markdown OKF-Schema Studio when requested.","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmarkdown-studio-exploratory-qa\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7ENBRZE7R7D3D87NCCMDN4V","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\u002Fchanges\u002F3-requests\u002F. 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.","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmarkdown-studio-exploratory-qa-claude\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7ENBQ2CSCFFMGK8YN14WCJD","change-requests-factory","A 4 layers software factory able to chains and parallelize Change Requests implementation","https:\u002F\u002Fgithub.com\u002Fgsemet\u002Fmarkdown-okf-schema-studio\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fchange-requests-factory\u002FSKILL.md",[],[]]