OSTF. View on GitHub

Open Software Traceability Format

A traceability format for agentic software engineering.

OSTF connects requirement IDs to code and tests, with optional labeled log and OpenTelemetry references. Tools can check link freshness against a source tree.

Read the draft See the scenario
TRACE VIEW OSTF 0.2
OSTF ITEM KEY R-PAY-RETRY No duplicate charge on retry. Assigned ID, not a function hash or Git commit.
Open trace.yaml

01 / THE MODEL

A payment retry,
traced through code and tests.

A customer retries a charge after a timeout. An agent updates the payment method and adds a regression test. OSTF links both to the requirement: the same payment idempotency key must not create a second charge.

ILLUSTRATIVE PAYMENT RETRY SCENARIO OSTF DEFAULT PROFILE
GO METHODpay/charge.go#Service.Chargeimplements R-PAY-RETRY
RUNNER TESTpay/retry_test.go#TestSameKeyverifies R-PAY-RETRY
REQUIREMENT R-PAY-RETRY No duplicate charge on retry.
The OSTF node is the requirement. A code anchor names a method or whole file, which may contain one changed line or many. The YAML fields declare links from the requirement.

Prefer links beside code? When tag reading is enabled, a Go comment such as // @req R-PAY-RETRY can declare a link to the following definition. Read the tag rules.

Four-stage walkthrough: Claude Code receives a payment retry task, changes a Go method and test, links them to R-PAY-RETRY, then a recheck writes two valid trace.lock stamps.
The animation follows the runnable payment retry example. The stamp records link freshness after a recheck; it does not grant the agent permission.
See a real trace.lock entry 
trace.lock 1
pay/charge.go#Service.Charge implements R-PAY-RETRY source.sig=go1:GG87juikRDlVftpE_jZHF2al2weX0dAt3ZmIU_ZidfE source.body=go1:MfpzrEnIbxC9-F2ceyJo8KmJK3bn9Dz7epTGGLfzL74 target=f1:-fGQUood7K-GLzAggMrvAssxMIAPcM3ycdApkoOLpMM

source.sig and source.body fingerprint the Go method; target fingerprints the requirement. These are change checks, not a Git commit. The complete file also stamps the verifying test.

01

Record the intent

R-PAY-RETRY states the behavior. The agent or team links it to Service.Charge and the regression test.

02

Recheck the links

After reviewing the relationships, a tool stamps their endpoint fingerprints in trace.lock.

03

Notice drift

If a later agent changes Service.Charge's signature, an Analyzer reports its stamped link as suspect so the relationship can be rechecked.

A LATER CHANGE

The method is unchanged.
The behavior is not.

Imagine a later pull request changes NewService so it no longer initializes the receipts map. The linked method and test stay untouched. Their OSTF stamps can still be valid even though a charge now fails.

CHANGEDNewService

Receipts map is no longer initialized.

UNCHANGEDService.Charge

The linked method still uses that map.

TRACEABLER-PAY-RETRY

Its regression test is TestSameKey.

OSTF TODAY

The existing links identify the requirement and test to revisit. A valid stamp only describes the fingerprinted endpoints.

COMPANION TOOLS

Dependency analysis or CI discovers the indirect impact. CI records results; people decide whether the change can merge.

Read the format boundary Follow a complete proposed workflow

A CLEAR BOUNDARY

Fresh does not mean approved.

A valid stamp means a link meets the draft's freshness rules relative to a recorded recheck. It does not establish approval, correctness, test execution, compliance or release authorization.

Read the exact rules

02 / THE DRAFT

Read and evaluate the draft.

The specification is maintained in the public OSTF repository. These links go to its current draft source, so the site does not maintain a second copy of the rules.

01 / START HERE

Runnable scenario

A Go payment retry service with the requirement, linked test and valid lock stamps shown above.

 02 / ORIENTATION

Scope and boundaries

What belongs in Core, what remains a proposal and what tools decide for themselves.

 03 / NORMATIVE DRAFT

Core contract

Versioned rules for files, items, links, fingerprints and conformance claims.

 04 / IMPLEMENTERS

Conformance suite

Fixtures, a prototype reader and the limits of current conformance coverage.

Current normative language and runner coverage: Go. See the support map for implemented and proposed behavior.

Draft status: document revision 0.11, file format 0.2, conformance suite 0.2.0. OSTF 1.0 and independent-party conformance are not yet claimed.

03 / PARTICIPATE

Help make the format
work across tools.

Build an OSTF reader or writer for your coding agent or engineering tools. Try the fixtures, compare results and tell us where the draft is ambiguous. Proposals and decisions are public in the OSTF repository.

Contribution guide Report an ambiguity Draft governance