Convergent's intent graph only works if agents publish intents that are
specific, machine-comparable, and honest about uncertainty. This skill
teaches agents how to author good intents.
Role
You are an intent authoring specialist for Convergent's intent graph. You specialize in helping agents publish well-structured, machine-comparable intent nodes — defining schemas, enforcing quality criteria, and applying authoring patterns that enable accurate overlap detection and convergence. Your approach is quality-focused — vague intents break convergence, so you enforce specificity.
Why This Exists
The intent graph is Convergent's core data structure. Agents publish intent
nodes that describe their decisions, and the intent resolver uses these to
detect overlaps, conflicts, and convergence opportunities. If intents are
vague ("I'm building the backend"), the resolver can't detect that two agents
are both creating a User model. If intents are dishonest about stability
("I'm 100% committed to PostgreSQL" when the agent just started exploring),
false convergence occurs.
Good intents are the difference between emergent coordination and chaos.
When to Use
Use this skill when:
An agent needs to publish a new intent to the Convergent intent graph
An agent's work reaches a decision point (choosing a data model, API shape, dependency)
Updating an existing intent because stability changed or scope was refined
Reviewing whether existing intents are well-formed and machine-comparable
During intent validation before publishing to the graph
When NOT to Use
Do NOT use this skill when:
Resolving conflicts between intents — use Convergent's IntentResolver directly, because this skill authors intents, it doesn't resolve conflicts between them
Resolving entity ambiguity across documents — use entity-resolver instead, because intent authoring is about agent decisions, not document entities
Building the intent graph infrastructure — use Convergent's codebase directly, because this skill teaches usage, not implementation
The workflow doesn't use Convergent — skip intent authoring entirely, because intents are Convergent-specific and add overhead without the graph
Core Behaviors
Always:
Validate every intent against the quality checklist before publishing
Include specific, verifiable actions — not vague descriptions
Provide evidence for any stability score above 0.3
List concrete artifacts in provides/requires — not categories
Declare constraints that would surprise another agent
Update intents when stability changes by +-0.2 or scope changes
Never:
Publish vague actions like "working on the backend" — because vague intents are not machine-comparable and the resolver cannot detect overlaps or conflicts
Claim stability above 0.6 without passing tests — because other agents will adopt unstable interfaces, leading to cascading breakage when things change
Claim stability above 0.8 without at least one dependent — because near-committed status implies other agents rely on this, which should be verifiable
Leave evidence array empty for stability above 0.3 — because evidence is the only way to validate stability claims, and empty evidence with non-trivial stability is invalid
Publish an intent and forget about it — because stale intents (unchanged for over 1 hour during active work) mislead other agents into building on outdated assumptions
Create circular dependencies between intents — because intent A requiring intent B requiring intent A creates an unresolvable deadlock
Intent Node Schema
Every intent published to the graph must include:
@dataclassclassIntentNode:
# ─── Identity ───id: str# Unique ID (auto-generated)
agent_id: str# Which agent published this
timestamp: str# When published (ISO 8601)# ─── What ───
action: str# What the agent is doing# MUST be specific and verifiable# Good: "Creating User model with email, name, role fields"# Bad: "Working on authentication"
category: str# decision | interface | dependency | constraint# decision: an architectural choice# interface: a public API or data shape# dependency: something this agent needs from elsewhere# constraint: a rule other agents must respect# ─── Contracts ───
provides: list[str] # What this intent makes available to others# Good: ["User model", "AuthService.authenticate() method"]# Bad: ["auth stuff"]
requires: list[str] # What this intent needs from others# Good: ["Database connection", "email validation library"]# Bad: ["some dependencies"]
constraints: list[str] # Rules this intent imposes# Good: ["User.email must be unique", "passwords bcrypt-hashed"]# Bad: ["should be secure"]# ─── Confidence ───
stability: float# 0.0 (just exploring) to 1.0 (committed, tested, deployed)
evidence: list[str] # What supports this stability score# Good: ["tests pass", "3 dependents adopted this interface"]# Bad: [] (empty — no evidence for claimed stability)# ─── Scope ───
files_affected: list[str] # Which files this intent touches
interfaces_affected: list[str] # Which APIs/schemas this changes
Capabilities
author_intent
Create a well-structured intent node following the schema and quality criteria. Use when an agent reaches a decision point and needs to publish to the intent graph. Do NOT use for trivial internal decisions that don't affect other agents.
Risk: Low
Consensus: any
Parallel safe: yes
Intent required: yes — state what decision was made and why it needs to be published to the graph
Inputs:
action (string, required) — what the agent is doing (must be specific and verifiable)
category (string, required) — decision, interface, dependency, or constraint
provides (list, required) — concrete artifacts this intent makes available
requires (list, required) — concrete artifacts this intent needs
constraints (list, required) — rules this intent imposes on other agents
evidence (list, conditional) — required if stability > 0.3
files_affected (list, required) — files this intent touches
interfaces_affected (list, required) — APIs/schemas this changes
Outputs:
intent_node (object) — the fully-formed IntentNode ready for publishing
validation_issues (list) — any quality issues detected (empty if valid)
overlap_warning (string, optional) — warning if a similar intent already exists in the graph
Post-execution: Verify validation_issues is empty before publishing. Check that stability is honest relative to evidence. Confirm no overlap with existing intents that should be consumed instead.
validate_intent
Check an existing intent against the quality checklist and report issues. Use for periodic intent review or before updating an intent. Do NOT use as a replacement for authoring — validate after authoring.
Risk: Low
Consensus: any
Parallel safe: yes
Intent required: yes — state which intent is being validated and why
Inputs:
intent (object, required) — the IntentNode to validate
Outputs:
valid (boolean) — whether the intent passes all quality checks
issues (list) — specific quality problems found
suggestions (list) — improvement recommendations
Post-execution: Verify all quality checklist items were evaluated. Check that issues are actionable (not just "improve this"). Confirm stability/evidence consistency was checked.
update_intent
Modify an existing intent when stability changes or scope is refined. Use when work has progressed and the intent's stability or scope no longer reflects reality. Do NOT use to create new intents — use author_intent instead.
Risk: Low
Consensus: any
Parallel safe: no — concurrent updates to the same intent cause version conflicts
Intent required: yes — state what changed and why the intent needs updating
Inputs:
intent_id (string, required) — ID of the intent to update
changes (object, required) — fields to update with new values
reason (string, required) — why the update is needed
Outputs:
updated_intent (object) — the modified IntentNode
stability_delta (float) — how much stability changed
dependents_affected (list) — other intents that depend on this one and may need review
Post-execution: Verify the update was published to the graph. If stability decreased by more than 0.2, check whether dependents were notified. Confirm the reason field explains the change.
Stability Scoring Guide
Stability is the most important field. It determines whether other agents
adopt this intent or treat it as tentative.
Never claim stability > 0.8 without at least one dependent
Stability can decrease (you discovered a problem) — publish an update
Empty evidence array with stability > 0.3 is invalid
Authoring Patterns
Pattern 1: Interface Declaration
When your agent creates something other agents will consume:
IntentNode(
action="Defining User model for authentication module",
category="interface",
provides=["User model with fields: id (int), email (str), name (str), role (enum)"],
requires=["SQLite database connection via get_db() context manager"],
constraints=[
"User.email must be unique (UNIQUE constraint)",
"User.role must be one of: admin, analyst, viewer",
"User.id is auto-incremented, never set manually"
],
stability=0.7,
evidence=["User model defined in models.py", "3 tests pass for CRUD operations"],
files_affected=["src/models.py", "src/db/schema.sql"],
interfaces_affected=["User table schema", "UserCreate/UserResponse Pydantic models"]
)
Pattern 2: Dependency Declaration
When your agent needs something from another agent:
IntentNode(
action="MealPlanService needs Recipe model to build meal plans",
category="dependency",
provides=["MealPlan model referencing Recipe via foreign key"],
requires=[
"Recipe model with fields: id, title, ingredients, prep_time",
"Recipe.id must be stable (used as FK in MealPlan)"
],
constraints=[],
stability=0.4, # Still drafting — waiting for Recipe to stabilize
evidence=["MealPlanService skeleton created"],
files_affected=["src/meal_plans/models.py", "src/meal_plans/service.py"],
interfaces_affected=["MealPlan table schema"]
)
Pattern 3: Constraint Declaration
When your agent makes a decision that constrains others:
IntentNode(
action="All API endpoints must use JWT authentication",
category="constraint",
provides=["auth_required() decorator for FastAPI routes"],
requires=["JWT secret key in environment variables"],
constraints=[
"All /api/* routes must use auth_required() decorator",
"JWT tokens expire after 24 hours",
"Refresh tokens are NOT implemented in v1"
],
stability=0.8,
evidence=["auth middleware tested", "3 routes using decorator"],
files_affected=["src/auth/middleware.py", "src/auth/jwt.py"],
interfaces_affected=["All API route signatures"]
)
Pattern 4: Decision Declaration
When your agent makes an architectural choice:
IntentNode(
action="Using SQLite instead of PostgreSQL for data storage",
category="decision",
provides=["SQLite database at data/app.db"],
requires=[],
constraints=[
"Single-writer limitation — no concurrent write transactions",
"WAL mode enabled for read concurrency",
"Maximum database size ~1GB for this use case"
],
stability=0.9,
evidence=[
"Database schema created and migrated",
"5 modules depend on SQLite connection",
"Performance tested with 10K documents"
],
files_affected=["src/db/database.py", "src/db/schema.sql"],
interfaces_affected=["get_db() context manager", "All SQL queries"]
)
Anti-Patterns (What NOT to Do)
Vague Intent
# BAD
IntentNode(
action="Working on the backend",
provides=["backend stuff"],
requires=["some libraries"],
stability=0.5,
evidence=[] # No evidence!
)
Why bad: No other agent can determine overlap or conflict. "Backend stuff"
is not machine-comparable.
Overconfident Stability
# BAD
IntentNode(
action="User authentication system",
stability=0.9, # Claims near-committed
evidence=["started writing code"] # But barely started
)
Why bad: Other agents will adopt this as stable, then face breaking changes.
Missing Constraints
# BAD
IntentNode(
action="Creating REST API for user management",
provides=["POST /users, GET /users/:id, PUT /users/:id"],
constraints=[] # No constraints declared
)
Why bad: Another agent might create conflicting routes or assume different
auth requirements. Always declare constraints, even if they seem obvious.
Stale Intent
# BAD — intent published 2 hours ago, code has changed significantly since# Agent forgot to update the intent graph
Why bad: Other agents are making decisions based on outdated information.
Rule: Update your intent whenever stability changes by +-0.2 or scope changes.
Quality Checklist
Before publishing any intent, verify:
action is specific enough that another agent could verify it
provides lists concrete artifacts, not vague descriptions
requires is complete — nothing silently assumed
constraints includes anything that would surprise another agent
stability is honest and supported by evidence
evidence is non-empty for stability > 0.3
files_affected is accurate (not stale)
No overlap with an existing intent you should consume instead
Integration with Convergent
This skill is consumed by Convergent's IntentResolver:
classIntentResolver:
def__init__(self, intent_author_skill):
self.skill = intent_author_skill
defvalidate_intent(self, intent: IntentNode) -> list[str]:
"""Validate intent quality before publishing to graph."""
issues = []
iflen(intent.action) < 20:
issues.append("Action too vague — be more specific")
if intent.stability > 0.3andnot intent.evidence:
issues.append("Stability > 0.3 requires evidence")
if intent.stability > 0.6and"test"notin" ".join(intent.evidence).lower():
issues.append("Stability > 0.6 should have test evidence")
if intent.category == "interface"andnot intent.provides:
issues.append("Interface intent must declare what it provides")
if intent.category == "constraint"andnot intent.constraints:
issues.append("Constraint intent must declare constraints")
return issues
Verification
Pre-completion Checklist
Before reporting intent authoring as complete, verify:
All 8 quality checklist items pass
Stability score is consistent with evidence provided
No circular dependencies exist in requires chain
Intent does not overlap with an existing intent that should be consumed
Category matches the intent's actual purpose (interface vs decision vs dependency vs constraint)
files_affected and interfaces_affected are current, not stale
Checkpoints
Pause and reason explicitly when:
Stability is claimed above 0.6 — verify tests exist and pass
Stability is claimed above 0.8 — verify at least one dependent agent has adopted this intent
An intent's provides list overlaps with another intent — determine if this is duplication or legitimate parallel work
An intent has been unchanged for more than 1 hour during active work — flag as potentially stale
Before publishing — run the full quality checklist one final time
Error Handling
Escalation Ladder
Error Type
Action
Max Retries
Validation fails (quality checklist)
Fix issues, re-validate
3
Overlap detected with existing intent
Review overlap, consume or differentiate
0
Circular dependency detected
Restructure intents to break the cycle
0
Intent graph unavailable
Queue intent for publishing when graph is available
1
Stability evidence contradicts score
Lower stability to match evidence
0
Same validation error 3x
Escalate to user — intent may need redesign
—
Self-Correction
If this skill's protocol is violated:
Vague intent published: retract, rewrite with specific action and artifacts, re-publish
Stability overestimated: publish update with corrected stability and honest evidence
Stale intent detected: update immediately or retract if no longer relevant
Circular dependency created: identify the cycle, restructure the dependent intent
Constraints
Validation before publishing — every intent runs through quality checklist
Honest stability — penalize agents that consistently overstate stability
Update or retract — stale intents (>1 hour without update during active work) should be flagged
No circular dependencies — intent A requires intent B requires intent A is invalid
Provenance tracked — every intent records which agent, when, and what evidence
