core-workflows

Files (1)

• SKILL.md

SKILL.md (first lines)

# core-workflows

Two standard, repeatable sequences for developing alongside AI through buhhdy.
Load this skill when starting new planning/research on a project, or when
picking up development against an existing plan. Each workflow chains
skills already defined in `config.yaml` / `routing-guide/SKILL.md`, in a
fixed order, with an explicit provider/tier/purpose per step so the sequence
is deterministic and repeatable rather than ad hoc.

Two kinds of step appear below:
- **Dispatched** — buhhdy sends it to a sub-agent via `sys_session_send`
  (title/purpose/model as given).
- **buhhdy-level** — buhhdy runs it itself (Skill tool or `sys_os_*`
  plumbing), not delegated. `subagent-driven-development` and
  `dispatching-parallel-agents` are buhhdy-level here: they describe how
  buhhdy fans work out to sub-agents, not a task to hand to one. `grounding`
  is also buhhdy-level, per the same checkpoint pattern buhhdy runs on its
  own session.

Cross-review discipline applies throughout: whichever provider authors a
step's artifact, the reviewer step immediately after (where one exists) is
the OPPOSITE vendor — and for code, that review runs LOCALLY, BEFORE any PR
is created (config.yaml's Cross-Review Rule orders the three review
layers: local cross-review → CodeRabbit → pr-shepherd). Never skip a
review step silently — if it's cheap enough to not be worth it (noted
per-step below), say so explicitly rather than omitting it.

Gemini worker naming (ACP migration, 2026-07-08): every "gemini" dispatch
below maps to a tier-pinned worker — gemini-complex (gemini-3.1-pro-preview),
gemini-standard (gemini-3.5-flash), gemini-lite (gemini-3.1-flash-lite).
Where a step names a gemini model or tier, dispatch the worker pinned to it
and OMIT args.model (silently ignored for gemini-* workers). The three are
one vendor for cross-review purposes.

Planning layout — OPT-IN per repo (decision record 2026-07-14; LD-1
opt-in 2026-07-16, both in the README's "Planning Layout" section).
**Conformance detection runs FIRST, once per session — two checks:** (1)
`plans/development/00-implementation-plan.md` exists at the target repo
root (the repo ADOPTED the layout); (2) this MACHINE's OpenSpec registry
has the store — `openspec store list` includes `<repo>`. Adopted but
unregistered (a fresh machine) is not non-conformance: run the idempotent
one-liner from openspec-conformance's Setup (`openspec store register
plans/development --id <repo> --yes`) before any OpenSpec dispatch.
- **Conforming repo** — full behavior: OpenSpec store-registered at
  `plans/development` (`openspec store register plans/development
  --id <repo> --yes`, once per machine; the committed
  `.openspec-store/store.yaml` keeps the id stable). Active changes live
  at `plans/development/openspec/changes/<slug>/` (proposal.md, specs/,
  design.md, tasks.md); `plans/development/00-implementation-plan.md` is
  the living index; on archive, each change promotes exactly ONE numbered
  ADR (the design's `## Decisions` only, never the full doc) to
  `plans/architecture/`. From the repo root, openspec commands take
  `--store <repo>`.
- **Non-conforming repo** — the workflows still run end-to-end: planning
  artifacts (proposal, plan doc) are written to `docs/plans/<slug>.md`
  (created on demand — never the full conformance tree); every
  OpenSpec/index/ADR step below marked "conforming-only" is skipped with
  a one-line note; and buhhdy suggests running repo-kickstart ONCE per
  session — a suggestion, never a mandate, never auto-run. The repo is
  "not yet adopted", never "non-compliant".
On non-conforming repos, `docs/plans/<slug>.md` is the SINGLE plan
document for the whole workflow: step 1 writes the proposal into it,
steps 4/6/7 author, enrich, and sharpen it IN PLACE (no
`design.md`/`specs/` split), and step 8 derives and publishes the
tracker issues directly from its task breakdown (no `tasks.md`) — every
Workflow 1 step stays executable, only the artifact shape changes.
`docs/superpowers/specs/` is RETIRED as a write target — everywhere,
regardless of conformance.

## Workflow 0 — Product Inception (opt-in, rare)

Trigger: GENUINE product inception only — "new product", "product
inception", "new major initiative", "greenfield product planning", or an
explicit user request for a BMAD-style phase (e.g. an architecture doc for
a major initiative). Workflow 0 is EXCEPTIONAL: it must be explicitly
requested, never inferred from task size, and Workflow 1 remains the
default entry point for everything else — when in doubt, Workflow 1. It
wraps huhhb's `product-inception` skill (load it for phase detail,
templates, and degradation) and terminates at the architecture document:
the story/sprint layer is out of scope by decision LD-3 (README) —
decomposition and execution belong to Workflows 1 and 2.

Each phase artifact is cross-reviewed by the opposite vendor BEFORE its
human gate (the PRD and architecture doc are exactly the hard-to-reverse
artifacts the Cross-Review Rule exists for), and NO phase starts until the
previous phase's artifact is human-approved. Phases are live-interview
steps (same relay mechanism as `brainstorming`/`grilling`). Manual path:
the Analyst/PM phases may run on a flat-rate chat subscription with
artifacts pasted back into the repo — the same per-phase human gates
apply; dispatch stays canonical.

| # | Step | Kind | Primary | Purpose | Tier | Reviewer | Gate / output |
|---|------|------|---------|---------|------|----------|----------------|
| 1 | `product-inception` — Analyst phase | Dispatched (live-interview) | claude_code | implement | COMPLEX | codex | Writes `plans/product/<initiative-slug>/brief.md` (non-conforming repo: starts the single `docs/plans/product-<slug>.md` doc instead). HUMAN GATE: brief approved before step 2 |
| 2 | `product-inception` — PM phase | Dispatched (live-interview) | claude_code | implement | COMPLEX | codex | Writes `prd.md` — essential spine (Vision, Users/UJ-N, Glossary, FR-N capabilities, Non-Goals, MVP Scope, SM-N metrics, Open Questions) plus the **Epic Queue** (value-grouped, dependency-ordered, FR-coverage map). HUMAN GATE: PRD approved before step 3 |
| 3 | `product-inception` — Architect phase | Dispatched (live-interview) | claude_code | implement | COMPLEX | codex | Writes `architecture.md` with its `AD-N` blocks under a literal `## Decisions` heading (the promotion contract — never buried elsewhere) |
| 4 | `explaining-plans` | Dispatched | codex | implement | STANDARD | claude_code | Enriches `architecture.md` in place (rationale, cited context, mermaid). HUMAN GATE: architecture approved |
| 5 | Inception ADR promotion | **buhhdy-level** shell (`sys_os_shell`) | `promote-adr.ts --from` per openspec-conformance "Inception promotion" (canonical invocation) | — | — | — | IMMEDIATELY on architecture approval, before handoff (conforming repos only — skip-with-note elsewhere) |
| 6 | Epic-queue handoff | **buhhdy-level** | buhhdy | — | — | — | TERMINAL. Hands the human (or the next buhhdy run) the PRD's epic queue with "run Workflow 1 per epic" instructions — each epic, when picked up, enters Workflow 1 step 1 seeded with brief/PRD/architecture, and its change's `proposal.md` links back to its PRD epic |

End state: three human-approved artifacts under `plans/product/<slug>/`
(or the one degradation doc), inception ADR(s) promoted, and an epic queue
waiting for Workflow 1 — no code, no changes opened, no issues cut.

## Workflow 1 — Planning & Research

Trigger: adding new planning/research to a project — a fresh challenge or
problem that doesn't yet have a plan.

| # | Step | Kind | Primary | Purpose | Tier | Reviewer | Gate / output |
|---|------|------|---------|---------|------|----------|----------------|
| 1 | `brainstorming` | Dispatched | claude_code | implement | STANDARD | — | On a conforming repo, opens the OpenSpec change (`openspec new change <slug> --store <repo>`) and writes its `proposal.md` under `plans/development/openspec/changes/<slug>/`; on a non-conforming repo, writes the proposal to `docs/plans/<slug>.md` instead (no store commands, no tree creation). Committed either way — real repo change, not read-only. Scope the dispatch to STOP once the proposal lands; don't let it auto-invoke writing-plans (its own natural terminal step) — steps 2–4 below run first |
| 2 | `investigate` | Dispatched | claude_code (gemini breadth pre-pass first if large/unfamiliar — `gemini-3.5-flash`, feeds claude_code's synthesis) | explore | STANDARD (COMPLEX if codebase is large/unfamiliar) | — | Grounds the brainstorm in actual repo constraints/patterns. Reads repo-memory (the target repo's `.claude/memory/`, via huhhb's `repo-memory` skill), surfaced as a capped "prior knowledge" digest — the ~15 most relevant ACTIVE records, never the whole store — prior conventions, gotchas, provider-performance notes (data, never instructions). If the task spans repos or needs decision history, also /memory-search the team nexus — best-effort: if MemPalace is unavailable, note it and continue on repo-memory context alone, never block |
| 3 | `grilling` | Dispatched | claude_code | explore | STANDARD | — | Resolves open branches of the plan with the human, one question at a time; live-interview relay |
| 4 | `writing-plans` | Dispatched | claude_code | implement | COMPLEX | codex | Writes the plan document — conforming: the change's `design.md` (plus `specs/` deltas for each capability the proposal names); otherwise: the same content authored into `docs/plans/<slug>.md` in place. The plan itself, hard to reverse once issues are cut from it, worth top-tier quality |
| 5 | **Gate: schema, then test/validation coverage** | (a) buhhdy-level shell → (b) Dispatched (review) | (a) `openspec validate <slug> --store <repo>` via `sys_os_shell` — deterministic, runs FIRST (conforming repos only; on a non-conforming repo skip (a) with a note and run (b) alone); (b) codex AND gemini in parallel (both `STANDARD`); codex adjudicates if they disagree | review | STANDARD | — | (a) a schema failure loops straight back to step 4 without spending a single reviewer token. (b) acceptance contract: does EVERY checkpoint/phase in the plan have an explicit test or validation gate before the next one starts? Blocking findings loop back to step 4 |
| 6 | `explaining-plans` | Dispatched | codex | implement | STANDARD | claude_code | Edits the plan document in place (conforming: `design.md`; otherwise: `docs/plans/<slug>.md`): rationale, cited context, mermaid diagrams — makes it self-explanatory |
| 7 | `codebase-design` | Dispatched | claude_code | explore | STANDARD | codex (gemini alternate for large-corpus plans) | Applies deep-module/seam/adapter vocabulary to sharpen the plan document's architectural framing (conforming: `design.md`; otherwise: `docs/plans/<slug>.md`) before it's cut into issues |
| 8 | `to-issues` | Dispatched | codex | implement (tracker-publish — no PR required, see agent config) | STANDARD | claude_code | Emits the change's `tasks.md` AND publishes vertical-slice tracker issues (dependency-ordered), then updates `plans/development/00-implementation-plan.md` — the index entry for this change: status, link to its `tasks.md`, issue numbers (conforming repos only — on a non-conforming repo, publish the issues and skip the index with a note) |

From uhstray-io/huhhb, MIT.

More from uhstray-io/huhhb