RVTF Skills

Make "done" provable in agentic software delivery.

Think of engineering methodologies as algorithms, and RVTF as the data structure that carries delivery evidence.

Your methodology organizes the work. RVTF links requirements, acceptance items, implementation tasks, verification evidence, review findings, and delivery decisions so you can see what was done, what was verified, and what remains unresolved.

It also records why work is needed, what is deferred, and when the work can stop. These decisions help agents avoid unjustified design expansion, extra implementation, and unnecessary review cycles.

Start with the core Skill; add a companion adapter when using an existing methodology. Evaluated revisions and their freshness status are listed on the adapter status page; each adapter's contract defines its supported scope.

The analogy describes a division of responsibilities: host methods keep their native specs, plans, and lifecycle. RVTF adds trace links and explicit rules for evidence validity, finding disposition, and closure. Recording a claim does not verify it; missing evidence stays visible as a gap.

Requirements-to-Verification Traceability Framework (RVTF) is Skill-first: six Agent Skills help your agent maintain a trace (a linked delivery record) in conversation. A TypeScript CLI validates that record and provides an optional read-only dashboard for exploring it.

English | 中文

Quick start · Understand the trace · Choose an adapter · Read progress · Advanced installation

Quick Start

Start with one bounded change and have your agent maintain a trace within your existing workflow. Run the commands in your project directory. You will need Node.js/npm and network access.

1. Install the core Skill

npx skills add SoLoHiC/rvtf-skills --skill tracing-requirements-to-verification

Follow the prompts to choose your target agent, installation scope and method. RVTF uses the general-purpose skills CLI for distribution. Being able to install a Skill in an agent does not establish compatibility with every engineering methodology. For Superpowers, BMAD, or another existing method, see adapter selection.

2. Start in conversation

Replace the example requirement with your actual task:

Use tracing-requirements-to-verification with this project's existing workflow.

Requirement: add date-range filtering to the export feature.
First confirm scope and acceptance criteria, then create and maintain
docs/verification/date-range-export.yaml.
Link requirements, acceptance items, implementation tasks, evidence and gaps.
Record a Journey when verification requires a connected path.
Choose the trace depth by risk. Do not mark unexecuted checks as passing.
Link design and implementation tasks to existing requirements or constraints.
Classify new suggestions before deciding whether to include them in scope.
After review, state the remaining issues and completion criteria. Focus re-review
on the effects of the fixes and retain the host's required checks.
At each update, explain what was done, what was verified, what remains
unresolved, and where the record is saved.

This is a request to your agent, not a new CLI command. The agent should confirm requirements and assumptions before maintaining the trace at the selected depth. You do not need to hand-author a complete YAML document first.

3. Validate and view the record when needed

Install the CLI for deterministic checks or the dashboard. It requires Node.js 20.19.0 or newer:

npm install --global @rvtf/cli
rvtf --version
rvtf --help
# Run after the agent creates the file above
rvtf validate docs/verification/date-range-export.yaml
# Optional: open the same record in the read-only dashboard
rvtf view docs/verification/date-range-export.yaml

The CLI checks the trace's structure and the semantic rules it implements. These checks do not replace software tests or acceptance checks. The dashboard ships with the CLI. Keep the command running for live updates; stop it with Ctrl+C. Skills and CLI install separately. Skills help the agent maintain records; the CLI validates and displays them. Install both when a formal workflow requires the CLI gate.

Understand the Trace

Consider the date-range export example. Code can be written and unit tests can pass without anyone checking whether a user's downloaded file contains only records within the selected dates. RVTF keeps those different conclusions explicit.

Record	Question it answers	Example
Requirement	What is required, and where did it come from?	Export records within the selected dates
Acceptance Item	How is each criterion checked?	Correct date boundaries; clear output when no records match
Host task	What work implements those criteria?	Update the query, UI and tests
Journey, when applicable	Does the connected path reach its outcome?	Select dates → export → inspect the download
Evidence Claim	Which target does an artifact support, and is that evidence still valid?	Boundary tests support date criteria; an end-to-end download check supports the path
Findings, gaps and decisions	What remains unresolved, and how is it handled?	Keep the unverified download path visible with an owner

Each acceptance criterion has one authoritative record. Tasks and Journeys reference it instead of copying its status. An isolated change without a connected-path requirement may omit a Journey with an explicit rationale.

These links support four everyday decisions:

• Why is this design or implementation needed? Link it to an existing requirement, constraint, or accepted scope change. Record and assess optional improvements before making them tasks. Keep design effort and trace detail proportional to risk.
• What supports the completion claim? implemented means built; verified requires evidence for the target. Passing tests support only what they cover; passing individual criteria does not replace path verification.
• What must this review still establish? After fixes, focus re-review on known findings, changed evidence, and direct regression risks. Expanding the review requires an explicit basis. Merely recording an accepted terminal verdict should not trigger another review.
• Does earlier evidence still apply? Assess changes to the implementation, verifier and environment before reusing evidence. Avoid repeating unchanged checks without a reason to expect new evidence, and retain the host's mandatory fresh checks and independent review.

At completion, the agent assesses requirements, acceptance items, applicable Journeys, review dispositions and host gates together. Required gaps and external blockers remain explicit even when every implementation task is checked off.

When is it useful?

Use it for multi-step features, handoffs, repeated review, or uncertainty about whether passing tests cover the acceptance criteria. Keep simple changes lightweight; exploration can record candidate requirements and unknowns without claiming completion.

Two other useful signals:

• A small change keeps growing into abstractions, a general-purpose framework, or extra features with no clear requirement behind them.
• Each fix triggers a fresh review from a different angle, and decisions already made are repeatedly revisited without a new basis.

Detailed fields, aggregation rules, evidence reuse, verification tiers and controlled reopening live in the core Skill, schema reference, gate reference, and review-governance reference.

Usage Modes

RVTF can be light or strict depending on risk:

Mode	Use when
discovery	Exploring or prototyping without a completion claim.
lite	Small bounded changes with low risk.
standard	Multi-step delivery, phase work, review, or handoff. Requires an explicit decision on whether Journeys and formal review apply.
strict	Security, privacy, migrations, compatibility, money, production risk, or cross-agent execution. Requires bounded review governance and independent review evidence for the affected risk scope.

Do not lower the mode to justify an unsupported completion claim. If review reveals a high-risk issue, apply stricter handling to at least that issue.

Included Skills

The core Skill supplies shared trace structures and rules. Five adapters connect them to existing host workflows. Usually, install the core plus the adapter for the method you actually use.

Your workflow	Skill	Native artifacts and stages connected
RVTF directly	Core Skill	Requirements, acceptance, evidence, gaps and delivery decisions
Superpowers	Superpowers adapter	Plans, task reviews, verification and branch finishing
Agent Skills	Agent Skills adapter	Planning, incremental build, review and ship readiness
GSD Core	GSD adapter	Goals, phases, execution waves and verification records
BMAD Method	BMAD adapter	Specs, Stories, build, review and retrospectives
OpenSpec	OpenSpec adapter	Changes, specs, tasks and archive

Use with your host

Install the core first, then the chosen adapter. For example, add the Superpowers adapter, selecting the same agent and installation scope as the core:

npx skills add SoLoHiC/rvtf-skills --skill adapting-rvtf-to-superpowers

In your existing task conversation, ask: "Use adapting-rvtf-to-superpowers to maintain an RVTF trace of this change's requirements and evidence, following the existing Superpowers workflow." Use the corresponding Skill name for other methods; list names with npx skills add SoLoHiC/rvtf-skills --list. Adapters do not install their host method or take over its execution, review or lifecycle.

For OpenSpec, the trace belongs at openspec/changes/<change-name>/rvtf.yaml, rather than the generic quick-start path. Formal completion checks require both OpenSpec strict validation and rvtf validate; the adapter's Host Contract Snapshot defines its supported scope.

Check compatibility

Use the compatibility record to find evaluated host revisions and freshness; each adapter's Host Contract Snapshot defines scope. adapters.json is the machine-readable inventory. current is relative to the tracked ref: an unchanged tag does not establish support for the latest release.

In the RVTF repository, run npm run validate:adapters for record consistency and npm run audit:adapters for upstream drift. See the compatibility guide for status and re-audit rules.

Read Progress in Context

The local dashboard lets you explore one trace during an ongoing engineering conversation. Using the records already written by the workflow, it helps you answer "How far have we got?", "What evidence supports this status?", and "What remains unresolved?"

Actual rvtf view screenshot: the RVTF TypeScript CLI iteration trace, shown in fullscreen with compact density. The historical sample contains 8 Requirements, 24 Acceptance Items, and 2 Journeys; the image shows one selected Journey, not the current overall project status.

• Requirements and paths: explore the story map and Journey Steps, or read Requirements and Acceptance Items directly when no Journey is recorded.
• Evidence and decisions: drill into current evidence references, historical claims, review findings, gaps, and delivery scopes. Read recorded owners and decisions rather than treating every blocker as a task for the current user.
• Reading continuity: search and filter Items, keep details in a side panel, collapse navigation, or expand the map to fullscreen. Three themes and a compact density option support different reading preferences.
• Bilingual interface: switch fixed labels and controls between English and Chinese. The dashboard initially follows the browser language and remembers your choice for the same local address; trace content, raw status values, paths, commands, and diagnostic text remain in their source language.
• Live source updates: the page refreshes when the selected source changes and retains your selection when it can identify the same record. Read errors remain visible alongside the last readable snapshot; removed or ambiguous selections are marked invalid instead of silently switching to another record.

In normal work, ask the agent about progress and continue in conversation. When visual inspection would help, ask it to open the current trace; if the context is complex, it may suggest the dashboard once and wait for your agreement. The agent can run rvtf view, reuse an active page, and help explain what it shows. Copy a record from the detail panel back to the conversation to discuss the next decision; the host workflow, not the page, updates the trace.

The dashboard shows recorded state, not live agent execution telemetry. It does not edit files, approve decisions, execute evidence commands, or coordinate multiple projects. If visualization is unavailable or unwanted, continue in conversation with the same trace and workflow gates.

What RVTF Is Not

RVTF does not prove that original requirements are correct. It also does not replace product judgment, security review, domain expertise, automated testing, or code review. Bounded review governance keeps legitimate required gaps visible, even when found late. Each late finding must link to the affected requirements or evidence and record the decision about its effect on delivery.

RVTF does not automatically judge whether an architecture is too complex or guarantee less work on every task. It requires a basis for extra work and a reason for repeated verification. Necessary defects and mandatory host gates still need to be addressed.

The dashboard is not a project-management system or a replacement for the agent's host environment. It explains the existing trace; it does not create new work or infer missing completion evidence from the way records are displayed.

Install

For first use, follow the quick start. This section covers full-pack, global and exact-version installation.

Install Skills

List available skills:

npx skills add SoLoHiC/rvtf-skills --list

Install all RVTF Skills and select the target agent interactively:

npx skills add SoLoHiC/rvtf-skills --skill '*'

The OpenSpec adapter requires the core Skill. Select both in one installation:

npx skills add SoLoHiC/rvtf-skills \
  --skill tracing-requirements-to-verification \
  --skill adapting-rvtf-to-openspec

Follow the prompts to choose scope, or add -g to explicitly install globally. For scripted installation, specify --agent <agent-name> and add -y to skip confirmation. Examples include --agent claude-code, --agent cursor and --agent codex; see the supported agents for the full list. Use --copy to require copies; otherwise choose the installation method interactively.

Use the SSH source if your environment requires SSH authentication:

npx skills add git@github.com:SoLoHiC/rvtf-skills.git --skill '*' -g

Exact-version installation and checksums

For an exact released Skills version, download and verify the Skills archive, then install from the extracted package:

release_version=0.8.1
skills_install_dir="$(mktemp -d)"
gh release download "v${release_version}" \
  --repo SoLoHiC/rvtf-skills \
  --dir "${skills_install_dir}" \
  --pattern "rvtf-skills-${release_version}.tgz" \
  --pattern SHA256SUMS
(
  cd "${skills_install_dir}"
  awk -v file="rvtf-skills-${release_version}.tgz" '$2 == file { print }' SHA256SUMS |
    shasum -a 256 -c -
)
mkdir "${skills_install_dir}/package"
tar -xzf "${skills_install_dir}/rvtf-skills-${release_version}.tgz" \
  -C "${skills_install_dir}/package"
npx skills add "${skills_install_dir}/package/package" --skill '*' -g

These npx skills add commands and scripts/install.sh install Skills only. They do not install CLI runtime dependencies or create an rvtf executable.

Install the CLI

CLI versions, verified downloads and signatures

The CLI requires Node.js 20.19.0 or newer. Install the exact public package from the official npm registry:

release_version=0.8.1
npm install --global "@rvtf/cli@${release_version}" --registry=https://registry.npmjs.org/

Alternatively, download and verify the exact GitHub Release asset before installing it:

release_version=0.8.1
cli_install_dir="$(mktemp -d)"
gh release download "v${release_version}" \
  --repo SoLoHiC/rvtf-skills \
  --dir "${cli_install_dir}" \
  --pattern "rvtf-cli-${release_version}.tgz" \
  --pattern SHA256SUMS
(
  cd "${cli_install_dir}"
  awk -v file="rvtf-cli-${release_version}.tgz" '$2 == file { print }' SHA256SUMS |
    shasum -a 256 -c -
)
npm install --global --ignore-scripts \
  "${cli_install_dir}/rvtf-cli-${release_version}.tgz"

Both commands install the CLI only and do not install any agent Skill. See the TypeScript CLI guide for registry provenance and signature verification, local development, and Python rollback instructions.

CLI Contract

rvtf --version
rvtf --help
rvtf validate --help
rvtf validate path/to/rvtf.yaml
rvtf validate path/to/rvtf.yaml --format json
rvtf validate --format json path/to/rvtf.yaml

Use validate for deterministic checks of a YAML trace. Use view to read a YAML trace or a selected top-level YAML/YML fenced block in Markdown:

rvtf view --help
rvtf view path/to/rvtf.yaml
rvtf view path/to/trace.md --block 2 --no-open

view opens the local dashboard on 127.0.0.1 with an available port. Use --port PORT to select the port or --no-open to print the URL without opening a browser. A single Markdown YAML block is selected automatically; multiple blocks require an explicit one-based --block. Keep the process running for live updates and stop it with Ctrl+C. A source/data error is shown without ending the service; normal shutdown exits 0; usage or startup failure exits 2. See the local-view guide.

Verify the installed registry package signatures and provenance in a clean project when supply-chain verification is required:

release_version=0.8.1
signature_dir="$(mktemp -d)"
npm install --prefix "${signature_dir}" --ignore-scripts \
  "@rvtf/cli@${release_version}" --registry=https://registry.npmjs.org/
npm audit signatures --prefix "${signature_dir}" --registry=https://registry.npmjs.org/

For validate, both -h and --help are supported. Text is the default format, and --format may appear before or after the trace path. A valid document exits 0; a loaded document with semantic diagnostics exits 1; usage, file-access, YAML-load, and runtime errors exit 2. Text validation results use stdout; handled operational errors use stderr. JSON mode emits exactly one JSON document on stdout for loaded-document results and handled operational errors; argument-parser usage errors remain on stderr.

Repository Layout

skills/
  tracing-requirements-to-verification/
  adapting-rvtf-to-superpowers/
  adapting-rvtf-to-agent-skills/
  adapting-rvtf-to-gsd/
  adapting-rvtf-to-bmad/
  adapting-rvtf-to-openspec/
packages/
  cli/                         # TypeScript validation and local-view CLI
  viewer/                      # dashboard source, bundled into the CLI
src/
  rvtf_cli/                    # Python rollback implementation
docs/
  adapter-governance.md
  cli-typescript.md
  releasing.md
scripts/
  validate.sh
  validate-schema-examples.py
  fixtures/schema/
    positive/
    negative/
  install.sh
  package.sh
  package-typescript-cli.sh
  publish-node-package.sh
  smoke-openspec-v1.sh
package.json

Release Automation

Release preparation, candidate verification, and formal publication are separate decisions. The formal workflow publishes checksummed Skills and CLI archives, verifies the npm package and provenance, and promotes the GitHub Release only after the required gates pass. Maintainer commands, credentials, recovery rules, and invariants are documented in the release guide.

Development

Install the pinned CI dependencies before running the Python-backed validation commands:

python3 -m pip install --requirement requirements-ci.txt

Validate all six Skills plus the deterministic positive/negative schema and invariant fixtures:

scripts/validate.sh

Run only the schema/invariant fixture validator when working on the additive artifact contracts:

python3 scripts/validate-schema-examples.py

If the default Python does not have PyYAML, pass a Python from a prepared environment:

PYTHON_BIN=/tmp/rvtf-skill-validate-venv/bin/python scripts/validate.sh

Install Skills from a local checkout:

npx skills add . --skill '*'

Build and audit all repository packages under dist/:

scripts/package.sh
scripts/package-typescript-cli.sh
(cd dist && shasum -a 256 -c SHA256SUMS)

The TypeScript implementation is the current CLI. See the TypeScript CLI guide.

License

RVTF Skills is available under the MIT License. Compatibility references, pinned upstream revisions, third-party license notices, and the BMAD trademark boundary are documented in THIRD_PARTY_NOTICES.md.