### Install All Antfarm Workflows (Bash)

Source: https://context7.com/snarktank/antfarm/llms.txt

Installs all bundled workflows (feature-dev, bug-fix, security-audit), provisions agent workspaces, and starts the dashboard. This command is the primary entry point for setting up Antfarm.

```bash
# Install all bundled workflows
antfarm install

# Output:
# Installing 3 workflow(s)...
#   ✓ feature-dev
#   ✓ bug-fix
#   ✓ security-audit
# Done. Start a workflow with: antfarm workflow run <name> "your task"
# Dashboard started (PID 12345): http://localhost:3333
```

--------------------------------

### Install Antfarm CLI

Source: https://github.com/snarktank/antfarm/blob/main/landing/index.html

Installs the Antfarm command-line interface using a Go command. This is the initial step to get the Antfarm toolset on your system.

```bash
$ install github.com/snarktank/antfarm
```

--------------------------------

### Install and Uninstall Workflows

Source: https://context7.com/snarktank/antfarm/llms.txt

Manages the installation and uninstallation of workflows. This includes checking for active runs before uninstallation to prevent data loss.

```APIDOC
## Workflow Management

### Install Workflow

#### Description
Installs a specified workflow into the system.

#### Method
POST

#### Endpoint
/workflows/install

#### Parameters
##### Request Body
- **workflowId** (string) - Required - The ID of the workflow to install.

#### Request Example
```json
{
  "workflowId": "feature-dev"
}
```

#### Response (Install)
##### Success Response (200)
- **workflowId** (string) - The ID of the installed workflow.
- **workflowDir** (string) - The directory where the workflow is installed.

##### Response Example
```json
{
  "workflowId": "feature-dev",
  "workflowDir": "/path/to/workflows/feature-dev"
}
```

### Uninstall Workflow

#### Description
Uninstalls a specified workflow from the system. Requires checking for active runs first.

#### Method
POST

#### Endpoint
/workflows/uninstall

#### Parameters
##### Request Body
- **workflowId** (string) - Required - The ID of the workflow to uninstall.

#### Request Example
```json
{
  "workflowId": "feature-dev"
}
```

#### Response (Uninstall)
##### Success Response (200)
(No specific response body detailed, typically indicates success or failure)

### Check for Active Runs

#### Description
Checks if there are any active runs for a given workflow before uninstallation.

#### Method
GET

#### Endpoint
/workflows/{workflowId}/active-runs

#### Parameters
##### Path Parameters
- **workflowId** (string) - Required - The ID of the workflow to check.

#### Response (Active Runs)
##### Success Response (200)
- **activeRuns** (array) - A list of active run objects.
  - **id** (string) - The ID of the active run.
  - **task** (string) - The title of the task for the active run.

##### Response Example
```json
[
  {
    "id": "a1fdf573-8b2c-4d1e-9f3a-1234567890ab",
    "task": "Add user authentication with OAuth"
  }
]
```

### Uninstall All Workflows

#### Description
Uninstalls all managed workflows. Use with caution.

#### Method
POST

#### Endpoint
/workflows/uninstall-all

#### Response (Uninstall All)
##### Success Response (200)
(No specific response body detailed, typically indicates success or failure)
```

--------------------------------

### Install and Uninstall Antfarm Bundled Workflows

Source: https://github.com/snarktank/antfarm/blob/main/README.md

These bash commands manage the installation and uninstallation of Antfarm's bundled workflows. `antfarm install` sets up all necessary components. `antfarm uninstall` performs a full teardown, optionally with the `--force` flag to ensure complete removal of agents, crons, and the database. Ensure you have the necessary permissions to modify system components.

```bash
antfarm install
antfarm uninstall [--force]
```

--------------------------------

### Install Antfarm Workflow

Source: https://github.com/snarktank/antfarm/blob/main/landing/index.html

Installs a specific Antfarm workflow, such as 'feature-dev'. This command prepares the system to run the chosen automated task.

```bash
$ antfarm workflow install feature-dev
✓ Installed workflow: feature-dev
```

--------------------------------

### Install Single Antfarm Workflow (Bash)

Source: https://context7.com/snarktank/antfarm/llms.txt

Installs a specific workflow by its ID, creating necessary agent workspaces and registering agents within the OpenClaw configuration. This is useful for setting up individual workflows.

```bash
# Install feature-dev workflow
antfarm workflow install feature-dev

# Output:
# Installed workflow: feature-dev
# Agent crons will start when a run begins.
# Start with: antfarm workflow run feature-dev "your task"
```

--------------------------------

### Antfarm Workflow Management

Source: https://github.com/snarktank/antfarm/blob/main/README.md

Demonstrates commands for installing, running, and checking the status of Antfarm workflows. These commands are used to manage the execution of agent teams for specific tasks.

```bash
$ antfarm workflow install feature-dev
✓ Installed workflow: feature-dev

$ antfarm workflow run feature-dev "Add user authentication with OAuth"
Run: a1fdf573
Workflow: feature-dev
Status: running

$ antfarm workflow status "OAuth"
Run: a1fdf573
Workflow: feature-dev
Steps:
  [done   ] plan (planner)
  [done   ] setup (setup)
  [running] implement (developer)  Stories: 3/7 done
  [pending] verify (verifier)
  [pending] test (tester)
  [pending] pr (developer)
  [pending] review (reviewer)
```

--------------------------------

### Start, Stop, and Status for Antfarm Dashboard

Source: https://github.com/snarktank/antfarm/blob/main/README.md

These bash commands control the Antfarm dashboard service. The `dashboard` command starts the service, typically on port 3333. The `stop` command halts the service, and `status` checks if it is running. No external dependencies are required for these basic operations.

```bash
antfarm dashboard              # Start on port 3333
antfarm dashboard stop         # Stop
antfarm dashboard status       # Check status
```

--------------------------------

### Antfarm Agent Definition Example (YAML)

Source: https://github.com/snarktank/antfarm/blob/main/docs/creating-workflows.md

An example of an agent definition within a `workflow.yml` file. It specifies the agent's ID, name, role (which determines tool access), a description, and its workspace configuration, including base directory and files to be provisioned.

```yaml
agents:
  - id: my-agent            # Unique within this workflow
    name: My Agent           # Display name
    role: coding             # Controls tool access (see Agent Roles below)
    description: What it does.
    workspace:
      baseDir: agents/my-agent
      files:                 # Workspace files provisioned for this agent
        AGENTS.md: agents/my-agent/AGENTS.md
        SOUL.md: agents/my-agent/SOUL.md
        IDENTITY.md: agents/my-agent/IDENTITY.md
      skills:                # Optional: skills to install into the workspace
        - antfarm-workflows
```

--------------------------------

### Run Antfarm Workflow

Source: https://github.com/snarktank/antfarm/blob/main/landing/index.html

Executes an installed Antfarm workflow with a specific task description. The command initiates the agent team's process and provides a run ID for tracking.

```bash
$ antfarm workflow run feature-dev "Add user authentication with OAuth"
Run: a1fdf573
Workflow: feature-dev
Status: running
```

--------------------------------

### Antfarm Workflow Management (Bash)

Source: https://github.com/snarktank/antfarm/blob/main/skills/antfarm-workflows/SKILL.md

Commands for listing, installing, and uninstalling individual or all Antfarm workflows. These operations manage the definition and deployment of workflow pipelines.

```bash
# List available workflows
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow list

# Install/uninstall individual workflows
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow install <name>
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow uninstall <name>
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow uninstall --all [--force]
```

--------------------------------

### Manage Antfarm Dashboard (Bash)

Source: https://context7.com/snarktank/antfarm/llms.txt

Controls the Antfarm web dashboard, which is used for monitoring workflow runs and viewing agent output. Commands include starting the dashboard on a default or custom port, checking its status, and stopping it.

```bash
# Start dashboard (default port 3333)
antfarm dashboard

# Start on custom port
antfarm dashboard --port 4000

# Check status
antfarm dashboard status
# Output: Dashboard running (PID 12345)

# Stop dashboard
antfarm dashboard stop
```

--------------------------------

### Antfarm CLI Commands (Bash)

Source: https://github.com/snarktank/antfarm/blob/main/skills/antfarm-workflows/SKILL.md

Core commands for managing Antfarm workflows, including installation, uninstallation, running, status checks, and log viewing. These commands interact with the Antfarm CLI tool.

```bash
# Install all workflows (creates agents + starts dashboard)
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js install

# Full uninstall (workflows, agents, crons, DB, dashboard)
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js uninstall [--force]

# Start a run
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow run <workflow-id> "<detailed task with acceptance criteria>"

# Check a run
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow status "<task or run-id prefix>"

# List all runs
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow runs

# Resume a failed run from the failed step
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js workflow resume <run-id>

# View logs
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js logs [lines]

# Dashboard
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js dashboard [start] [--port N]
node ~/.openclaw/workspace/antfarm/dist/cli/cli.js dashboard stop
```

--------------------------------

### Injecting Progress Log into Prompts (YAML)

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

Example of how the 'progress' variable, containing the content of progress.txt, can be injected into agent prompts, specifically for verifier or tester steps.

```yaml
input: |
  ...
  PROGRESS LOG:
  {{progress}}
```

--------------------------------

### Antfarm Workflow Step Definition (YAML)

Source: https://github.com/snarktank/antfarm/blob/main/docs/creating-workflows.md

An example of a step definition in `workflow.yml`. It shows how to specify the step's ID, the agent responsible, the input prompt template (supporting variables like `{{task}}` and `{{prev_output}}`), the expected output string for success, and optional retry and failure handling.

```yaml
steps:
  - id: step-name           # Unique step identifier
    agent: agent-id          # Which agent handles this step
    input: |                 # Prompt template (supports {{variables}})
      Do the thing.
      {{task}}               # {{task}} is always the original task string
      {{prev_output}}        # Variables from prior steps (lowercased KEY names)

      Reply with:
      STATUS: done
      MY_KEY: value          # KEY: value pairs become variables for later steps
    expects: "STATUS: done"  # String the output must contain to count as success
    max_retries: 2           # How many times to retry on failure (optional)
    on_fail:                 # What to do when retries exhausted (optional)
      escalate_to: human     # Escalate to human
```

--------------------------------

### Minimal Antfarm Workflow Definition (YAML)

Source: https://github.com/snarktank/antfarm/blob/main/docs/creating-workflows.md

A basic example of a `workflow.yml` file defining two agents (researcher and writer) and two steps (research and write) to process a task. It shows how to define agents, their workspaces, and the sequence of steps with inputs and expected outputs.

```yaml
id: my-workflow
name: My Workflow
version: 1
description: What this workflow does.

agents:
  - id: researcher
    name: Researcher
    role: analysis
    description: Researches the topic and gathers information.
    workspace:
      baseDir: agents/researcher
      files:
        AGENTS.md: agents/researcher/AGENTS.md
        SOUL.md: agents/researcher/SOUL.md
        IDENTITY.md: agents/researcher/IDENTITY.md

  - id: writer
    name: Writer
    role: coding
    description: Writes content based on research.
    workspace:
      baseDir: agents/writer
      files:
        AGENTS.md: agents/writer/AGENTS.md
        SOUL.md: agents/writer/SOUL.md
        IDENTITY.md: agents/writer/IDENTITY.md

steps:
  - id: research
    agent: researcher
    input: |
      Research the following topic:
      {{task}}

      Reply with:
      STATUS: done
      FINDINGS: what you found
    expects: "STATUS: done"

  - id: write
    agent: writer
    input: |
      Write content based on these findings:
      {{findings}}

      Original request: {{task}}

      Reply with:
      STATUS: done
      OUTPUT: the final content
    expects: "STATUS: done"
```

--------------------------------

### Define Custom Antfarm Workflow (YAML)

Source: https://github.com/snarktank/antfarm/blob/main/landing/index.html

An example YAML configuration for defining a custom Antfarm workflow. It specifies the workflow ID, name, agents, and their respective steps and inputs.

```yaml
id: my-workflow
name: My Custom Workflow
agents:
  - id: researcher
    name: Researcher
    workspace:
      files:
        AGENTS.md: agents/researcher/AGENTS.md

steps:
  - id: research
    agent: researcher
    input: |
      Research {{task}} and report findings.
      Reply with STATUS: done and FINDINGS: ...
    expects: "STATUS: done"
```

--------------------------------

### Install and Uninstall Workflows with TypeScript

Source: https://context7.com/snarktank/antfarm/llms.txt

Manages the lifecycle of workflows within the Antfarm system. `installWorkflow` deploys a specified workflow, returning its ID and directory. `uninstallWorkflow` removes a specific workflow, while `uninstallAllWorkflows` performs a complete cleanup. `checkActiveRuns` is a crucial safety function to prevent uninstallation if active runs exist for a workflow.

```typescript
import { installWorkflow } from "./src/installer/install.js";
import { uninstallWorkflow, uninstallAllWorkflows, checkActiveRuns } from "./src/installer/uninstall.js";

// Install a workflow
const result = await installWorkflow({ workflowId: "feature-dev" });
console.log(`Installed: ${result.workflowId}`);
console.log(`Directory: ${result.workflowDir}`);

// Check for active runs before uninstall
const activeRuns = checkActiveRuns("feature-dev");
if (activeRuns.length > 0) {
  console.log(`Cannot uninstall: ${activeRuns.length} active runs`);
  for (const run of activeRuns) {
    console.log(`  - ${run.id}: ${run.task}`);
  }
} else {
  await uninstallWorkflow({ workflowId: "feature-dev" });
}

// Full cleanup
await uninstallAllWorkflows();
```

--------------------------------

### Manage Antfarm Workflow Runs and Status

Source: https://github.com/snarktank/antfarm/blob/main/README.md

This set of bash commands allows for the management of workflows within Antfarm. You can start a specific task within a workflow run, check the status of runs using a query, list all active runs, resume a failed run, or list and install/uninstall available workflows. These commands interact with the Antfarm's internal state and may require a running Antfarm instance.

```bash
antfarm workflow run <id> <task>
antfarm workflow status <query>
antfarm workflow runs
antfarm workflow resume <run-id>
antfarm workflow list
antfarm workflow install <id>
antfarm workflow uninstall <id>
```

--------------------------------

### Run Antfarm Workflow (Bash)

Source: https://context7.com/snarktank/antfarm/llms.txt

Starts a new workflow run with a given task description. The command returns a unique run ID that can be used for tracking the workflow's progress. Supports optional webhook notifications.

```bash
# Start a feature development run
antfarm workflow run feature-dev "Add user authentication with OAuth"

# Output:
# Run: a1fdf573-8b2c-4d1e-9f3a-1234567890ab
# Workflow: feature-dev
# Task: Add user authentication with OAuth
# Status: running

# With webhook notification
antfarm workflow run feature-dev "Add dark mode" --notify-url https://hooks.example.com/notify
```

--------------------------------

### Output Format Summary

Source: https://github.com/snarktank/antfarm/blob/main/workflows/security-audit/agents/prioritizer/AGENTS.md

Illustrates the overall output format of the Prioritizer Agent, including status, a numbered fix plan, counts of different severity levels, and the final STORIES_JSON array.

```text
STATUS: done
FIX_PLAN:
1. [CRITICAL] fix-001: Parameterize SQL queries in user search
2. [HIGH] fix-002: Remove hardcoded API keys from source
...
CRITICAL_COUNT: 2
HIGH_COUNT: 3
DEFERRED: 5 low-severity issues deferred (missing rate limiting, verbose error messages, ...)
STORIES_JSON: [ ... ]
```

--------------------------------

### Get All Stories for a Run (TypeScript)

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

A TypeScript function to retrieve all stories associated with a specific run ID. The stories are returned in the order of their `story_index`.

```typescript
function getStories(runId: string): Story[] {
  // Return all stories for a run, ordered by story_index
}
```

--------------------------------

### View Pull Request Differences using GitHub CLI

Source: https://github.com/snarktank/antfarm/blob/main/workflows/feature-dev/agents/reviewer/AGENTS.md

This command displays the actual code changes introduced by a pull request. It is crucial for examining the diff and understanding the modifications made.

```bash
gh pr diff <url>
```

--------------------------------

### Submit a Review with Comments using GitHub CLI

Source: https://github.com/snarktank/antfarm/blob/main/workflows/feature-dev/agents/reviewer/AGENTS.md

This command is used to submit a review for a pull request, including comments. It allows for specifying the review action (e.g., `--comment`) and the review body.

```bash
gh pr review <url> --comment --body "..."
```

--------------------------------

### View Pull Request Details using GitHub CLI

Source: https://github.com/snarktank/antfarm/blob/main/workflows/feature-dev/agents/reviewer/AGENTS.md

This command allows the reviewer to view the details of a pull request. It is a fundamental step in understanding the context of the changes being reviewed.

```bash
gh pr view <url>
```

--------------------------------

### Get Current Story for a Step (TypeScript)

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

A TypeScript function to retrieve the story that is currently being processed by a loop step. It utilizes the `step.current_story_id` to fetch the relevant story.

```typescript
function getCurrentStory(stepId: string): Story | null {
  // Get the story currently being worked on by a loop step
  // Uses step.current_story_id
}
```

--------------------------------

### Agent-facing API for Claiming and Completing Steps

Source: https://context7.com/snarktank/antfarm/llms.txt

Provides endpoints for agents to claim pending work items (steps) and report their completion or failure. This is crucial for the execution flow of workflows.

```APIDOC
## Agent Step Operations

### Claim a Step

#### Description
Claims the next available step for a given agent and workflow.

#### Method
POST

#### Endpoint
/steps/claim

#### Parameters
##### Request Body
- **agentId** (string) - Required - The ID of the agent claiming the step.
- **workflowId** (string) - Required - The ID of the workflow the step belongs to.

#### Request Example
```json
{
  "agentId": "developer",
  "workflowId": "feature-dev"
}
```

#### Response (Claim)
##### Success Response (200)
- **found** (boolean) - True if a step was found and claimed, false otherwise.
- **stepId** (string) - The ID of the claimed step (if found).
- **runId** (string) - The ID of the run the step belongs to (if found).
- **resolvedInput** (string) - The input for the claimed step (if found).

##### Response Example (Found)
```json
{
  "found": true,
  "stepId": "step-123",
  "runId": "run-abc",
  "resolvedInput": "{\"code\": \"...\"}"
}
```

##### Response Example (Not Found)
```json
{
  "found": false
}
```

### Complete a Step

#### Description
Marks a claimed step as completed with a specific output.

#### Method
POST

#### Endpoint
/steps/complete

#### Parameters
##### Request Body
- **stepId** (string) - Required - The ID of the step to complete.
- **output** (string) - Required - The output produced by the step.

#### Request Example
```json
{
  "stepId": "step-123",
  "output": "STATUS: done\nCHANGES: Implemented OAuth provider integration"
}
```

#### Response (Complete)
##### Success Response (200)
- **advanced** (boolean) - True if the workflow advanced to the next step.
- **runCompleted** (boolean) - True if the run has now completed.

##### Response Example
```json
{
  "advanced": true,
  "runCompleted": false
}
```

### Fail a Step

#### Description
Marks a claimed step as failed with an error message.

#### Method
POST

#### Endpoint
/steps/fail

#### Parameters
##### Request Body
- **stepId** (string) - Required - The ID of the step to fail.
- **errorMessage** (string) - Required - The error message describing the failure.

#### Request Example
```json
{
  "stepId": "step-123",
  "errorMessage": "TypeError: Cannot read property 'code' of undefined"
}
```

#### Response (Fail)
##### Success Response (200)
- **retrying** (boolean) - True if the step is configured to retry.
- **runFailed** (boolean) - True if the entire run has now failed.

##### Response Example
```json
{
  "retrying": true,
  "runFailed": false
}
```

### Query Stories for a Run

#### Description
Retrieves a list of stories (sub-tasks) associated with a specific workflow run.

#### Method
GET

#### Endpoint
/runs/{runId}/stories

#### Parameters
##### Path Parameters
- **runId** (string) - Required - The ID of the workflow run.

#### Response (Stories)
##### Success Response (200)
- **stories** (array) - A list of story objects.
  - **storyId** (string) - The ID of the story.
  - **status** (string) - The status of the story (e.g., "completed", "failed").
  - **title** (string) - The title of the story.
  - **retryCount** (integer) - The number of times the story has been retried.
  - **maxRetries** (integer) - The maximum allowed retries for the story.

##### Response Example
```json
[
  {
    "storyId": "story-001",
    "status": "completed",
    "title": "Implement OAuth endpoint",
    "retryCount": 0,
    "maxRetries": 3
  },
  {
    "storyId": "story-002",
    "status": "failed",
    "title": "Test OAuth flow",
    "retryCount": 1,
    "maxRetries": 3
  }
]
```
```

--------------------------------

### Run a Workflow Programmatically

Source: https://context7.com/snarktank/antfarm/llms.txt

Starts a workflow run from TypeScript code. This endpoint allows you to initiate a new workflow execution with specified parameters and receive a run ID upon success.

```APIDOC
## POST /workflows/run

### Description
Starts a workflow run programmatically.

### Method
POST

### Endpoint
/workflows/run

### Parameters
#### Request Body
- **workflowId** (string) - Required - The ID of the workflow to run.
- **taskTitle** (string) - Required - A title for the workflow run.
- **notifyUrl** (string) - Optional - A URL to notify upon completion.

### Request Example
```json
{
  "workflowId": "feature-dev",
  "taskTitle": "Add user authentication with OAuth",
  "notifyUrl": "https://hooks.example.com/workflow-complete"
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the started run.
- **workflowId** (string) - The ID of the workflow that was run.
- **task** (string) - The title of the workflow run.
- **status** (string) - The initial status of the run (e.g., "running").

#### Response Example
```json
{
  "id": "a1fdf573-8b2c-4d1e-9f3a-1234567890ab",
  "workflowId": "feature-dev",
  "task": "Add user authentication with OAuth",
  "status": "running"
}
```
```

--------------------------------

### List Stories for a Run (CLI)

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

A new command-line interface command to list all stories associated with a specific run ID. Displays story ID, status, and description.

```bash
$ antfarm step stories abc123
US-001 [done]    Add status field to database
US-002 [done]    Display status badge on task cards  
US-003 [running] Add status toggle to task list rows
US-004 [pending] Filter tasks by status
```

--------------------------------

### Path Traversal Prevention Example (TypeScript)

Source: https://github.com/snarktank/antfarm/blob/main/workflows/security-audit/agents/fixer/AGENTS.md

Shows how to prevent directory traversal vulnerabilities by sanitizing user-provided filenames. It replaces potentially dangerous path constructions with a safer approach using `path.basename`.

```typescript
// BAD: fs.readFile(path.join(uploadDir, userFilename))
// GOOD: const safe = path.basename(userFilename); fs.readFile(path.join(uploadDir, safe))
```

--------------------------------

### XSS Mitigation Example (TypeScript)

Source: https://github.com/snarktank/antfarm/blob/main/workflows/security-audit/agents/fixer/AGENTS.md

Illustrates methods to prevent Cross-Site Scripting (XSS) attacks. It shows replacing direct `innerHTML` assignment with `textContent` or using a sanitization library like DOMPurify.

```typescript
// BAD: element.innerHTML = userInput
// GOOD: element.textContent = userInput
// Or use a sanitizer: DOMPurify.sanitize(userInput)
```

--------------------------------

### SQL Injection Fix Example (TypeScript)

Source: https://github.com/snarktank/antfarm/blob/main/workflows/security-audit/agents/fixer/AGENTS.md

Demonstrates the transformation from a vulnerable SQL query using string concatenation to a secure parameterized query. This prevents attackers from injecting malicious SQL code.

```typescript
// BAD: `SELECT * FROM users WHERE name = '${input}'`
// GOOD: `SELECT * FROM users WHERE name = $1`, [input]
```

--------------------------------

### Story Object Format (JSON)

Source: https://github.com/snarktank/antfarm/blob/main/workflows/security-audit/agents/prioritizer/AGENTS.md

Defines the structure of a single fix story within the STORIES_JSON output. Includes fields for ID, title, description, acceptance criteria, and severity.

```json
{
  "id": "fix-001",
  "title": "Parameterize SQL queries in user search",
  "description": "SQL injection in src/db/users.ts:45 and src/db/search.ts:23. Both use string concatenation for user input in queries. Replace with parameterized queries.",
  "acceptance_criteria": [
    "All SQL queries use parameterized inputs, no string concatenation",
    "Regression test confirms SQL injection payload is safely handled",
    "All existing tests pass",
    "Typecheck passes"
  ],
  "severity": "critical"
}
```

--------------------------------

### Planner Agent Output Format (JSON)

Source: https://github.com/snarktank/antfarm/blob/main/workflows/feature-dev/agents/planner/AGENTS.md

This snippet demonstrates the expected JSON output format for the Planner Agent, detailing the structure for user stories, including IDs, titles, descriptions, and acceptance criteria. This format is consumed by a pipeline for tracking story records.

```json
{
  "STATUS": "done",
  "REPO": "/path/to/repo",
  "BRANCH": "feature-branch-name",
  "STORIES_JSON": [
    {
      "id": "US-001",
      "title": "Short descriptive title",
      "description": "As a developer, I need to... so that...\n\nImplementation notes:\n- Detail 1\n- Detail 2",
      "acceptanceCriteria": [
        "Specific verifiable criterion 1",
        "Specific verifiable criterion 2",
        "Tests for [feature] pass",
        "Typecheck passes"
      ]
    },
    {
      "id": "US-002",
      "title": "...",
      "description": "...",
      "acceptanceCriteria": ["...", "Typecheck passes"]
    }
  ]
}
```

--------------------------------

### Update SKILL.md Documentation

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

Updates the main SKILL.md file for the Antfarm workflows. This includes documenting the newly introduced pipeline structure, updating the command-line interface (CLI) reference, providing an example interaction, and noting the change to 5-minute cron cycles.

```markdown
# Antfarm Workflows Skill

## Pipeline Overview

This skill orchestrates feature development workflows using a multi-agent system. The pipeline now includes a planner agent for task decomposition and story generation, followed by developer and verifier agents that operate on a per-story basis.

## CLI Reference

- `antfarm workflow install <workflow-name>`
- `antfarm workflow uninstall <workflow-name>`
- `antfarm workflow status <run-id>`
- `antfarm step stories <run-id>` (New command to view stories for a run)

## Example Interaction

```bash
antfarm workflow install feature-dev
# ... observe planner generating stories ...
antfarm workflow status <run-id>
```

## Notes

- Cron jobs are now configured to run every 5 minutes (300,000 ms).
```

--------------------------------

### Control Antfarm Dashboard Daemon

Source: https://context7.com/snarktank/antfarm/llms.txt

Manages the Antfarm web dashboard daemon by starting, stopping, and checking its status. It requires the 'daemonctl' module for these operations. The function returns status information including whether the daemon is running and its process ID (PID).

```typescript
import { startDaemon, stopDaemon, getDaemonStatus, isRunning } from "./src/server/daemonctl.js";

// Check if dashboard is running
const status = isRunning();
console.log(`Dashboard running: ${status.running}`);

if (!status.running) {
  // Start dashboard on port 3333
  const daemon = await startDaemon(3333);
  console.log(`Started dashboard (PID ${daemon.pid})`);
  console.log(`URL: http://localhost:${daemon.port}`);
}

// Get detailed status
const details = getDaemonStatus();
if (details?.running) {
  console.log(`PID: ${details.pid}`);
}

// Stop dashboard
if (stopDaemon()) {
  console.log("Dashboard stopped");
}
```

--------------------------------

### Get Active Step ID in JavaScript

Source: https://github.com/snarktank/antfarm/blob/main/src/server/index.html

This function determines the active step ID for a given run. It checks for steps that are not 'done' or 'skipped'. If no active steps are found, it returns the step ID of the last step. It is used to determine the current state of a run.

```javascript
function getActiveStepId(run) {
  if (!run.steps || !run.steps.length) return null;
  const active = run.steps.find(s => s.status !== 'done' && s.status !== 'skipped');
  return active ? active.step_id : run.steps[run.steps.length - 1].step_id;
}
```

--------------------------------

### Archive Run Progress in TypeScript

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

Implements a function to archive the progress of a completed workflow run. It finds the agent workspace, creates a timestamped archive directory, copies the progress.txt file, and then truncates the original. This function requires a helper to get the agent workspace path.

```typescript
function archiveRunProgress(runId: string) {
  const workspacePath = getAgentWorkspacePath(); // Assuming this helper exists
  const archivePath = `${workspacePath}/archive/${runId}`;
  // Create archive directory if it doesn't exist
  // Copy progress.txt to archivePath
  // Truncate original progress.txt
}
```

--------------------------------

### Verify State Machine Transitions

Source: https://github.com/snarktank/antfarm/blob/main/docs/design-story-loop.md

Describes the state transitions for the implement-verify mini-loop in the agent workflow. It outlines states like 'pending', 'running', and 'waiting' for 'implement' and 'verify' steps, and story statuses. It covers both successful completion and failure paths, including retry mechanisms.

```plaintext
INITIAL STATE (after planner completes):
  implement step: pending
  verify step: waiting
  stories: US-001=pending, US-002=pending, US-003=pending

DEVELOPER CLAIMS (claimStep for developer agent):
  implement step: running, current_story_id=US-001
  US-001: running

DEVELOPER COMPLETES (completeStep for implement):
  implement step: running (stays running, waiting for verify)
  verify step: pending
  US-001: done (output saved)
  context: { changes: "...", verify_feedback: "" }

VERIFIER CLAIMS (claimStep for verifier agent):
  verify step: running

VERIFIER PASSES (completeStep for verify, STATUS=done):
  verify step: waiting (reset for next story)
  implement step: pending (ready for next story)
  US-001: done (confirmed)

DEVELOPER CLAIMS NEXT (claimStep for developer agent):
  implement step: running, current_story_id=US-002
  US-002: running

... (repeat until all stories done) ...

LAST STORY VERIFIED:
  verify step: done
  implement step: done
  → advance to test step

--- FAILURE PATH ---

VERIFIER FAILS (completeStep for verify, STATUS=retry):
  verify step: waiting (reset)
  implement step: pending (developer retries)
  US-001: pending (retry_count incremented)
  context: { verify_feedback: "ISSUES: ..." }
```