Schemas — Intent

Signal

The atomic unit of the Notice layer. A signal is a structured observation — something noticed during work that's worth tracking. Signals have trust scores, autonomy levels, and flow through a lifecycle from captured to promoted.

Template: .intent/templates/signal.md
Storage: .intent/signals/YYYY-MM-DD-slug.md
Live examples: Signal dashboard (15 signals)

Frontmatter Fields

Field	Type	Description
`id`	string	Sequential identifier (SIG-001, SIG-002, ...)
`timestamp`	ISO 8601	When the signal was captured
`source`	enum	cli \| mcp \| slack \| conversation \| pr-review \| agent-trace
`confidence`	float	0.0–1.0 — how confident the capturer is this matters
`trust`	float	0.0–1.0 — computed from trust factors (see below)
`autonomy_level`	enum	L0 \| L1 \| L2 \| L3 \| L4 — derived from trust score
`status`	enum	captured \| active \| clustered \| promoted \| dismissed
`cluster`	string?	Cluster name if grouped with related signals
`author`	string	Who captured the signal
`related_intents`	list	Intent IDs this signal relates to
`parent_signal`	string?	SIG-ID if this is a refinement of another signal

Trust Scoring Formula

trust = clarity × 0.30 + (1/blast_radius) × 0.20 + reversibility × 0.20 + testability × 0.20 + precedent × 0.10

Factor	Weight	Description
Clarity	30%	How well-defined is the observation? Vague hunch vs. concrete pattern.
Blast Radius	20%	Inverse — high blast radius lowers trust. How much damage if wrong?
Reversibility	20%	Can the action taken on this signal be undone?
Testability	20%	Can we verify the signal's accuracy before acting?
Precedent	10%	Have similar signals been successfully acted on before?

Autonomy Levels

Level	Trust Range	Behavior
L0	< 0.2	Human drives all action. Agent only records.
L1	0.2 – 0.4	Agent suggests actions. Human decides.
L2	0.4 – 0.6	Agent proposes and awaits approval.
L3	0.6 – 0.85	Agent executes with human monitoring.
L4	≥ 0.85	Full autonomy with circuit breakers only.

Intent

An intent is a problem worth solving — promoted from clustered signals. It's the bridge between "we keep noticing this" and "let's spec a solution." Intents carry evidence from the signals that spawned them.

Template: .intent/templates/intent.md
Storage: .intent/intents/INT-NNN-slug.md

Frontmatter Fields

Field	Type	Description
`id`	string	Sequential identifier (INT-001, INT-002, ...)
`title`	string	Short description of the problem
`status`	enum	proposed \| accepted \| specced \| executing \| complete \| archived
`proposed_by`	string	Who proposed the intent
`signals`	list	SIG-IDs that led to this intent
`specs`	list	SPEC-IDs created from this intent
`owner`	string	Who is responsible for this intent
`priority`	enum	now \| next \| later
`product`	enum	notice \| spec \| execute \| observe

Sections

Problem statement, desired outcome, evidence from signals, constraints, and open questions.

Spec

A spec is intent made executable. It's the contract between the person shaping work and the agent (or person) building it. Good specs are verifiable — you can test whether they've been fulfilled. Specs have an independent lifecycle and may spawn multiple atoms.

Template: .intent/templates/spec.md
Storage: spec/SPEC-NNN-slug.md

Frontmatter Fields

Field	Type	Description
`id`	string	Sequential identifier (SPEC-001, SPEC-002, ...)
`title`	string	What this spec delivers
`version`	string	Semantic version of this spec (e.g., 1.0, 1.1)
`status`	enum	draft \| review \| approved \| executing \| complete
`intent`	string	Parent intent ID (INT-NNN)
`product`	string	Product boundary this spec addresses
`author`	string	Who wrote the spec
`contracts`	list	Contract IDs this spec requires
`atoms`	list	Atom IDs (ATOM-NNN) created from this spec
`assignee`	string	Who/what is executing this spec
`completeness_score`	float	0.0–1.0 — how complete is the specification
`agent_ready`	boolean	True if spec is structured enough for agent execution

Sections

Problem statement, solution description, contracts (verifiable assertions), acceptance criteria, out of scope, dependencies, and test scenarios.

Contract

A contract is a verifiable assertion about what must be true when a spec is fulfilled. Contracts are the smallest testable unit — like assertions in code, but for any kind of work. They come in four types: interface, behavior, quality, and integration. Contracts have an independent lifecycle separate from the specs they verify.

Template: .intent/templates/contract.md
Storage: inline within spec files or standalone in spec/contracts/

Frontmatter Fields

Field	Type	Description
`id`	string	Sequential identifier (CON-001, CON-002, ...)
`title`	string	What this contract asserts
`spec`	string	Parent spec ID (SPEC-NNN)
`status`	enum	defined \| verified \| failed \| revised
`type`	enum	interface \| behavior \| quality \| integration
`severity`	enum	critical \| major \| minor — impact if contract fails
`verification_method`	enum	manual \| cli-command \| test-suite \| automated
`verification_command`	string?	Command or test to verify this contract
`verified_date`	ISO 8601?	When last verified
`verified_by`	string?	Who or what verified it

Contract Types

Type	Description	Example
Interface	API shape, input/output format	"CLI accepts --format json flag"
Behavior	What happens when invoked	"Emits signal.created event on capture"
Quality	Non-functional requirements	"Response time under 200ms"
Integration	Cross-system interaction	"Event appears in events.jsonl within 5s"

Atom

An atom is an execution envelope — a single pass through the work stream. Atoms are spawned by specs and coordinate execution, but do not contain the specs or contracts themselves. They reference specs for validation logic and contracts for verification, placing them at the intersection of ephemeral and persistent work.

Template: .intent/templates/atom.md
Storage: .intent/atoms/ATOM-NNN-slug.md

Frontmatter Fields

Field	Type	Description
`id`	string	Sequential identifier (ATOM-001, ATOM-002, ...)
`title`	string	Name of this execution unit
`status`	enum	planned \| in-progress \| complete \| failed \| blocked
`parent_intent`	string	Parent intent ID (INT-NNN)
`spec`	string	Reference to spec being executed (SPEC-NNN)
`contracts`	list	Contract IDs (CON-NNN) to be verified
`product`	string	Product boundary this atom operates within
`capability`	string	Capability within the product
`autonomy_level`	enum	L0 \| L1 \| L2 \| L3 \| L4 — autonomy granted for execution
`trust_score`	float	0.0–1.0 — computed trust score for this execution
`executor`	string	Human or agent identifier performing the work
`arb_verdict`	enum	proceed \| review \| block — ARB decision on execution

Sections

Execution plan, resource requirements, success criteria, risk assessment, and post-execution analysis.

Event

Every action in the Intent system emits a structured event. Events are the raw material for the Observe layer — they tell you what happened, when, and in response to what. The event schema is OTel-compatible by design.

Catalog: 15 event types documented
Storage: .intent/events/events.jsonl (one JSON object per line)

Event Envelope

Field	Type	Description
`event`	string	Event type (e.g., signal.created, intent.proposed)
`timestamp`	ISO 8601	When the event occurred
`actor`	string	Who or what triggered the event
`ref`	string	ID of the artifact affected (SIG-001, SPEC-003, etc.)
`data`	object	Event-specific payload
`source`	string	Emission mechanism (cli, mcp, github-action, etc.)

Event Types (15)

Category	Events
Signal	signal.created, signal.updated, signal.dismissed, signal.clustered, signal.promoted
Intent	intent.proposed, intent.accepted, intent.specced, intent.completed
Spec	spec.created, spec.approved, spec.executing, spec.completed
Contract	contract.verified, contract.failed
System	system.status (roadmap/health check)

Knowledge Artifact Schemas

The Knowledge Engine (Layer 1) compiles raw sources into structured knowledge artifacts. Six artifact types form the compiled knowledge base. Each artifact is a markdown file with YAML frontmatter, following the schema defined in knowledge-engine/AGENTS.md.

Persona (PER-NNN)

Storage: knowledge/personas/
A structured representation of a user or stakeholder type, compiled from research sources and agent analysis.

Field	Type	Description
`id`	string	Sequential identifier (PER-001, PER-002, ...)
`type`	enum	persona
`subtype`	enum	product \| role \| hero \| stakeholder \| engagement \| archetype
`name`	string	Persona name or archetype label
`confidence`	float	0.0–1.0 — corroboration level across sources
`origin`	enum	human \| agent \| synthetic — source of the persona
`sources`	list	Source IDs or references this persona derives from
`related_journeys`	list	Journey map IDs (JRN-NNN) associated with this persona
`related_decisions`	list	Design decision IDs (DDR-NNN) this persona influences
`pain_points`	list	Named pain points or friction areas

Journey Map (JRN-NNN)

Storage: knowledge/journeys/
A structured narrative of a persona's experience over time, with stages, emotions, and decision points.

Field	Type	Description
`id`	string	Sequential identifier (JRN-001, JRN-002, ...)
`type`	enum	journey
`name`	string	Journey name or scenario label
`persona`	string	Associated persona ID (PER-NNN)
`confidence`	float	0.0–1.0 — evidence strength for this journey
`origin`	enum	human \| agent \| synthetic
`sources`	list	Source IDs this journey derives from
`related_decisions`	list	Decision IDs (DDR-NNN) influenced by this journey
`stages`	list	Ordered stage names (H3 sections in body with substeps, emotions, pain points)

Design Decision Record (DDR-NNN)

Storage: knowledge/decisions/
A structured record of a design choice, its rationale, validation status, and impact on personas and journeys.

Field	Type	Description
`id`	string	Sequential identifier (DDR-001, DDR-002, ...)
`type`	enum	decision
`title`	string	Decision statement (e.g., "Use webhooks for async events")
`status`	enum	proposed \| accepted \| superseded \| validated \| invalidated
`confidence`	float	0.0–1.0 — validation strength
`origin`	enum	human \| agent \| synthetic
`addresses`	list	Pain point IDs or challenge names this decision resolves
`persona`	string?	Primary persona affected (PER-NNN)
`journey_stage`	string?	Journey stage where this decision matters
`superseded_by`	string?	Newer decision ID (DDR-NNN) if this is outdated
`validated_by`	list	Validation method IDs or test results confirming this decision

Theme (THM-NNN)

Storage: knowledge/themes/
A cross-cutting concern or pattern observed across personas, journeys, and decisions.

Field	Type	Description
`id`	string	Sequential identifier (THM-001, THM-002, ...)
`type`	enum	theme
`name`	string	Theme label (e.g., "Asynchronous Communication", "Trust Validation")
`confidence`	float	0.0–1.0 — how consistently this theme appears
`origin`	enum	human \| agent \| synthetic
`sources`	list	Source IDs supporting this theme
`related_personas`	list	Persona IDs (PER-NNN) affected by this theme
`related_journeys`	list	Journey IDs (JRN-NNN) where this theme appears
`related_decisions`	list	Decision IDs (DDR-NNN) addressing this theme
`signals`	list	Signal IDs (SIG-NNN) that first surfaced this theme

Domain Model (DOM-NNN)

Storage: knowledge/domain-models/
A structured representation of entities, relationships, and constraints within a bounded context or problem domain.

Field	Type	Description
`id`	string	Sequential identifier (DOM-001, DOM-002, ...)
`type`	enum	domain-model
`name`	string	Domain name or bounded context label
`scope`	enum	glossary \| bounded-context \| entity-relationship \| state-machine
`confidence`	float	0.0–1.0 — structural validation level
`origin`	enum	human \| agent \| synthetic

Design Rationale (RAT-NNN)

Storage: knowledge/design-rationale/
A narrative explaining the reasoning behind design choices, frameworks applied, and trade-offs considered.

Field	Type	Description
`id`	string	Sequential identifier (RAT-001, RAT-002, ...)
`type`	enum	rationale
`name`	string	Rationale title or topic
`confidence`	float	0.0–1.0 — consensus or validation level
`origin`	enum	human \| agent \| synthetic
`related_decisions`	list	Decision IDs (DDR-NNN) explained by this rationale
`frameworks`	list	Named frameworks applied (Torres, Cagan, Jobs-to-be-Done, etc.)

Federation & Confidentiality

Every knowledge artifact carries two federation fields:

engagement (string | null): Engagement ID for federated workspaces. null = Core. Cross-scope references use Core:PER-001 notation when an Engagement references Core artifacts. Core→Engagement references are not needed. Engagement→Engagement references are forbidden.
confidentiality (enum): One of public, internal, client-internal, or nda. Controls artifact visibility and usage.

Origin Tracking: The origin field (human | agent | synthetic) indicates the source. Agent-generated artifacts start with confidence ≤ 0.5 unless independently corroborated.

Entity Dossiers

Six dossier types serve as an intermediate compilation step between raw sources and the six artifact types above. Dossiers aggregate raw evidence before synthesis:

DSR-PER: Persona source compilation — raw research about a user type
DSR-COM: Competitive intelligence — market and competitor analysis
DSR-PRD: Product research — feature reviews, use case studies
DSR-SVC: Service research — workflow and process documentation
DSR-IND: Industry research — domain trends and standards
DSR-CTX: Context research — organizational and team structure

Dossiers are working documents. Once synthesized into Personas, Journeys, Decisions, Themes, Domain Models, or Design Rationales, they may be archived.

Work Ontology v2

Intent v2 organizes work around a two-plane architecture: ephemeral flow entities (Signal → Intent → Atom → Event → Trace) and persistent artifacts (Spec, Contract) that bridge the planes. An independent ownership topology (Product → Capability → Team) provides structural context via the Inverse Conway Maneuver.

Full reference: Work ontology page

Work Stream (Ephemeral Flow)

Entity	Schema	Lifecycle	Description
Signal	signal.md	captured → active → clustered → promoted → dismissed	Raw observation from work
Intent	intent.md	proposed → accepted → specced → executing → complete	Problem worth solving, promoted from signals
Atom	atom.md	planned → in-progress → complete \| failed \| blocked	Single pass through execution (ephemeral envelope)
Event	JSONL	emitted → ingested → traced	Structured action record
Trace	OTel Span	started → span events → ended	Execution observability (Span = Atom, Leaf Span = Contract Verification)

Persistent Artifacts (Bridge)

Artifact	Schema	Lifecycle	Purpose
Spec	spec.md	draft → review → approved → executing → complete	Intent made executable; referenced by atoms for validation logic
Contract	contract.md	defined → verified → failed \| revised	Verifiable assertion; checked during atom execution

Ownership Topology (Persistent Structure)

Level	Entity	Schema	Description
1	Product	product.md	Value boundary a team owns; context for Inverse Conway formation
2	Capability	—	Functional grouping within a product
3	Team	team.md	Persistent group of humans and agents that owns products

OTel Mapping

Intent Entity	OTel Concept	Mapping
Intent	Trace	A logical work session; the context for all atoms it spawns
Atom	Span	A single execution unit; contains contract verifications
Contract Verification	Leaf Span	Terminal span that verifies a contract assertion
Signal	Span Event	An event emitted within a span's execution

Product

A product is a value boundary that a team owns. It's not a work item but a context boundary — the unit that drives team formation through the Inverse Conway Maneuver. Products contain capabilities and define the persona-centric value stream your team delivers.

Template: .intent/templates/product.md
Storage: .intent/products/PROD-slug.md

Frontmatter Fields

Field	Type	Description
`id`	string	Product identifier (short slug, e.g., "signals")
`title`	string	Product name
`owner`	string	Primary owner (person or team ID)
`team`	list	Team member identifiers (human or agent)
`maturity`	enum	operational \| conceptual \| defined \| schema-ready
`value_stream`	string	How this product delivers value
`persona_key`	string	Primary persona this product serves
`capabilities`	list	Capability names or IDs within this product
`repositories`	list	Repository URLs or slugs related to this product
`file_paths`	list	Directory paths or file patterns owned by this product

Sections

Value proposition, personas served, capabilities overview, team charter, and integration points with other products.

Team

A team is a persistent group of humans and agents that owns products. Teams are formed around product boundaries (Inverse Conway), have defined autonomy boundaries, and escalation paths for decisions that cross boundaries.

Template: .intent/templates/team.md
Storage: .intent/teams/TEAM-slug.md

Frontmatter Fields

Field	Type	Description
`id`	string	Team identifier (short slug, e.g., "signals-team")
`title`	string	Team name
`type`	enum	stream-aligned \| platform \| enabling \| complicated-subsystem
`products`	list	Product IDs this team owns
`members.humans`	list	Human team member identifiers or email addresses
`members.agents`	list	Agent identifiers or service names
`autonomy_boundary`	string	What decisions this team can make independently
`escalation_path`	list	Chain of escalation for decisions outside autonomy boundary

Team Types

Type	Description	Owns
Stream-Aligned	Organized around a value stream	One or more products in a coherent stream
Platform	Builds internal capabilities	Shared infrastructure or tools
Enabling	Coaches and unblocks other teams	Knowledge, process, observability
Complicated Subsystem	Owns specialized, complex domain	Deep expertise area (e.g., cryptography)

Sections

Team charter, success criteria, communication norms, decision-making framework, and quarterly priorities.

Signal Amplification

Signals gain weight through repeated reference — like citation count in academic papers or PageRank for web pages. The amplification system tracks cross-references and adjusts effective trust over time.

Spec: spec/signal-amplification.md

Amplification Fields (proposed)

Field	Type	Description
`referenced_by`	list	IDs of artifacts that reference this signal
`reference_count`	int	Total reference count
`last_referenced`	ISO 8601?	Most recent reference timestamp
`amplification_score`	float	Computed from weighted, time-decayed references
`effective_trust`	float	min(1.0, base_trust + amplification_score)

Reference Weights

Reference Type	Weight
Signal → Signal	0.15
Conversation	0.10
Commit message	0.05
Intent / Spec	0.20

Decay: References have a 7-day half-life. Recent references count more than old ones.
Re-evaluation: When effective_trust crosses an autonomy level boundary, the signal is flagged for review.

Why these schema shapes were chosen →