Skip to main content
Agents are more useful when they can reason from business context.

​
Build the chain

  1. As an organization owner or admin, create a goal with a target date.
  2. Attach one or more KPIs.
  3. Create initiatives expected to move those KPIs.
  4. Link initiatives to projects, milestones, and tasks.
  5. Record KPI snapshots as work changes the metric.

​
Example

If the KPI is off pace and the initiative has blocked tasks, heartbeat can show that unblocking the docs launch is more important than a lower-priority unrelated task.

​
Strategy page for agents

The Strategy page shows the same reasoning chain humans and agents use:
  • Attention ranks stale KPIs, off-pace KPIs, stalled initiatives, blocked tasks, overdue tasks, and overdue milestones.
  • Plan summarizes goals, KPI health, initiatives, linked work, and gaps.
  • Update KPIs shows KPI freshness, target health, current values, sync state, and manual update controls.
  • Trace Chain traces Goal -> KPI -> Initiative -> Project -> Task.
  • Audit Table gives a dense scan across projects, owners, target dates, KPI values, health, task progress, and risk.
When you are working in an org with multiple companies or workstreams, use the project/company, owner, date, health, status, and risk filters before deciding which strategy signal to act on. When heartbeat can infer one concrete next action, the Strategy page shows a strategy-backed action card above the views. It may recommend creating missing work, starting linked work, escalating a blocker, or refreshing a metric. The card can prefill issue creation, update task status, open KPI snapshot recording with initiative attribution, or submit blocker/progress comments with the strategy evidence preserved.

​
KPI snapshots

Snapshots update KPI current value and create attribution history. Goal reads are available to organization members. Creating or updating goals, including through the first-time Strategy wizard, requires organization owner/admin Strategy write access. KPI reads require non-guest organization-wide Strategy access. Creating, updating, or deleting a KPI and recording snapshots require organization owner/admin Strategy write access. Guest and project-scoped agents cannot read the KPI collection, and direct KPI routes return 404 for unreadable KPIs. Before using KPI or per-KPI sync commands, verify that the active Atoll profile has the required organization-wide role; do not treat project access as KPI access.
Use atoll kpi snapshot add <kpi> --value ... --initiative "<initiative>" --issue ATOLL-123 --note "..." to attribute a measurement to the work that produced it. Use atoll kpi snapshot list <kpi> --include-attribution --json to inspect that history, and atoll heartbeat --explain-kpi <kpi> --json to see the canonical KPI status with linked initiatives and recent attributed snapshots.

​
Read relationship context

Use the detail reads when an agent needs the strategy relationship graph:
  • GET /api/orgs/{id}/initiatives/{initiativeId} embeds kpi_impacts only for linked KPIs readable by the caller.
  • GET /api/orgs/{id}/kpis/{kpiId} embeds visible initiative_impacts across all initiative statuses, filtered by project-aware initiative access.
These fields describe intended impact. Keep them separate from snapshot attribution, which records what produced one measurement. The detail fields are read-only; use the existing initiative KPI link/unlink operations for relationship mutations. For launch-style goals, use an internal task-completion KPI instead of snapshots:
This KPI calculates done directly linked and milestone-linked tasks over total linked tasks for initiatives under the goal.

​
Initiative health

Heartbeat summarizes linked execution:
  • Total issues
  • Completed issues
  • Stalled issues
  • Blocked issues
  • Expected KPI impacts
Link tasks to initiatives when the work exists to move a KPI. Leave routine chores unlinked unless they truly affect a strategic objective.

​
Audit the chain

Heartbeat is the operational lens (what to do today). The audit is the structural lens — is the strategy well-formed? GET /api/orgs/{id}/strategy/audit (CLI: atoll strategy audit) returns findings[] with a severity and a concrete suggested_fix for each gap: orphaned initiatives/KPIs (no goal), goals with no KPI or no initiative, KPIs missing targets or stale, initiatives missing impact/execution, and blocked/overdue work. The audit is scoped to the caller. Owners and admins receive organization-wide execution evidence. Other non-guest members receive issues, milestones, target links, and target findings only through readable projects. Shared initiatives are redacted at each nested link, and a restricted member with no readable projects receives no issue or target execution evidence. Guests cannot run the audit. Strategy audit focuses on active planning records. Paused and cancelled goals are excluded from active goal findings, KPIs attached to inactive goals do not create KPI health findings, and paused, completed, or cancelled initiatives do not create initiative health findings.
The audit only diagnoses — fix findings with the normal goal/KPI/initiative write endpoints, then re-run to confirm they cleared.