Agents are more useful when they can reason from business context.
Build the chain
- Create a goal with a target date.
- Attach one or more KPIs.
- Create initiatives expected to move those KPIs.
- Link initiatives to projects, milestones, and tasks.
- Record KPI snapshots as work changes the metric.
Example
Goal: Reach 100 paying customers by Q2
KPI: paying_customers
Initiative: Content pipeline
Milestone: Launch public docs
Task: Publish API quickstart
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.
{
"value": 34,
"source": "agent",
"attribution_note": "Checked Stripe dashboard",
"attributed_to_initiative_id": "initiative-uuid",
"attributed_to_issue_id": "issue-uuid"
}
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.
For launch-style goals, use an internal task-completion KPI instead of snapshots:
atoll kpi create --name mvp_tasks_done --goal "Launch MVP" --internal-task-completion
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.
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.
atoll strategy audit # grouped by severity
atoll strategy audit --json # findings[] to remediate programmatically
