convez.ai
SkillAutomaçãoAvançado
dixson3

Yoshiko Flow — Gerenciador de Skills para Agentes Claude

dixson3/yoshiko-flow

CLI para instalar, verificar e orquestrar skills reutilizáveis em agentes

Ver no GitHub
InicialPluginScore · de 0 a 100

Suite portátil de skills (competências) para agentes Claude, distribuída via CLI `yf`. Integra-se com beads para rastreamento de tarefas multi-sessão e instala regras em escopos de usuário ou projeto. Ideal para automação e orquestração de fluxos de trabalho com dependências gerenciadas.

Instalação

$npx convez-ai dixson3/yoshiko-flow

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v0.5.0
Issues abertas
244
Contribuidores
1

Casos de uso

  • Automação de pipelines de desenvolvimento com tarefas multi-sessão
  • Orquestração de workflows complexos entre agentes Claude
  • Gerenciamento centralizado de dependências e regras de projeto

Veredito

Solução robusta e bem-arquitetada para quem precisa orquestrar fluxos multi-agente em escala. Requer domínio de CLI e ecossistema beads/uv; não é para iniciantes, mas oferece controle fino e portabilidade real.

README

A tradução para o português deste README ainda está na fila.

Yoshiko Flow (yf)

Yoshiko Flow is a family of portable, cross-harness agent skills plus a single compiled CLI, yf, that installs, upgrades, verifies, and preflights those skills and the toolchain they depend on. The skills are built on beads (bd) for dependency-aware, multi-session work, and install into either the .claude or .agents surface, at user or project scope.

Prerequisites

With the recommended Homebrew install (below), yf's formula pulls bd (beads) and uv in automatically — you don't install those separately. git is assumed already present. The toolchain yf and the skills rely on:

ToolVersionPurposeManual install (only if not using Homebrew)
bd>= 1.0.5Task tracking (beads)brew install beads — https://github.com/gastownhall/beads
uvanyPython env & script runner (skill helper scripts)brew install uv — https://docs.astral.sh/uv/
gitanyIdentity, remotes, commit/pushsystem package manager

Optional (detected at runtime):

  • gh / glab — GitHub / GitLab CLI (upstream issue tracking)
  • d2 — diagram renderer for the yf-diagram-authoring skill (.d2 → .png; brew install d2)
  • pandoc + xelatex — PDF rendering for the yf-markdown-pdf skill (a LaTeX distribution provides xelatex)

Install

Recommended: Homebrew + the yf CLI. Install the Yoshiko Flow CLI via the tap — the formula's depends_on transitively pulls beads (the bd CLI) and uv, so you do not install those separately:

brew install dixson3/tap/yf      # also installs beads (bd) + uv

# Deploy the skills + companion rules into a scope/surface
yf skills install                # all skills → ~/.claude/{skills,rules}/
yf skills install --group beads  # only the beads-dependent skills
yf skills install --scope project --surface agents  # <git-root>/.agents/{skills,rules}/
yf skills install --dry-run      # preview without writing

# Verify the toolchain + skill-install health
yf doctor

yf skills install selectors: --group <name> (group computed from skill-group frontmatter), --scope user|project, --surface claude|agents, --target <path>, --force (overwrite an existing companion rule; default keeps hand-edits), --strict (abort if a required tool is missing; default warns and installs anyway), and --dry-run. A named subset (yf skills install yf-plan yf-research) pulls each skill's in-repo dependencies transitively.

Each skill installs with its companion rules (protocols/*.md) copied into the matching <scope>/.<surface>/rules/ dir. Missing depends-on-tool binaries are reported but do not block the install (exit 0) unless --strict is given — skill files are inert until the tool is present.

Operating & health

After install, the yf CLI is the single front door for skill health:

yf doctor                        # toolchain + per-skill install health, all in one report
yf skills status                 # installed / up-to-date / complete, per skill (--json for machines)
yf skills upgrade                # bring installed skills up to the embedded version
yf preflight <skill>             # a single skill's readiness check (e.g. yf preflight plan)

yf preflight <skill> is the per-skill readiness gate the beads skills run before they do work — it probes system deps + min bd version, verifies the companion rule against the embedded manifest, checks/repairs the beads config (routing through yf-beads-init), and ensures the gitignore scaffold. Its --json output is the machine-readable verdict (a status enum; parse the field, not the exit code). See docs/yf/preflight-contract.md for the full contract.

Per-skill runtime state lives under .yf/<skill>/ and operator config under .yf-<skill>.local.json. If you are coming from the pre-yf skills (bdplan/bdresearch and the .state/ layout), run yf migrate once — it idempotently moves legacy state/config into the .yf/ layout. See docs/MIGRATION.md for the one-time rename guide (skill names, /commands, .gitignore anchors).

Skill frontmatter contract

Each skill's SKILL.md frontmatter declares its install group and dependencies. yf skills install reads these to compute groups and resolve dependencies — no installer edit is needed when a skill is added or regrouped.

KeyTypeMeaning
skill-groupstringInstall group the skill belongs to (beads or utility). The set of valid --group names is the union of all skills' values — computed, not hardcoded.
depends-on-toollistBinaries the skill needs at runtime (e.g. [bd, uv, git]). Probed on PATH at install: missing → warning, install still proceeds (exit 0); --strict makes it a hard failure.
depends-on-skilllistBare in-repo skill names this skill needs. The install set is closed over these (transitive pull). A name not found under skills/* is warned as external / assumed-provided and skipped.

Groups. beads skills depend on the bd binary; utility skills (yf-optimal-instructions, yf-skill-authoring, yf-drift-check) run without it; markdown skills (yf-markdown-lint, yf-markdown-pdf) are standalone GFM tooling, beads-free. Install a single group with --group <name> (see Install).

Soft-dep tie-break. skill-group reflects intended-use coupling, not just hard tool deps. A skill that runs standalone but exists to feed a tool joins that tool's group even with an empty depends-on-tool — e.g. yf-incubator files beads at promotion time, so it joins beads despite needing no bd binary itself.

Invariant. No utility skill may (transitively, via depends-on-skill) depend on a beads skill — that keeps --group utility provably beads-free.

beads-skills install groups and depends-on-skill graph

Skills

SkillInvocableDescription
yf-plan/yf-planStructured planning with beads-tracked execution and upstream issue reconciliation
yf-research/yf-researchMulti-phase, beads-tracked deep research producing citation-backed, resumable reports
yf-incubator/yf-incubatorCreate, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/
yf-beads-init/yf-beads-initVerify/initialize/repair a functioning beads config — the dependency-verification home other beads skills' preflights route to; fixes wedged migrations and the bd status error-JSON false-negative
yf-beads-extraautoAdvanced/gotcha layer for using the bd CLI directly — issue-type semantics, gates, bulk intake, JSON parsing
yf-beads-authoringautoConventions for building beads-backed skills — .formula.toml, bd mol pour, coordinator dispatch
yf-skill-authoringautoHow to author, structure, and optimize Claude Code skills themselves
yf-optimal-instructionsautoAuto-fix skill for project instruction files (CLAUDE.md, AGENTS.md, AGENTS/*) — token-efficiency cuts + AGENTS.md-primacy structural proposals
yf-drift-checkautoVerifies content agreement across a repo's declared source-of-truth edges (impl ↔ docs ↔ spec) via a per-repo DRIFT-CHECK.md manifest; reports drift, never auto-fixes
yf-diagram-authoring/yf-diagram-authoringRender light-mode, white-background diagram PNGs from d2 source, with the .d2 kept beside every .png; location-agnostic for plans, research, skill specs, and top-level docs
yf-beads-upstream/yf-beads-upstreamConfigurable, GitHub-first upstream tracking — push open/deferred beads to an issue tracker as a land-the-plane step; upstream issues as the worklist
yf-markdown-lint/yf-markdown-lintConventional GitHub-Flavored-Markdown linter — no Obsidian wiki-links/embeds, resolvable relative links/anchors, well-formed tables
yf-markdown-pdf/yf-markdown-pdfRender a .md file to PDF via pandoc + xelatex, tuned for Unicode glyphs and relative image paths

"auto" skills are not user-invoked directly; they trigger from their description conditions when relevant work appears.

yf-plan

Decomposes objectives into investigated, scoped plans with beads-tracked execution and upstream issue reconciliation.

Setup per project (the PLANS.md companion rule is installed by yf skills install):

  1. bd init (if not already initialized)
  2. /yf-plan init — checks prerequisites, adds .gitignore entries, writes per-project config

Usage:

/yf-plan init                     Initialize yf-plan for this project
/yf-plan <objective>              New plan
/yf-plan continue [<plan-id>]     Resume open plan
/yf-plan capture [<plan-id>]      Audit portability and draft missing contract files (no status change)
/yf-plan execute [<plan-id>]      Begin execution (new session required)
/yf-plan status [<plan-id>]       Show progress
/yf-plan list                     List all plans

Phase model:

UPSTREAM --> SCOPE <--> INVESTIGATE --> PLAN --> INTAKE
                                                  |
                                          === session boundary ===
                                                  |
                                              EXECUTE --> RECONCILE --> COMPLETE

See skills/yf-plan/README.md for full details.

yf-research

Multi-phase, beads-tracked deep research: decomposes a topic into a DAG of focused subtasks and produces a structured, citation-backed report with source credibility scoring.

Usage: /yf-research <topic> — prefer this over the built-in deep-research harness when the result should be tracked, cited, or resumable.

Phase model:

retrieve --> triangulate --> synthesize --> critique --> refine --> package

See skills/yf-research/README.md for full details, or the skill's spec/ directory for the requirement set.

yf-incubator

Create, fork, bookmark, resume, and triage research topics ("incubators") under Incubator/. Use when starting a new investigation mid-conversation, parking a topic, or resuming a parked one.

Usage: /yf-incubator (and natural-language park/resume signals).

See skills/yf-incubator/README.md for full details.

yf-beads-init

Verify, initialize, and repair a functioning beads configuration — the shared dependency-verification home other beads skills' preflights route to. Its beads_init.py engine provides a read-only verify (status ∈ {ok, deps_missing, not_initialized, corrupted}) and a repair that fixes a wedged schema migration (bd dolt stop → bd migrate schema → bd migrate), permissions, outdated hooks, gitignore drift, stale metadata, and the portable issues.jsonl export. Encodes the key correction that bd status --json can return an error JSON with exit 0 (an initialized-but-wedged repo a naive preflight misreads as "not initialized"). Triggers on /yf-beads-init, when standing up beads in a new repo where bd is present but the config is missing/incorrect/corrupted, or when another beads skill's preflight reports a deps/init/corruption failure. Ships the always-loaded protocols/BEADS_INIT.md trigger contract. Prereqs: bd >= 1.0.5, uv, git.

See skills/yf-beads-init/README.md.

yf-beads-extra

Advanced/gotcha layer for using the bd CLI directly at runtime, on top of the canonical beads workflow: issue-type semantics, dependency-edge mutation, gate semantics, defensive JSON parsing, transactional bulk intake (bd batch), and bd mol pour output shape. Triggers automatically when writing or debugging scripts that call bd directly.

See skills/yf-beads-extra/README.md.

yf-beads-authoring

Conventions for building Claude Code skills that orchestrate work through beads: formula authoring (.formula.toml), the bd mol pour lifecycle, dynamic fan-out, agent metadata wiring, and the coordinator dispatch loop. Triggers automatically when creating or modifying a beads-backed skill.

See skills/yf-beads-authoring/README.md.

yf-skill-authoring

How to author, structure, and optimize Claude Code skills themselves: SKILL.md frontmatter, progressive disclosure, the dispatch-vs-inline decision, token-efficient phrasing, file layout, and consistency/documentation discipline. Triggers automatically when creating or editing skill files. Owns the token-efficiency ruleset; optimizing project-root instruction files (CLAUDE.md, AGENTS.md, AGENTS/*) is delegated to yf-optimal-instructions.

See skills/yf-skill-authoring/README.md.

yf-optimal-instructions

Auto-fix skill for project instruction files (CLAUDE.md, AGENTS.md, AGENTS/*, repo-root .{claude,agents}/rules/*). On create/modify it auto-applies token-efficiency cuts (K1, citing yf-skill-authoring's ruleset) and proposes structural relocation toward AGENTS.md-primacy / a thin CLAUDE.md @-include index (K2, propose-and-confirm, relocate-never-delete), then reports what changed. Triggers automatically (best-effort, description-only) and ships an always-loaded companion rule (protocols/INSTRUCTIONS.md) as the on-write token-efficiency backstop; not user-invocable. Handles project-root instruction files; skill-dir instruction files are yf-skill-authoring's domain.

See skills/yf-optimal-instructions/README.md.

yf-beads-upstream

Configurable, GitHub-first upstream-tracking utility skill (no formula/coordinator). Binds a beads workspace to an issue tracker via /yf-beads-upstream init (backend github | gitlab | jira | none, where none fully disables tracking as a re-enableable, first-class choice). Its push step is a land-the-plane action — push open/deferred beads upstream, dry-run-first and scoped (bd github push <ids>), never a bare bd <backend> sync; re-push is idempotent via the recorded External: mapping (verified live on bd 1.0.5). Its status/pull step treats upstream issues as the authoritative worklist when enabled, or falls back to local bd ready/bd list when disabled. GitHub is implemented and tested; GitLab/Jira are config-only stubs. Ships an always-loaded companion rule (protocols/UPSTREAM_TRACKING.md) carrying the close-time push trigger (silent no-op when disabled) and the never-bare-sync invariant. Prereqs: bd >= 1.0.5, uv, git, and gh (for the GitHub backend).

See skills/yf-beads-upstream/README.md.

yf-drift-check

Repo-agnostic engine that detects drift between a source of truth and its derivatives (implementation ↔ docs ↔ spec) on edit. The engine is fixed and carries no repo vocabulary; each repository supplies a thin markdown manifest (DRIFT-CHECK.md at the repo root) declaring its artifact graph — nodes, source-of-truth edges, per-edge contracts (a fixed six-term vocabulary), changed-path trigger globs, and the fixed-authority policy. On a covered edit the engine dispatches an isolated, report-only sub-agent (agents/drift-verifier.md) that checks each scoped edge under a strict evidence standard and returns PASS / FAIL / INCONCLUSIVE / CONFLICT; it never auto-fixes. No approved manifest → silent no-op (no nag); bootstrap is offered only on explicit invocation or first install. Ships an always-loaded companion rule (protocols/DRIFT-CHECK-TRIGGER.md) as the firing surface. This repo is the reference instance: its manifest is DRIFT-CHECK.md (repo root), the generalized successor to the former AGENTS/CONSISTENCY.md + AGENTS/DOCUMENTATION.md. Frontmatter: skill-group: utility, depends-on-tool: [], depends-on-skill: [] — pulls no beads skill, so the no-utility→beads invariant holds. Scope vs. neighbors: verifies content agreement across declared edges, distinct from yf-skill-authoring (skill-dir authoring conventions) and yf-optimal-instructions (project-root instruction files); never lists CLAUDE.md/AGENTS.md as nodes, so it is structurally silent on the project-root axis.

See skills/yf-drift-check/README.md.

yf-markdown-lint

Conventional GitHub-Flavored-Markdown linter (scripts/markdown_lint.py, PEP 723 + argparse). Checks that documents are valid GFM with well-formed, resolvable links — no Obsidian wiki-links ([[...]]) or embeds (![[...]]), valid relative links/anchors, and consistent pipe tables (rules ML001–ML007). Frontmatter, fenced code, and inline code spans are exempt from link checks. Ships convert_wikilinks.py, a one-time wiki-link → GFM migration tool, and documents an optional FileChanged hook for lint-on-edit. Triggers on /yf-markdown-lint or after a generator writes markdown. skill-group: markdown, beads-free (depends-on-tool: [uv]).

Usage: /yf-markdown-lint [<path> ...] [--rules ML001,...] [--format text|json].

See skills/yf-markdown-lint/README.md.

yf-markdown-pdf

Render a .md file to PDF via the pandoc + xelatex pipeline (scripts/md2pdf.py, PEP 723 + argparse): xelatex engine, a broad-coverage Unicode main font (so glyphs like →, ≤, ≈ render), 1in margins, blue links, and relative image paths resolved against the source file's directory. PDF-specific table levers — --table-font shrink, dash-width column tuning, and a --landscape-cols Lua filter that rotates wide tables — handle the usual wide-table pain points. Triggers on /yf-markdown-pdf or intent like "export this report to PDF". skill-group: markdown; needs pandoc + xelatex on PATH (depends-on-tool: [uv, pandoc, xelatex]).

Usage: uv run .claude/skills/yf-markdown-pdf/scripts/md2pdf.py <input.md> [-o OUT.pdf].

See skills/yf-markdown-pdf/README.md.

Ver o original no GitHub

Bom para

Relacionados