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.