tieline

Give every agent durable product intent, grounded in the code that delivers it.

How it works · Core concepts · Quickstart · Code graph · Agent queries · Docs

Tieline generates Capabilities, User Stories, and Acceptance Criteria, linking them to the exact code and tests as evidence. By creating a semantic business intent layer grounded in your production code, Tieline ensures nothing gets lost in translation between you and your agent.

• Reviewed intent: Stories and ACs evolve beside the implementation and are accepted through normal pull-request review.
• Graded evidence: a fresh grader assesses changed ACs against bounded source evidence and a closed citation list, returning supported, partial, or unsupported.
• A derived code topology: tieline code compile records parsed symbols and static dependencies for the exact source snapshot, letting agents trace code and connect possible impact back to accepted ACs.
• Follow features from idea to production In addition to production state, track 'Observations' such as feature requests, ideas and bug reports, allowing you to track features through their lifecycle to production.

The contract creates a manifest in your repository. When synced to optional Postgres, any connected agent—including product, research, and support agents without codebase access can query the accepted state of main, and review + update 'Observations'.

How it works

• An agent proposes intent. The Tieline skill reads product context and code, then drafts or updates Stories, ACs, and evidence links for review.
• Parsers ground code links. Tree-sitter extracts canonical symbols, source ranges, and bounded snippets. Conservative resolvers preserve ambiguous and unresolved relationships as diagnostics.
• A fresh agent grades the evidence. The grader receives one AC, its current evidence, and a closed citation list. Deterministic verification rejects stale or invented citations.
• Review establishes acceptance. The YAML, compiled manifest, and code change travel together. Merge accepts that version of the relationship.
• Checks make drift visible. The skill updates intent as behavior changes, while tieline check flags changed evidence, broken links, invalid contracts, and stale artifacts.

Optional Postgres storage adds Observations such as feature requests, ideas, and bugs, giving agents context on both accepted behavior and future direction.

How evidence, authority, and freshness work →

Quickstart

cd /path/to/your-repository
npx -y tieline@latest init

Restart your agent, then run the /tieline skill to begin onboarding. The skill proposes the initial contract and code links for review; the generated .tieline/review.html provides a browser-friendly view.

Postgres is optional. Use it to allow all your agents to query the current state of your product, and to record 'Observations' like feature requests alongside the products current state. The postgres DB gets updated with each merge. See Setup's post-merge sync for configuration.

Core concepts

Capability → User Story → Acceptance Criteria → Scenarios

Acceptance Criteria are the primary anchors for code, test, and Observation links. Story-level links remain available when the evidence applies to the broader user outcome.

Term	Meaning
Capability	A stable product or business area that groups related User Stories
User Story	Desired behavior expressed through actor, goal, and benefit
Acceptance Criteria	Observable outcomes that define when a User Story is satisfied
Scenario	An optional Given/When/Then example that clarifies Acceptance Criteria
Observation	Append-only source evidence such as a request, bug, or question
Backlog Item	Optional work that consolidates Observations before or alongside a User Story
Artifact	Code or test evidence linked to a User Story or Acceptance Criteria

What agents can ask

Ask	Tool
“What is this symbol supposed to do?”	get_asset_intent_context
“What implements RETRIEVAL-001-AC1?”	get_acceptance_criterion_context
“Which criteria touch these paths?”	get_path_criteria
“Which code may depend on this symbol?”	trace_code_dependencies
“Which accepted behaviors may this branch affect?”	analyze_code_blast_radius

Exact manifest and topology reads work from the repository. Database-backed reads expose the synced accepted contract to agents without repository access. Planning tools can also capture Observations and shape backlog Stories.

Full MCP reference →

How the code graph works

tieline code compile uses Tree-sitter parsers to build a derived snapshot of the repository's source structure. By default it is kept out of Git in .tieline/topology/cache/, keyed by the exact source and resolver inputs it describes, so concurrent pull requests never conflict on generated topology. Later reads select the graph for the snapshot they inspect without starting a parser or writing to Postgres. Set "topology_mode": "committed" to commit one reviewed .tieline/topology/graph.json instead.

Layer	Role
Stored file hashes	Identify the exact source bytes represented by the snapshot
Stored locator-bearing symbols	Identify code assets for traversal and authored joins
Stored resolved adjacency edges	Trace static dependencies and dependents
Stored unresolved dependency frontiers	Keep ambiguous imports and unsupported boundaries visible
Query-time AC join (not stored)	Match visited paths and selectors to authored AC links

Source ranges, source snippets, raw reference and resolution facts, and parser diagnostics are not duplicated in the graph.

source code → Tree-sitter → topology graph → symbols and static dependents
                                      + authored AC links
                                      ↓
                              AC-aware blast radius

Explicit blast-radius analysis starts from the supplied locators. A Git-base comparison instead seeds every symbol in changed files plus the endpoints of changed edges. Both traverse static edges in the selected direction—dependents by default, or dependencies when requested—then perform the authored locator-to-AC join. Cycles, external dependencies, ambiguity, and traversal limits remain visible. The result is a bounded impact signal, not a runtime call graph or a guarantee of breakage.

Topology and blast-radius commands →

What the contract looks like

version: 1
capability:
  key: CONTRACT
  name: Living product contract
  description: Accepted product behavior is reviewable beside the implementation.
  stories:
    - key: CONTRACT-003
      title: Inspect accepted intent before changing an asset
      actor: implementing agent
      goal: retrieve reviewed context for a known code locator
      benefit: implementation begins from accepted intent
      lifecycle: production
      acceptance_criteria:
        - key: CONTRACT-003-AC4
          criterion: Tieline must expose exact manifest-backed context without a database.
          scenarios:
            - given: the compiled manifest is available
              when: an agent requests context for a known code locator
              then: Tieline returns its accepted intent and linked evidence
          links:
            - relation: implements
              provenance: authored
              target:
                kind: code
                repository: tieline
                path: src/tools/intent-context.ts
                selector: function:registerIntentContextTools
            - relation: tests
              provenance: authored
              target:
                kind: test
                repository: tieline
                path: tests/unit/contract/test-intent-context.ts

An AC is complete on its own. Given/When/Then Scenarios are optional examples for important conditions or edge cases.

How the contract stays current

During implementation, the Tieline skill proposes new Stories and ACs when behavior was added, updates existing definitions when behavior changed, reconciles evidence links, grades changed claims, and refreshes generated artifacts for review.

Run the deterministic check in CI:

npx -y tieline@latest check --base <base-ref> .

Invalid YAML, broken links, and stale generated artifacts fail. Changed linked evidence identifies the affected ACs for agent or human review. After merge, an idempotent sync publishes accepted main to Postgres.

GitHub Actions example · CLI reference

Where to learn more

Guide	Contents
Setup	Initialization, database modes, sync, and agent registration
Concepts	Contract structure, evidence, authority, and freshness
CLI	Contract, topology, check, sync, grading, and review commands
MCP	Local and database-backed tools for agents
Architecture	Production boundaries and dependency direction
Testing	Test layout, canonical checks, and disposable database guard
Operations	Serving, credentials, durability, and privacy