AI Agents

After each command commits, Specor automatically runs proactive AI agents in the background. Agents read the affected part of the product graph and produce suggestions — structured observations that surface in the UI and API.

How agents work

A command commits and produces events.
Each agent that is configured to trigger on that event type runs asynchronously.
The agent receives a context pack — the affected node plus its two-hop neighbourhood, open suggestions, and relevant ontology rules — and analyses it.
Suggestions are deduplicated and filtered against suppressions before being saved.
Suggestions appear in the workspace inbox.

Agents can chain: accepting a suggestion may execute a command, which triggers agents again, up to a depth of 3.

Agent types

`coverage`

Checks whether required semantic elements are present for each node type.

Category	Triggered when
`feature_missing_metric`	A Feature has no linked Metric
`feature_missing_acceptance_criteria`	A Feature has no AcceptanceCriteria
`feature_missing_need`	A Feature is not linked to any Need
`flow_missing_actor_assignment`	A Flow has no Actor
`capability_missing_feature`	A Capability has no child Features
`metric_missing_target`	A Metric has no `target_value`
`need_not_addressed`	A Need is not linked to any Feature
`duplicate_feature`	A Feature appears semantically identical to another

Triggers on: node created / updated for Feature, Flow, Capability, Metric, Need, Domain; edge created.

`conflict`

Detects semantic contradictions between connected nodes.

Category	Triggered when
`contradicting_feature_rules`	Two Rules on the same Feature contradict each other
`feature_rule_conflicts_capability_constraint`	A Feature’s Rule conflicts with its parent Capability
`circular_flow_dependency`	Steps in a Flow form a cycle

Triggers on: Rule, Feature, Capability, Flow, or Step created, updated, or with edges added/removed.

`flow`

Checks the structural integrity of Flows.

Category	Triggered when
`flow_no_terminal_step`	A Flow has no Step that has no outgoing `next_step` edge
`flow_unreachable_step`	A Step exists that cannot be reached from the first Step
`flow_invalid_state_transition`	A Step transition violates the defined state machine

Triggers on: Flow or Step created, updated, or with edges changed.

`impact`

Tracks downstream consequences of structural changes.

Category	Triggered when
`metric_linked_to_deleted_feature`	A Metric’s Feature was deleted
`flows_need_review_after_rule_change`	A Rule changed on a Feature that has Flows
`feature_archived_with_many_dependents`	A Feature is archived but other nodes depend on it
`flow_unowned_no_actor_steps`	A Flow has steps but no Actor involvement
`need_orphaned_after_feature_change`	A Need lost all its linked Features

Triggers on: any node updated, deleted, moved, or with edges removed.

`naming`

Flags vague or low-quality node titles and descriptions.

Category	Triggered when
`placeholder_title`	Title looks like a placeholder (e.g. “New Feature”, “TODO”)
`missing_description`	Node has no description
`overly_generic_title`	Title is too generic to be useful
`title_too_short`	Title is fewer than 3 meaningful words
`description_too_vague`	Description is present but gives no information

Triggers on: any node created or updated.

`alignment`

Checks whether connected nodes are semantically consistent with each other.

Category	Triggered when
`feature_misaligned_with_need`	A Feature does not actually address its linked Need
`feature_misaligned_with_capability`	A Feature is outside its parent Capability’s scope
`capability_misaligned_with_domain`	A Capability does not fit its Domain
`acceptance_criteria_misaligned_with_feature`	An AcceptanceCriteria tests the wrong thing
`metric_misaligned_with_feature_goal`	A Metric does not measure what the Feature aims to achieve
`need_outside_domain_scope`	A Need is linked to a Domain it does not belong to

Triggers on: Feature, Capability, Need, AcceptanceCriteria, or Metric created, updated, or with edges added.

Suggestion lifecycle

A suggestion starts in pending and moves to one of:

Status	How it gets there
`pending`	Created by an agent
`snoozed`	User deferred it until a future date
`accepted`	User accepted and executed the suggested command
`rejected`	User dismissed it (optionally with a note)

Rejected suggestions can be suppressed — the agent will not raise that category for that node again. Suppressions can be deleted to re-enable the agent for a node.

Confidence and severity

Each suggestion has a confidence (0.0–1.0) and a severity (info, warning, error). If confidence is below 0.5, severity is automatically downgraded to info regardless of the agent’s output.

Enabling / disabling agents

Agents can be toggled per workspace via PATCH /workspaces/{id}/agent-config. Disabled agents produce no suggestions but their runs are still recorded.