>_ yoshiko-flow v0.4.0

yf-incubator

Create, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/.

Create, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/.

At a glance

When it fires

/yf-incubator invoked; starting a new investigation mid-conversation; the conversation is descending into a sidequest off its main topic; user signals walking away / pausing / stopping a topic; asking what incubators exist or which to work next; resuming a parked topic.

When to skip it

beads-tracked multi-step build planning (use yf-plan); routine note edits with no park/resume intent.

Prerequisites

  • uv — runs the scripts/incubator-index.py helper (PEP 723 inline deps).
  • beads-extra skill — the incubation→build hand-off (## Beads to file) files beads via the bd CLI patterns that skill documents.

Usage

User-invocable (/incubator). Subcommands:

/incubator new <name> [seed notes]   create, set active
/incubator fork <name>               fork current sidequest into a new incubator, set active
/incubator bookmark [notes]          rewrite active incubator's ## Resume + last_reviewed
/incubator resume <name>             load bookmark, set active
/incubator list                      index all incubators by state + staleness
/incubator touch <name>              bump last_reviewed only

Proactive sidequest detection (offer once to fork a tangent) also fires from natural-language park/resume signals, driven from AGENTS.md (see below).

What it does

  • new / fork — spin up a fresh incubator mid-conversation, or fork a sidequest out of the current conversation so the tangent isn't lost.
  • bookmark — write the ## Resume block for the active topic on demand (explicit only: on a "walking away" signal or a phase boundary; there is no per-turn write and no Stop hook, by design — the trade-off is that a turn killed mid-write loses only that turn's delta).
  • resume — reload a parked topic from its bookmark and named context files.
  • list — scripts/incubator-index.py indexes the whole tree by state and staleness, tolerating pre-existing "unmanaged" incubators without mutating them; managed ones are retrofitted lazily when next actively worked.
  • touch — bump last_reviewed for triage without a full resume.

Proactive sidequest detection (offer once to fork a tangent) is driven from AGENTS.md, not this skill, so it fires even when the skill isn't pre-loaded.

Schema rationale

The frontmatter and body contract were derived by surveying all ~36 existing incubators and biasing toward the most active (bookpipe, gloak, yoshiko-flow):

  • status is the maturity ladder actually used in the vault — incubating → scoping → exploring → converging → concluded — plus parked (deliberately paused) and abandoned. The earlier active/blocked values were invented and unused.
  • ## Decision log and ## Beads to file are load-bearing in the active incubators: the decision log is a first-class append-only record, and "Beads to file" is the incubation→build hand-off (bead stubs ready for bd create), which ties into the project rule that follow-on work is filed as beads.
  • ## Resume is the one skill-owned addition. It consolidates into a single predictable block what the best existing resume artifact (yoshiko-flow/routing-proxy-investigation.md) scatters across "Next concrete steps" + "Beads to file" + "Open invitation."
  • last_reviewed / priority exist only to drive the index's triage sort.

Layout

  • SKILL.md — instruction-only entry point (frontmatter trigger, invocation, schema as output contract, subcommand steps, constraints).
  • README.md — this file.
  • scripts/incubator-index.py — uv PEP-723 script; classifies managed vs unmanaged, sorts by priority then staleness, --json / --write options.