Capability · 15 min
Reuse a reference implementation safely
Save a proven example, select it by ID, share it with your team, and adapt it across many targets without copying away local behavior.Last updated August 2026Copy a starter prompt ↓
Start with a proven example, not a vague instruction
A Brief reference points an agent to an implementation that already works. It records the source, when to use it, where it applies, and what must not be copied blindly. For a broad rollout, Brief turns that evidence into shared invariants and target-specific variation points instead of asking the agent to duplicate files.
Ask your coding agent
Use Brief to study <path, component, page, or URL> as a possible reference for <job>. Confirm that it is implemented and verified, identify the behavior and design decisions worth reusing, and name the context-specific details another target must supply. Do not edit yet and do not treat visual similarity alone as proof.
- Search: preserve keyboard behavior, result states, loading, accessibility, and analytics; bind each product's fields, permissions, and result actions.
- Presence: preserve status semantics, accessibility, and freshness behavior; bind each surface's size, label, privacy rule, and realtime source.
- Table controls: preserve the shared search, filter, and header pattern; bind each table's columns, filters, actions, permissions, empty state, and mobile priority.
- Look and feel: preserve approved tokens, primitives, interaction states, and responsive rules; bind each page's content hierarchy and product-specific components.
Save the reference locally first
Ask your coding agent
Save src/features/customers/CustomersTable.tsx and its focused tests as a local Brief reference named "Product table controls". It applies when a product table needs search, filters, or header actions. Record that agents must preserve table-specific columns, permissions, actions, and empty states. Show me the saved reference ID.
CLI example
brief save-reference --repo "$PWD" --title "Product table controls" --summary "Shared search, filter, and header behavior for product tables." --files src/features/customers/CustomersTable.tsx,src/features/customers/CustomersTable.test.tsx --applies-to "src/features/**/Table.tsx" --use-when "A product table needs search, filters, or header actions." --do-not-copy "Preserve target-specific columns, permissions, actions, and empty states."
Select the exact reference before editing
Use the reference ID when more than one example could match. Exact selection prevents an agent from silently choosing a convenient but weaker pattern.
List local and team references
brief references --repo "$PWD" --query table
Inspect one local reference
brief references --repo "$PWD" --local --reference-id ref_123
Inspect one approved team reference
brief references --repo "$PWD" --team --reference-id ref_123
Ask your coding agent
Use Brief's reference_implementations tool to load reference ref_123 from the team scope. Before editing, cite its sources and explain what you will reuse, adapt, rule out, and avoid copying.
Adapt one target to the shared core
Ask your coding agent
Use approved reference ref_123 to add the same search behavior to the Orders product. Compile the reference contract first. Preserve its shared interaction, accessibility, loading, empty, error, and result-selection behavior. Bind the Orders searchable fields, permissions, analytics, copy, and result actions from the Orders implementation. Show the contract and local adaptations before editing, then verify the changed behavior against both.
Roll the pattern out across many targets
Ask your coding agent
Use approved reference ref_123 to converge the search, filter, and header pattern across every product table. Inventory the full target set, group targets by archetype, name the shared foundations, and bind each table's columns, filters, actions, permissions, empty state, and responsive priority. Work foundation-first in bounded waves. Do not claim completion if the inventory is partial or any target lacks fresh proof.
Compile the contract
brief reference-contract compile --repo "$PWD" --reference-id ref_123 --task "Converge product table controls without erasing table-specific behavior" --kind compound_pattern --invariants-file ./invariants.json --variation-points-file ./variation-points.json --scenarios-file ./scenarios.json --verification-file ./verification.json --output .brief/table-contract.json
Plan a bounded rollout
brief reference-rollout plan --repo "$PWD" --contract-file .brief/table-contract.json --targets src/tables/CustomersTable.tsx,src/tables/OrdersTable.tsx --target-contexts-file ./target-contexts.json --foundation-files src/ui/TableShell.tsx,src/ui/tokens.css --output .brief/table-rollout.json
The MCP reference_contract and reference_rollout tools provide the same workflow without intermediate CLI files. Pass the exact compiled contract into the rollout; do not reconstruct it from a prose summary.
Compile a compound reference pack
A compound profile lets Brief recognize the parts that make a system trustworthy, not just its most visible file. A design-system pack needs Theme Lab, token, shared-component, and design-verification evidence. An adapter-contract pack needs manifest, canonical adapter, fixtures, contract-runner, and security-verification evidence. Missing roles keep the contract non-ready.
Discover a Theme Lab profile
brief reference-contract compile --repo "$PWD" --reference-id ref_theme --task "Converge the product design system" --profile design_system --status approved --output .brief/design-contract.json
Discover an adapter contract
brief reference-contract compile --repo "$PWD" --reference-id ref_adapter --task "Scale the canonical adapter contract" --profile adapter_contract --status approved --output .brief/adapter-contract.json
Verify every target against current evidence
Ask your coding agent
Verify this reference rollout before handoff. For every target, prove the required semantic scenarios and any visual or accessibility obligations against the current contract, adaptation manifest, and target content. Refresh the rollout with the resulting proof IDs and digests. Treat missing inventory, stale evidence, unverified targets, and unapproved exceptions as non-passing, then pass the convergence proof to brief.review_diff.
- A changed reference, contract, target context, or target file makes old proof stale.
- A partial inventory cannot be reported as complete coverage.
- An exception needs a reason and accountable approval; it remains visible debt.
- For frontend fidelity, verify behavior and rendered evidence—not a screenshot filename or an agent-authored claim.
Run repository-owned conformance proof
brief reference-proof run --repo "$PWD" --contract-file .brief/adapter-contract.json --manifest-file .brief/github-manifest.json --command "pnpm test:adapter -- --brief-result .brief/github-result.json" --result-file .brief/github-result.json --output .brief/github-proofs.json
Understand missing and unavailable results
- reference_not_found: check the exact ID and scope, then list available references without a filter.
- team_context_unavailable: restore the workspace connection or required context:read permission before concluding that the reference is missing.
- A team candidate is not available to other agents until a maintainer approves it in the web app.
- A failed team proposal leaves the local reference intact. Fix the reported connection or permission problem, then retry explicit sharing.
- If an approval or archive request times out, refresh before retrying so you do not repeat a decision that may already have completed.
Was this guide useful?Help us make Brief easier to learn.
Ready for another workflow?Choose your next mission →