getcargohq__cargo-skills/cargo-context/references/conventions.md

Context repo conventions

The conventions below are inherited from the canonical context repository getcargohq/cargo-workspaces. When in doubt, read its README.md and the _template.md file in the relevant domain.

Domains

Domain	Purpose
global/	Company-level context: mission, voice, positioning, narrative, pricing
icp/	Ideal Customer Profile segments
persona/	Buyer personas (roles inside an ICP)
jtbd/	Jobs-to-be-done framings
alternative/	Competitors, substitutes, status quo
client/	Customer profiles, case studies, reference accounts
insight/	Market insights and observations
medium/	Channel playbooks (email, LinkedIn, cold call, etc.)
objection/	Objections + responses + proof
play/	GTM plays (signal → audience → channel → sequence → outcome)
proof/	Atomic proof points (metrics, quotes, case data)
signal/	Buying signals and intent triggers

File conventions

• Filename: kebab-case.md (e.g. vp-sales-mid-market.md). Use ASCII letters, digits, and hyphens only.
• Frontmatter: YAML with title and description on every .md/.mdx file. This is a strong convention, not enforced — a write with missing, empty, or malformed frontmatter is still committed; it just indexes poorly. The graph reads title (fallback: filename) and summary (fallback: first paragraph), not description. See Source references and the knowledge graph.
• Cross-references: domain/slug form, no .md extension (e.g. persona/vp-sales-mid-market). To register as a graph edge, a reference must appear as a wikilink, a markdown link, or a frontmatter references: entry (see below) — a bare domain/slug or file path in plain prose is not parsed.
• Templates: each domain ships an _template.md. Read it (cargo-ai context runtime read --path <domain>/_template.md) before authoring a new entry. _template.* files are excluded from the graph — never reference them.
• Bidirectional links: keep cross-refs symmetric when it makes sense — a play that targets a persona should appear in the persona's Preferred channels or How we land sections when relevant.

Source references and the knowledge graph

The graph is built from every .md, .mdx, .yaml, and .yml file in the repo (any folder; only .git/ is excluded). Each file becomes a node. Edges are created only from these three forms — everything else is invisible to the graph:

1. Frontmatter references: list (preferred for source citations — keeps prose clean, and the edge carries a frontmatter origin):

   ---
   title: AgoraPulse expansion thesis
   description: Why the AgoraPulse account is ready for a multi-thread expansion play.
   references:
     - outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md
   ---
   

2. A Markdown link in the body — use when the citation needs surrounding prose. Write standard [label] immediately followed by (path) link syntax pointing at the source file, e.g. an "AgoraPulse session outcomes" anchor linking to outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes.md.

3. Wikilinks in the body (extension optional):

   [[outputs/sales-notes/2026-06-05-agorapulse-build-session-1-outcomes]]
   

Linking rules

• Never cite a source as a bare path in prose. A Source: line that just mentions outputs/sales-notes/foo.md as plain text is not parsed and creates no edge. Always use one of the three forms above.
• Prefer root-relative paths. Paths resolve root-relative first (from the repo root), then relative to the citing file's directory. Root-relative paths work regardless of where the citing document lives.
• Extensions are optional. The resolver auto-tries .md, .mdx, .yaml, .yml (in that preference order). Including the extension is fine too.
• The target must exist. A reference only resolves if the target file is actually in the repo — nonexistent targets become broken edges (dead links in the graph UI). Verify the path before citing it (cargo-ai context runtime browse --path <dir>).
• _template.* files are excluded from the graph — don't reference _template.md / .mdx / .yaml / .yml.
• YAML data files: title, summary, and references are read from top-level keys; YAML bodies produce no link edges.
• Node title/summary: titles come from frontmatter title: (fallback: filename); summaries from frontmatter summary: (fallback: the body's first paragraph, truncated to 280 chars). The graph does not read description — set a summary: if you want the node summary to differ from the first paragraph. Always set title so the node is discoverable.

Citing sources in insight / learning documents

When a document has a Source or Evidence section, cite the source files in frontmatter references: — this keeps the prose clean and gives the edges a frontmatter origin. Use inline markdown links when the citation needs surrounding prose.

How to read the context

Start at global/ for company context. Walk icp/ → persona/ → jtbd/ to understand the buyer. Use play/ for outbound motions and objection/ + proof/ for live conversations.

Domain templates

The most commonly authored domains. For domains not shown here (icp/, jtbd/, alternative/, client/, insight/, medium/, signal/), read the in-repo _template.md directly:

cargo-ai context runtime read --path icp/_template.md
cargo-ai context runtime read --path signal/_template.md
# ...

global/_template.md

---
title:
description:
---

## Summary

_One-line version._

## Detail

_Full version. Mission, voice, positioning, narrative, pricing — whatever this entry is._

## Source

_Where this comes from. Founder note, brand doc, board deck, prior conversation._

persona/_template.md

---
title:
description:
---

## Role

- Title:
- Seniority:
- Function:
- Reports to:

## KPIs

-

## Pains

-

## Motivations

-

## Day-to-day

_What this person actually does on a Tuesday._

## Preferred channels

_Cross-ref `medium/...`._

-

## Common objections

_Cross-ref `objection/...`._

-

## How we land

_The angle, the pitch, the moment they get it._

play/_template.md

---
title:
description:
---

## Hypothesis

_Why this play should work. The bet._

## Trigger

_Cross-ref `signal/...`._

-

## Audience

_Cross-ref `icp/...` or `persona/...`._

-

## Channel

_Cross-ref `medium/...`._

-

## Sequence

1.
2.
3.

## Proof

_Cross-ref `proof/...`._

-

## Success metric

_What we measure. Target._

## Owner

_Role accountable for running this._

## Variants

-

proof/_template.md

---
title:
description:
---

## Type

_metric | quote | case | benchmark | screenshot_

## Content

_The actual proof point. Number, quote, fact._

## Source

_Where it comes from. Customer, study, internal data._

## Client

_Optional. Cross-ref `client/...`._

## Context

_What claim this supports. Why we cite it._

## Use cases

_Where this shows up: objections, plays, posts, decks._

-

objection/_template.md

Objections pair a stated buyer concern with the response and the proof that backs it up:

---
title:
description:
---

## Objection

_The buyer's stated concern, in their own words._

## Response

_Our reframe. Short, calm, specific._

## Proof

_Cross-ref `proof/...`._

-

## Personas

_Cross-ref `persona/...` — who raises this most._

-

Authoring rules of thumb

• One concept per file. If you're tempted to add a second ## Persona or a second ## Play heading inside one file, you actually want two files.
• Title is a label, description is a hook. title shows up in lists; description is the one-line that explains why this entry exists.
• Cross-refs over duplication. If a fact already lives in proof/..., link to it from the play or objection rather than re-stating it.
• Atomic proof. Each proof/ entry is one fact / quote / metric. Bundled proof points break filtering in the knowledge graph.
• Repetition threshold for call-derived claims. A single sales call is anecdote, not evidence. Before promoting an objection / pain / missed-proof claim from call analysis into the context repo, require it to surface across multiple calls. Suggested defaults:
  • Call-rich workspaces (≥ 50 transcripts / quarter): 3 occurrences.
  • Medium volume: 2 occurrences.
  • New / call-poor workspaces (< 10 transcripts): 1 occurrence, and cite the source via frontmatter references: (or a markdown link) so the citation registers as a graph edge — see Source references and the knowledge graph. The threshold applies to claims, not to facts a call directly confirms (a named customer, a verbatim quote, a competitor explicitly mentioned). See examples/lifecycle.md for the full refresh loop.