Intent Author

Intent Author

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:

@dataclass
class IntentNode:
    # ─── 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
  • stability (float, required) — 0.0-1.0 confidence score
  • 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.

Rules:

• Never claim stability > 0.6 without passing tests
• 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:

class IntentResolver:
    def __init__(self, intent_author_skill):
        self.skill = intent_author_skill

    def validate_intent(self, intent: IntentNode) -> list[str]:
        """Validate intent quality before publishing to graph."""
        issues = []

        if len(intent.action) < 20:
            issues.append("Action too vague — be more specific")

        if intent.stability > 0.3 and not intent.evidence:
            issues.append("Stability > 0.3 requires evidence")

        if intent.stability > 0.6 and "test" not in " ".join(intent.evidence).lower():
            issues.append("Stability > 0.6 should have test evidence")

        if intent.category == "interface" and not intent.provides:
            issues.append("Interface intent must declare what it provides")

        if intent.category == "constraint" and not 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

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