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, orsynthesis, 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.