![\"Tieline\"](\"assets/tieline-logo.png\"){kind=logo}
\n\n \n
\n Give every agent durable product intent, grounded in the code that delivers it.\n
\n\n\n How it works ·\n Core concepts ·\n Quickstart ·\n Code graph ·\n Agent queries ·\n Docs\n
\n\n---\n\nTieline generates Capabilities, User Stories, and Acceptance Criteria, linking them to\nthe 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. \n\n- **Reviewed intent:** Stories and ACs evolve beside the implementation and are accepted through\n normal pull-request review.\n- **Graded evidence:** a fresh grader assesses changed ACs against bounded source evidence and a\n closed citation list, returning `supported`, `partial`, or `unsupported`.\n- **A committed code topology:** `.tieline/topology/graph.json` records parsed symbols and static\n dependencies, letting agents trace code and connect possible impact back to accepted ACs.\n- **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. \n\nThe contract creates a manifest in your repository. When synced to optional Postgres, any connected\nagent—including product, research, and support agents without codebase access can query the accepted\nstate of `main`, and review + update 'Observations'. \n\n---\n## Quickstart\n\n```bash\ncd /path/to/your-repository\nnpx -y tieline@latest init\n```\n\nRestart your agent, then run the /tieline skill to begin onboarding. The skill proposes the initial contract and code links for review; the generated\n`.tieline/review.html` provides a browser-friendly view.\n\nPostgres 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](docs/setup.md#post-merge-contract-sync) for configuration.\n\n## How it works\n\n1. **An agent proposes intent.** The Tieline skill reads product context and code, then drafts or\n updates Stories, ACs, and evidence links for review.\n2. **Parsers ground code links.** Tree-sitter extracts canonical symbols, source ranges, and bounded\n snippets. Conservative resolvers preserve ambiguous and unresolved relationships as diagnostics.\n3. **A fresh agent grades the evidence.** The grader receives one AC, its current evidence, and a\n closed citation list. Deterministic verification rejects stale or invented citations.\n4. **Review establishes acceptance.** The YAML, compiled manifest, topology, and code change travel\n together. Merge accepts that version of the relationship.\n5. **Checks make drift visible.** The skill updates intent as behavior changes, while `tieline check`\n flags changed evidence, broken links, invalid contracts, and stale artifacts.\n\nOptional Postgres storage adds Observations such as feature requests, ideas, and bugs, giving agents\ncontext on both accepted behavior and future direction.\n\n[How evidence, authority, and freshness work →](docs/concepts.md)\n\n## Core concepts\n\n```text\nCapability → User Story → Acceptance Criteria → Scenarios\n```\n\nAcceptance Criteria are the primary anchors for code, test, and Observation links. Story-level\nlinks remain available when the evidence applies to the broader user outcome.\n\n| Term | Meaning |\n| --- | --- |\n| Capability | A stable product or business area that groups related User Stories |\n| User Story | Desired behavior expressed through actor, goal, and benefit |\n| Acceptance Criteria | Observable outcomes that define when a User Story is satisfied |\n| Scenario | An optional Given/When/Then example that clarifies Acceptance Criteria |\n| Observation | Append-only source evidence such as a request, bug, or question |\n| Backlog Item | Optional work that consolidates Observations before or alongside a User Story |\n| Artifact | Code or test evidence linked to a User Story or Acceptance Criteria |\n\n## What agents can ask\n\n| Ask | Tool |\n| --- | --- |\n| “What is this symbol supposed to do?” | `get_asset_intent_context` |\n| “What implements `RETRIEVAL-001-AC1`?” | `get_acceptance_criterion_context` |\n| “Which criteria touch these paths?” | `get_path_criteria` |\n| “Which code may depend on this symbol?” | `trace_code_dependencies` |\n| “Which accepted behaviors may this branch affect?” | `analyze_code_blast_radius` |\n\nExact manifest and topology reads work from the repository. Database-backed reads expose the\nsynced accepted contract to agents without repository access. Planning tools can also capture\nObservations and shape backlog Stories.\n\n[Full MCP reference →](docs/mcp.md)\n\n## How the code graph works\n\n`.tieline/topology/graph.json` is a committed, derived snapshot of the repository's source\nstructure. `tieline code compile` uses Tree-sitter parsers to build it; later reads query the\nsnapshot without starting a parser or writing to Postgres.\n\n| Layer | Role |\n| --- | --- |\n| Stored file hashes | Identify the exact source bytes represented by the snapshot |\n| Stored locator-bearing symbols | Identify code assets for traversal and authored joins |\n| Stored resolved adjacency edges | Trace static dependencies and dependents |\n| Stored unresolved dependency frontiers | Keep ambiguous imports and unsupported boundaries visible |\n| Query-time AC join (not stored) | Match visited paths and selectors to authored AC links |\n\nSource ranges, source snippets, raw reference and resolution facts, and parser diagnostics are not\nduplicated in `graph.json`.\n\n```text\nsource code → Tree-sitter → graph.json → symbols and static dependents\n + authored AC links\n ↓\n AC-aware blast radius\n```\n\nExplicit blast-radius analysis starts from the supplied locators. A Git-base comparison instead\nseeds every symbol in changed files plus the endpoints of changed edges. Both traverse static\nedges in the selected direction—dependents by default, or dependencies when requested—then\nperform the authored locator-to-AC join. Cycles, external dependencies,\nambiguity, and traversal limits remain visible. The result is a bounded impact signal, not a\nruntime call graph or a guarantee of breakage.\n\n[Topology and blast-radius commands →](docs/cli.md#derived-code-topology-and-blast-radius)\n\n## What the contract looks like\n\n```yaml\nversion: 1\ncapability:\n key: CONTRACT\n name: Living product contract\n description: Accepted product behavior is reviewable beside the implementation.\n stories:\n - key: CONTRACT-003\n title: Inspect accepted intent before changing an asset\n actor: implementing agent\n goal: retrieve reviewed context for a known code locator\n benefit: implementation begins from accepted intent\n lifecycle: production\n acceptance_criteria:\n - key: CONTRACT-003-AC4\n criterion: Tieline must expose exact manifest-backed context without a database.\n scenarios:\n - given: the compiled manifest is available\n when: an agent requests context for a known code locator\n then: Tieline returns its accepted intent and linked evidence\n links:\n - relation: implements\n provenance: authored\n target:\n kind: code\n repository: tieline\n path: src/tools/intent-context.ts\n selector: function:registerIntentContextTools\n - relation: tests\n provenance: authored\n target:\n kind: test\n repository: tieline\n path: scripts/test-intent-context.ts\n```\n\nAn AC is complete on its own. Given/When/Then Scenarios are optional examples for important\nconditions or edge cases.\n\n## How the contract stays current\n\nDuring implementation, the Tieline skill proposes new Stories and ACs when behavior was added,\nupdates existing definitions when behavior changed, reconciles evidence links, grades changed\nclaims, and refreshes generated artifacts for review.\n\nRun the deterministic check in CI:\n\n```bash\nnpx -y tieline@latest check --base