# Asta Flows

> Plan and execute autonomous research as a graph of typed tasks tracked in beads. Use when working from a mission.md to drive multi-step research with explicit dependencies and structured outputs.

- Skill: `allenai/asta-flows` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add allenai/asta-flows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/allenai/asta-flows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: allenai (https://skillmd.com/u/allenai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/allenai/asta-flows

---


# Asta Flows

Models a research session as a beads epic. Each unit of work is a typed sub-issue whose `metadata.research_step.output` matches a JSON schema in `assets/schemas.yaml`.

This skill is a **router**. Inspect the working directory and the user's request, pick one workflow, then read its `.md` file in `workflows/` and follow it. Do not execute a workflow from memory — always open the file first.

## Setup

There are no hard preconditions. If `mission.md` does not exist, the **brainstorm** workflow will help the user draft one.

Installing `bd` and `jq`, running `bd init`, and verifying `scripts/summary-check.sh` works are the responsibility of the **init** workflow. Once `init` has run, subsequent workflows assume the environment is ready.

## Files

| Path | Role |
|---|---|
| `mission.md` | Input. The research task. |
| `.beads/` | Source of truth for state. |
| `summary.md` | Derived view of the session, regenerated by **update-summary**. Beads is the source of truth; this file is just a digest for humans and for **brainstorm**. Frontmatter `beads_snapshot` records the state it was rendered from. |
| `background_knowledge.txt` | Optional. Long-form context referenced from issue metadata via `summary_path`. |

## Workflows

| Name | Purpose | Detailed instructions |
|---|---|---|
| **brainstorm** | Default. Conversational exploration of current state; drafts/refines `mission.md`; hands off to other workflows when the user is ready to act. | `workflows/brainstorm.md` |
| **init** | Set up the environment: install `bd`/`jq`, run `bd init`, verify `scripts/summary-check.sh`. Hands off to **plan**. | `workflows/init.md` |
| **plan** | Create or extend the graph. Bootstraps the epic + initial frontier from `mission.md`, or replans downstream tasks after a closed task. | `workflows/plan.md` |
| **execute** | Run one ready task end-to-end. Hands off to **plan** when the closed task type unlocks new structure; otherwise to **update-summary**. | `workflows/execute.md` |
| **update-summary** | Regenerate `summary.md` from beads. Idempotent — no-op when `scripts/summary-check.sh` reports `status: fresh`. | `workflows/update-summary.md` |

Task-type schemas live in `assets/schemas.yaml`.

## Routing

### 1. Honor explicit requests

If the user named a workflow ("init the research", "refresh the summary", "run the next step", "execute task bd-xyz"), dispatch to that workflow.

### 2. Otherwise → brainstorm

If the user did not name a workflow, run **brainstorm**. It inspects the working directory, answers the user's question, drafts or refines `mission.md` when appropriate, and hands off to `init` / `plan` / `execute` / `update-summary` once the user is ready to act.

### 3. Chaining

- **init** → always run **plan** afterwards (which then chains to **update-summary**).
- **plan** → always run **update-summary** afterwards so the digest reflects the new graph.
- **execute** → if the closed task type is `literature_review`, `hypothesis`, `analysis`, or `synthesis`, chain to **plan** (which chains to **update-summary**); otherwise chain directly to **update-summary**.
- **update-summary** and **brainstorm** → never chain.

## Boundaries

This skill does not validate output quality or cache results. `mission.md` is written only by **brainstorm** and only with user confirmation. `bd init` is run by **init**. Each workflow's `.md` file states its own scope.