Goals and Background Execution

Norns supports long-term goal planning with autonomous background execution. This allows the supervisor to define goals with a definition of done, create granular execution plans, and run them autonomously while keeping users informed.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    NornsSupervisor                          │
│                  (Domain.GOAL routing)                      │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  GoalDomainSupervisor                       │
│            Routes to specialized workers                    │
└─────────────────────────────────────────────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│  Planning   │ │  Execution  │ │   Monitor   │ │Communication│
│   Worker    │ │   Worker    │ │   Worker    │ │   Worker    │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                   norns-executor                            │
│          (Background execution service)                     │
└─────────────────────────────────────────────────────────────┘

Database Tables

goals

Core goal definitions with status tracking.

Column	Type	Description
goal_id	UUID	Primary key
user_id	UUID	Owner
title	VARCHAR(500)	Goal title
description	TEXT	Detailed description
definition_of_done	TEXT	Success criteria
status	VARCHAR(30)	draft, planning, ready, active, paused, completed, failed, cancelled
priority	VARCHAR(5)	P1-P5
deadline	TIMESTAMPTZ	Optional deadline
schedule_cron	VARCHAR(100)	Recurring schedule
progress_pct	INTEGER	0-100

plan_items

Individual steps in a goal's execution plan.

Column	Type	Description
plan_item_id	UUID	Primary key
goal_id	UUID	Parent goal
title	VARCHAR(500)	Step title
action_type	VARCHAR(50)	tool_call, synthesis, decision_point, user_approval, external_wait
tool_name	VARCHAR(100)	Tool to execute
tool_params	JSONB	Tool parameters
depends_on	UUID[]	Prerequisite steps
status	VARCHAR(30)	pending, in_progress, completed, failed, skipped
execution_result	JSONB	Step output

background_goals

Goals queued for autonomous execution.

Column	Type	Description
goal_id	UUID	Primary key
user_id	UUID	Owner
title	VARCHAR(500)	Goal title
plan_steps	JSONB	Serialized plan
status	VARCHAR(50)	pending, claimed, running, completed, failed
executor_id	UUID	Claiming executor
context_snapshot	JSONB	User context at creation time
current_step	INTEGER	Progress tracking
percent_complete	NUMERIC(5,2)	0-100

Goal State Machine

draft → planning → ready → active ⟷ paused
                              ↓
                    completed | failed | cancelled

Workers

GoalPlanningWorker

Creates execution plans from goal definitions using LLM reasoning.

Capabilities:

• Breaks down goals into actionable steps
• Identifies tool calls needed
• Sets up step dependencies
• Estimates complexity

GoalExecutionWorker

Executes plan items step by step.

Action Types:

• tool_call - Execute a Norns tool
• synthesis - LLM reasoning/summarization
• decision_point - Make an autonomous decision
• user_approval - Pause and request user input
• external_wait - Wait for external event

GoalMonitorWorker

Tracks goal progress and handles state changes.

Capabilities:

• List active goals
• Check progress
• Pause/resume goals
• Cancel goals
• Detect blocked goals

GoalCommunicationWorker

Manages user communication.

Capabilities:

• Send Slack status updates
• Request approvals via Slack
• Update goal thread with progress
• Handle user replies

Available Tools

Tool	Description
create_goal	Create a new goal with title, description, and definition of done
query_goals	List goals by status, priority, or search
update_goal	Modify goal status, priority, or schedule
add_plan_step	Add a step to a goal's plan
get_goal_status	Get detailed goal progress
execute_goal_step	Manually trigger step execution
retry_plan_item	Retry a failed step

Background Executor Service

The norns-executor service runs as a separate container for crash isolation and scalability.

Components

ClaimManager

• Redis-based distributed locking
• 5-minute lease with 60-second heartbeat renewal
• Prevents duplicate execution across replicas

GoalConsumer

• Polls for pending goals
• Claims and executes goals
• Manages concurrency (default: 3 concurrent goals)

GoalRunner

• Executes plan steps sequentially
• Handles timeouts and failures
• Reports progress to database

Configuration

Environment Variable	Default	Description
EXECUTOR_CONCURRENCY	3	Max concurrent goals per instance
POLL_INTERVAL	5	Seconds between polling
EXECUTOR_MODEL	gpt-4o	LLM for reasoning steps

Endpoints

Endpoint	Description
GET /health	Health check with active goal count
GET /metrics	Prometheus-compatible metrics
GET /status	Detailed executor status

Usage Examples

Create a goal via Slack

@norns Create a goal to review all open PRs in the ravenhelm project.
Definition of done: All PRs have been reviewed and commented on.

Check goal progress

@norns What's the status of my active goals?

Pause a running goal

@norns Pause the PR review goal

Event Topics (Redpanda)

Topic	Description
norns.goals.created	New goal queued
norns.goals.execution	Goal claimed by executor
norns.goals.progress	Progress updates
norns.goals.completed	Completion events
norns.executor.heartbeat	Executor liveness

Approval Workflow

Certain actions require user approval before execution:

• File deletions
• Git push operations
• External API mutations
• Steps marked with requires_approval: true

When approval is needed:

1. Goal pauses at the approval step
2. Slack message sent to user with approve/reject buttons
3. User responds via Slack reaction or reply
4. Goal resumes or cancels based on response