> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useorgx.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Recipes

> Common multi-tool workflows with exact tool sequences and expected responses.

These recipes show common multi-tool workflows. Each includes the exact tool sequence, expected responses, and decision points.

## Questions This Page Answers

* What exact tool sequence should an operator run for common workflows?
* Which calls prove system health before dispatching high-value work?
* How do trust, autonomous sessions, and ROI queries connect in practice?

***

## Recipe 1: First Connection Handshake

Verify auth, discover workspace, and get org context.

<Steps>
  <Step title="Verify Connection">
    ```json theme={"dark"}
    { "tool": "workspace", "args": { "action": "get" } }
    ```

    **Expected**: `{ "workspace_id": "ws_...", "name": "My Workspace" }`

    If you get `workspace_not_set`, call `workspace` with `action=list` first, then `workspace` with `action=set`.
  </Step>

  <Step title="Get Org Overview">
    ```json theme={"dark"}
    { "tool": "orgx_recommend", "args": { "view": "summary" } }
    ```

    **Expected**: Summary with `active_initiatives`, `total_tasks`, health indicators.
  </Step>

  <Step title="Check Pending Work">
    ```json theme={"dark"}
    {
      "tool": "orgx_search",
      "args": { "type": "decision", "status": "pending", "limit": 5 }
    }
    ```

    **Expected**: `entities` array of pending decisions with `id`, `title`, `status`, and `urgency`.
  </Step>
</Steps>

***

## Recipe 2: Create and Launch an Initiative

Build a full initiative hierarchy and start execution.

<Steps>
  <Step title="Scaffold the Initiative">
    ```json theme={"dark"}
    {
      "tool": "scaffold_initiative",
      "args": {
        "title": "Q1 Product Launch",
        "summary": "Ship new dashboard features by end of quarter",
        "workstreams": [
          {
            "title": "Frontend Development",
            "tasks": [
              { "title": "Build hero section" },
              { "title": "Implement responsive layouts" },
              { "title": "A/B test CTAs" }
            ]
          },
          {
            "title": "Documentation",
            "tasks": [
              { "title": "Update API docs" },
              { "title": "Create migration guide" }
            ]
          }
        ],
        "milestones": [
          { "title": "Beta launch", "due_date": "2026-04-01" },
          { "title": "GA release", "due_date": "2026-06-01" }
        ]
      }
    }
    ```

    **Expected**: Returns initiative ID, workstream IDs, task IDs. Auto-launches by default.
  </Step>

  <Step title="Check Health">
    ```json theme={"dark"}
    {
      "tool": "orgx_recommend",
      "args": { "initiative_id": "<returned_id>" }
    }
    ```

    **Expected**: `health_score`, milestone progress, blockers.
  </Step>

  <Step title="Browse Created Entities">
    ```json theme={"dark"}
    {
      "tool": "orgx_search",
      "args": { "type": "task", "parent_id": "<workstream_id>", "limit": 20 }
    }
    ```

    **Expected**: List of tasks with status, titles, and IDs.
  </Step>
</Steps>

***

## Recipe 3: Decision Triage

Review and process pending decisions efficiently.

<Steps>
  <Step title="Fetch Pending Decisions">
    ```json theme={"dark"}
    {
      "tool": "orgx_search",
      "args": { "type": "decision", "status": "pending", "limit": 10 }
    }
    ```

    **Expected**: Pending decisions. Filter the results client-side for critical items if you want the strictest triage queue.
  </Step>

  <Step title="Get Context for a Decision">
    Use `orgx_search` to understand the background:

    ```json theme={"dark"}
    {
      "tool": "orgx_search",
      "args": {
        "query": "<decision title or topic>",
        "scope": "decisions",
        "limit": 5
      }
    }
    ```
  </Step>

  <Step title="Approve or Reject">
    ```json theme={"dark"}
    {
      "tool": "orgx_decide",
      "args": {
        "decision_id": "dec_...",
        "note": "Approved — budget within limits"
      }
    }
    ```

    Or reject with feedback:

    ```json theme={"dark"}
    {
      "tool": "orgx_decide",
      "args": {
        "decision_id": "dec_...",
        "reason": "Budget too high — reduce by 20%"
      }
    }
    ```
  </Step>
</Steps>

***

## Recipe 4: Overnight Autonomous Session

Set up a bounded autonomous session and review results the next morning.

<Steps>
  <Step title="Check Trust Levels">
    ```json theme={"dark"}
    {
      "tool": "get_my_trust_context",
      "args": { "workspace_id": "ws_...", "agent_type": "engineering-agent" }
    }
    ```

    **Expected**: Trust levels per capability. Only `autonomous` capabilities will execute without approval.
  </Step>

  <Step title="Start Session">
    ```json theme={"dark"}
    {
      "tool": "start_autonomous_session",
      "args": {
        "workspace_id": "ws_...",
        "session_type": "overnight",
        "max_cost_usd": 5.00,
        "max_receipts": 50
      }
    }
    ```

    **Expected**: Session ID, status `active`.
  </Step>

  <Step title="Morning Review">
    ```json theme={"dark"}
    {
      "tool": "orgx_recommend",
      "args": { "workspace_id": "ws_..." }
    }
    ```

    **Expected**: Curated receipts, exceptions that need attention, ROI delta.
  </Step>

  <Step title="Check ROI">
    ```json theme={"dark"}
    {
      "tool": "orgx_recommend",
      "args": {}
    }
    ```

    **Expected**: Session summary, cost, completed work, pending decisions, and artifacts from the latest autonomous run.
  </Step>
</Steps>

***

## Recipe 5: Planning Session

Use collaborative planning tools to improve an initiative plan.

<Steps>
  <Step title="Start Planning">
    ```json theme={"dark"}
    {
      "tool": "orgx_plan",
      "args": {
        "initiative_id": "init_...",
        "focus": "Refine Q1 launch workstreams"
      }
    }
    ```
  </Step>

  <Step title="Get AI Suggestions">
    ```json theme={"dark"}
    {
      "tool": "orgx_plan",
      "args": { "session_id": "<session_id>" }
    }
    ```

    **Expected**: AI-generated suggestions for gaps, risks, and improvements.
  </Step>

  <Step title="Record Edits">
    ```json theme={"dark"}
    {
      "tool": "orgx_plan",
      "args": {
        "session_id": "<session_id>",
        "edit_type": "add_workstream",
        "description": "Added QA workstream for regression testing"
      }
    }
    ```
  </Step>

  <Step title="Complete Planning">
    ```json theme={"dark"}
    {
      "tool": "orgx_plan",
      "args": { "session_id": "<session_id>" }
    }
    ```
  </Step>
</Steps>

***

## Recipe 6: Entity CRUD Lifecycle

Manage the complete lifecycle of an entity — create, update, comment, complete, and verify.

<Steps>
  <Step title="Create an Entity">
    ```json theme={"dark"}
    {
      "tool": "orgx_write",
      "args": {
        "type": "task",
        "title": "Implement OAuth2 token refresh",
        "parent_id": "ws_abc123"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "id": "tsk_abc123",
      "type": "task",
      "title": "Implement OAuth2 token refresh",
      "status": "pending",
      "parent_id": "ws_abc123",
      "created_at": "2026-02-26T10:00:00Z"
    }
    ```
  </Step>

  <Step title="Update the Entity">
    ```json theme={"dark"}
    {
      "tool": "update_entity",
      "args": {
        "entity_id": "tsk_abc123",
        "description": "Handle silent token refresh using refresh_token grant. Must support token rotation and revocation."
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "id": "tsk_abc123",
      "title": "Implement OAuth2 token refresh",
      "description": "Handle silent token refresh using refresh_token grant. Must support token rotation and revocation.",
      "status": "pending",
      "updated_at": "2026-02-26T10:02:00Z"
    }
    ```
  </Step>

  <Step title="Comment on It">
    ```json theme={"dark"}
    {
      "tool": "comment_on_entity",
      "args": {
        "entity_id": "tsk_abc123",
        "body": "Spike complete — refresh window should be 5 minutes before expiry. See design doc for sequence diagram."
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "comment_id": "cmt_def456",
      "entity_id": "tsk_abc123",
      "body": "Spike complete — refresh window should be 5 minutes before expiry. See design doc for sequence diagram.",
      "created_at": "2026-02-26T10:15:00Z"
    }
    ```
  </Step>

  <Step title="Complete the Entity">
    ```json theme={"dark"}
    {
      "tool": "orgx_act",
      "args": {
        "entity_id": "tsk_abc123",
        "action": "complete"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "id": "tsk_abc123",
      "status": "completed",
      "completed_at": "2026-02-26T14:30:00Z"
    }
    ```
  </Step>

  <Step title="Verify Parent Completion">
    ```json theme={"dark"}
    {
      "tool": "orgx_act",
      "args": {
        "dry_run": true,
        "entity_id": "ws_abc123"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "entity_id": "ws_abc123",
      "type": "workstream",
      "total_children": 5,
      "completed_children": 3,
      "completion_pct": 60,
      "is_complete": false,
      "remaining": ["tsk_ghi789", "tsk_jkl012"]
    }
    ```

    If `is_complete` is `true`, the parent workstream can be marked complete as well.
  </Step>
</Steps>

***

## Recipe 7: Scoring & Queue Management

Manage the Next Up Queue — score items, inspect signals, pin priorities, tune weights, and skip blockers.

<Steps>
  <Step title="Score the Queue">
    ```json theme={"dark"}
    {
      "tool": "orgx_recommend",
      "args": {
        "entity_type": "workspace",
        "entity_id": "default"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "recommendation": {
        "action": "orgx_decide",
        "target_id": "dec_abc123",
        "reasoning": "Campaign brief matches brand guidelines and has strong CTAs.",
        "confidence": 0.92
      }
    }
    ```
  </Step>

  <Step title="Get Scoring Signals">
    ```json theme={"dark"}
    {
      "tool": "get_scoring_signals",
      "args": {
        "entity_id": "tsk_q01aaa"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "entity_id": "tsk_q01aaa",
      "signals": {
        "critical_bug": { "weight": 1.5, "value": true, "contribution": 30 },
        "blocking_release": { "weight": 1.3, "value": true, "contribution": 26 },
        "recency": { "weight": 1.0, "value": 0.9, "contribution": 18 },
        "effort_estimate": { "weight": 0.8, "value": "small", "contribution": 20 }
      },
      "total_score": 94
    }
    ```
  </Step>

  <Step title="Pin a High-Priority Item">
    ```json theme={"dark"}
    {
      "tool": "pin_queue_item",
      "args": {
        "entity_id": "tsk_q01aaa",
        "reason": "P0 auth regression — must ship before release cut"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "entity_id": "tsk_q01aaa",
      "pinned": true,
      "reason": "P0 auth regression — must ship before release cut",
      "pinned_at": "2026-02-26T09:05:00Z"
    }
    ```

    Pinned items always appear at the top of the queue regardless of score.
  </Step>

  <Step title="Adjust Scoring Weights">
    ```json theme={"dark"}
    {
      "tool": "set_scoring_weights",
      "args": {
        "weights": {
          "critical_bug": 2.0,
          "blocking_release": 1.5,
          "user_impact": 1.2,
          "tech_debt": 0.5,
          "recency": 1.0
        }
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "updated": true,
      "weights": {
        "critical_bug": 2.0,
        "blocking_release": 1.5,
        "user_impact": 1.2,
        "tech_debt": 0.5,
        "recency": 1.0
      },
      "note": "The next orgx_recommend call will use these updated scoring weights"
    }
    ```
  </Step>

  <Step title="Skip a Blocked Workstream">
    ```json theme={"dark"}
    {
      "tool": "skip_workstream",
      "args": {
        "workstream_id": "ws_blocked99",
        "reason": "Waiting on third-party API access — ETA next week"
      }
    }
    ```

    **Expected**:

    ```json theme={"dark"}
    {
      "workstream_id": "ws_blocked99",
      "status": "skipped",
      "reason": "Waiting on third-party API access — ETA next week",
      "skipped_at": "2026-02-26T09:10:00Z",
      "tasks_dequeued": 4
    }
    ```

    Skipped workstreams and their tasks are removed from the queue until the workstream is resumed.
  </Step>
</Steps>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Failure Playbooks" icon="shield" href="/docs/agent-ops/failure-playbooks">
    Handle errors gracefully.
  </Card>

  <Card title="Tool Profiles" icon="users" href="/docs/agent-ops/tool-profiles">
    Reduce schema overhead with role-based profiles.
  </Card>
</CardGroup>