Agent Story: Light | HAP Analysis

When to Use Light vs. Full

Use Light when...	Use Full when...
Early-stage design / ideation	Implementation-ready specification
Simple, single-purpose agents	Multi-skill, complex workflows
Quick communication with stakeholders	Detailed handoff to engineering
Agents with straightforward behavior	Agents with nuanced human collaboration

The Format

1 Core Story (Required)

Core Format

AGENT STORY: [ID]

As [Agent Role],
triggered by [Event],
I [Action/Goal],
so that [Outcome/Value].

Autonomy: [Full | Supervised | Collaborative | Directed]

2 Essential Annotations (Include as needed)

# What activates the agent
trigger:
  type: [message | resource_change | schedule | cascade | manual]
  source: [Where the trigger comes from]

# What the agent knows how to do (at least one required)
skills:
  - name: [Skill Name]
    does: [What this skill accomplishes - one line]
    tools: [Tools used, if any]

# What external resources the agent uses
tools:
  - [Tool/MCP Server Name]: [Purpose]

# How humans are involved
human_role: [in_the_loop | on_the_loop | out_of_loop]
escalates_when: [Condition that requires human involvement]

# How we know it's working
success: [Primary measurable outcome]
guardrails:
  - [Thing the agent must NEVER do]

Complete Example

Core Story

AGENT STORY: EXPENSE-001

As an Expense Report Agent,
triggered by employee expense submission,
I validate receipts, check policy compliance, and route for approval,
so that employees are reimbursed quickly and accurately.

Autonomy: Supervised

trigger:
  type: message
  source: Expense management system

skills:
  - name: Receipt Validation
    does: Extracts and verifies receipt data against submission
    tools: [Document Analysis MCP]

  - name: Policy Compliance
    does: Checks expenses against company policy limits and categories
    tools: [Policy Database]

  - name: Approval Routing
    does: Determines correct approver based on amount and department
    tools: [Org Chart API]

tools:
  - Document Analysis MCP: Extract data from receipt images
  - Policy Database: Company expense policies and limits
  - Org Chart API: Manager lookup and approval chains

human_role: on_the_loop
escalates_when: Expense exceeds $500 or policy exception requested

success: 90% of compliant expenses auto-processed within 4 hours
guardrails:
  - Never approve expenses exceeding policy without human review
  - Never expose employee financial data in logs

Graduating to Full

When your Light story needs more detail, expand these mappings:

Light Element	Full Expansion
trigger.type + source	Full `trigger:` block with conditions and examples
skills[].does	`proficiencies[]`, `quality_bar`, `acquired`
tools[]	`permissions`, `conditions`
human_role + escalates_when	`human_interaction:` with checkpoints, timeouts
success	`acceptance.functional[]` + `acceptance.quality[]`
guardrails	`acceptance.guardrails[]`
(not in Light)	`behavior:` stages/transitions, `memory:`, `reasoning:`, `collaboration:`

View Full Format

Quick Reference

AGENT STORY LIGHT - QUICK REFERENCE

CORE (Always include)
  - Role: What the agent is
  - Trigger: What activates it
  - Action: What it does
  - Outcome: Why it matters
  - Autonomy: Full|Supervised|Collaborative|Directed

ESSENTIALS (Include as needed)
  - trigger: type + source
  - skills: name + does + tools
  - tools: name + purpose
  - human_role + escalates_when
  - success + guardrails

AUTONOMY LEVELS
  - Full: No human involvement during execution
  - Supervised: Human monitors, intervenes on exception
  - Collaborative: Human confirms agent proposals
  - Directed: Human guides each step

WHEN TO GRADUATE TO FULL
  - Need to specify workflow stages or state transitions
  - Agent has persistent memory or learning loops
  - Complex multi-agent collaboration
  - Detailed reasoning logic required