skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
kirkchen/beat523 installs

design

Use when starting a Beat change to create spec artifacts — not for task breakdown, implementation, or exploration

How do I install this agent skill?

npx skills add https://github.com/kirkchen/beat --skill design
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill is overall safe for its intended purpose as a design and specification tool. It has a minor vulnerability surface for indirect prompt injection as it processes data from external issue trackers, and it executes local Node.js scripts for project validation.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 2 issues

What does this agent skill do?

Design a change — create a change container (if needed) and generate spec artifacts.

<decision_boundary>

Use for:

  • Creating a new Beat change and generating spec artifacts (proposal, gherkin, design.md)
  • Resuming artifact generation for an existing change that has pending spec artifacts
  • Choosing which spec artifacts to include (presets: Full, Standard, Minimal, Technical, Custom)

NOT for:

  • Breaking down tasks or creating execution plans (use /beat:plan)
  • Exploring ideas or thinking through a problem before committing (use /beat:explore)
  • Implementing code (use /beat:apply)
  • Reviewing or verifying implementation (use /beat:verify)

</decision_boundary>

<HARD-GATE> Before writing any artifact files: you MUST invoke superpowers:using-git-worktrees. When the artifact selection includes proposal or design, you MUST invoke superpowers:brainstorming before generating content. This applies even when scope seems obvious.

Before writing gherkin scenarios: you MUST run the four-challenge glossary check (see step 4 below) and ensure every project-specific term used in scenarios is defined in GLOSSARY.md at the project root (path: references/project-layout.md). Create the glossary lazily — only when the first term is added.

After writing each artifact: you MUST run the four-check spec self-review (placeholder / consistency / scope / ambiguity). Fix issues inline.

While writing design.md: you MUST run the three-condition ADR gate (hard-to-reverse + surprising + real trade-off — see references/adr-format.md) on each Key Decision. When all three hold, offer to lift the decision into a new ADR under docs/adr/. The user may decline.

Invoke in order: worktrees first (isolate), then brainstorming (design).

If a prerequisite skill is unavailable (not installed), continue with fallback — but NEVER skip because you judged it unnecessary. </HARD-GATE>

Prerequisites (invoke before proceeding)

SkillWhenPriority
superpowers:using-git-worktreesBefore first file writeMUST
superpowers:brainstormingBefore creating proposal or designMUST
grilling + domain-modeling (mattpocock/skills, model-invoked)When a term fails the glossary four-challenge check and inline resolution is not enoughOPTIONAL

If a prerequisite skill is unavailable (skill not installed), skip and continue. grilling and domain-modeling are called directly when needed (they are model-invoked); grill-with-docs is user-invoked and cannot be reached from a skill — never offer it, tell the user they can run it themselves if they want a longer session.

Unattended mode

When the invocation carries --unattended, nobody can answer during the run: follow references/unattended-mode.md. Without it this skill is interactive, whatever the environment looks like. Every AskUserQuestion in this skill becomes a default (recorded in beat/changes/<name>/decisions/assumed.md), a decision brief (references/decision-brief.md, blocked-on: decision), or an environmental stop (blocked-on: env). The per-skill table in that reference says which. For design specifically: the preset defaults to what explore declared or standard; a Key Decision copied from the issue's locked decisions skips the ADR gate; any other Key Decision that meets the gate is one the human has not made, so it becomes a brief, and the ADR is written only from the reply.

Rationalization Prevention

ThoughtReality
"I don't need a worktree for just writing specs"Without a worktree, artifacts live in the main workspace and won't carry into apply. Isolate from the start.
"brainstorming isn't needed, the user already described what they want"A description is not a design. brainstorming surfaces assumptions, alternatives, and edge cases.
"The user wants speed, invoking superpowers will slow us down"Skipping prerequisites produces lower-quality artifacts that cause rework during apply and verify.
"This change is simple enough to skip brainstorming"Simple changes finish brainstorming quickly. Complex changes need it most. There is no middle ground where skipping helps.
"The domain terms are obvious, no need to update GLOSSARY.md"Obvious to you, not to future-you or anyone else reading the feature in six months. Glossary entries are two lines. Add them inline.
"Spec self-review is overkill, the artifact is short"Self-review catches placeholders, contradictions, and ambiguities that compound through plan and apply. The four checks take 30 seconds.
"This decision is just for this change, no ADR needed"Run the three-condition gate. If it's hard-to-reverse, surprising, and a real trade-off, future changes will trip over it — that's the ADR's job. Decisions that are change-specific don't pass the gate; let the gate decide, not your gut.
"We'll lift this into an ADR later""Later" rarely arrives. The decision is fresh now; the ADR is 1-3 sentences. Write it inline.
"Explore said minimal, but I'd rather ask the preset question anyway"Explore already listed the facts. Asking again is the double question the exit was meant to remove. Use it and say so.
"I'll pick minimal to keep this quick"Minimal is for changes whose files sit in one module with nothing left to decide. If you can't list that, it's standard. Apply will upgrade a wrong guess, at the cost of a second verify.

Red Flags — STOP if you catch yourself:

  • Writing any file before invoking using-git-worktrees
  • Generating proposal sections without having invoked brainstorming
  • Creating design.md without invoking brainstorming first
  • Writing gherkin scenarios that contain internal method names, internal tuning numbers (scores, weights, timeouts), or implementation constants
  • Writing gherkin scenarios that use project-specific domain terms not defined in GLOSSARY.md
  • Modifying an existing feature in beat/features/ without creating a .orig backup first
  • Writing tasks.md or - [ ] checkboxes — tasks belong in /beat:plan
  • Skipping the spec self-review because the artifact "looks fine"
  • Writing a Key Decision in design.md that meets all three ADR conditions without offering an ADR
  • Thinking "this prerequisite isn't needed for this particular change"
  • Leaving preset out of status.yaml, or choosing one without the facts that justify it

Process Flow

digraph design {
    "Select or create change" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "Preset already set?" [shape=diamond];
    "Ask artifact preset" [shape=box];
    "Write preset to status.yaml" [shape=box];
    "Includes proposal?" [shape=diamond];
    "Invoke brainstorming" [shape=box, style=bold];
    "Create proposal" [shape=box];
    "Self-review proposal" [shape=box, style=bold];
    "Includes gherkin?" [shape=diamond];
    "Glossary\nfour-challenge check" [shape=box, style=bold];
    "Existing scenarios\nto modify?" [shape=diamond];
    "Backup .orig +\ncopy to changes/" [shape=box];
    "Create gherkin\n(new features only)" [shape=box];
    "Self-review gherkin" [shape=box, style=bold];
    "Includes design?" [shape=diamond];
    "Create design" [shape=box];
    "ADR gate\n(per Key Decision)" [shape=box, style=bold];
    "Self-review design" [shape=box, style=bold];
    "Commit artifacts" [shape=box];
    "Show summary" [shape=doublecircle];

    "Select or create change" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "Preset already set?";
    "Preset already set?" -> "Ask artifact preset" [label="no"];
    "Preset already set?" -> "Write preset to status.yaml" [label="yes (explore / user)"];
    "Ask artifact preset" -> "Write preset to status.yaml";
    "Write preset to status.yaml" -> "Includes proposal?";
    "Includes proposal?" -> "Invoke brainstorming" [label="yes"];
    "Includes proposal?" -> "Includes gherkin?" [label="no"];
    "Invoke brainstorming" -> "Create proposal";
    "Create proposal" -> "Self-review proposal";
    "Self-review proposal" -> "Includes gherkin?";
    "Includes gherkin?" -> "Glossary\nfour-challenge check" [label="yes"];
    "Includes gherkin?" -> "Includes design?" [label="no"];
    "Glossary\nfour-challenge check" -> "Existing scenarios\nto modify?";
    "Existing scenarios\nto modify?" -> "Backup .orig +\ncopy to changes/" [label="yes"];
    "Existing scenarios\nto modify?" -> "Create gherkin\n(new features only)" [label="no"];
    "Backup .orig +\ncopy to changes/" -> "Create gherkin\n(new features only)";
    "Create gherkin\n(new features only)" -> "Self-review gherkin";
    "Self-review gherkin" -> "Includes design?";
    "Includes design?" -> "Invoke brainstorming" [label="yes, only if\nnot yet invoked"];
    "Includes design?" -> "Commit artifacts" [label="no"];
    "Invoke brainstorming" -> "Create design" [label="for design"];
    "Create design" -> "ADR gate\n(per Key Decision)" [style=bold];
    "ADR gate\n(per Key Decision)" -> "Self-review design";
    "Self-review design" -> "Commit artifacts";
    "Commit artifacts" -> "Show summary";
}

Input: Change name (kebab-case) OR a description of what to build. Can also be an existing change name to fast-forward remaining artifacts. --unattended switches on unattended mode (above).

Steps

  1. If no clear input provided, ask what they want to build

    Use AskUserQuestion tool to ask what they want to build. Derive kebab-case name from description.

  2. Create or select change

    Determine the change name. Before creating any files, invoke using-git-worktrees to isolate this change.

    • If beat/changes/<name>/ doesn't exist: create it (directory + status.yaml + features/.gitkeep)
    • If it exists: use it, read status.yaml (schema: references/status-schema.md) to find remaining artifacts

    From an issue (locked decisions): when the change was dispatched from an issue, or the input names one, read the issue body. The section ## 已定案(不要重新討論) (or ## Decided (do not reopen)) lists decisions the human already made: copy them into design.md Key Decisions as given, never re-ask or re-argue them, and skip the ADR gate for them (the human can lift one into an ADR later). ## 先不做 is the out-of-scope list. ## User stories and ## 測試 seam, when present, are the raw material for gherkin and for the @e2e / @behavior split. See references/unattended-mode.md "Locked decisions". Write issue: "#<n>" (the tracker's reference form, the same string a route node's issue field carries) into the new change's status.yaml (schema: references/status-schema.md): later phases find the change by it in unattended mode, and /beat:archive writes the PR's Closes line from it.

    From a route node: when the input names a route node (<route>/<node-id>, or /beat:explore just handed one off), read beat/routes/<route>/route.md and status.yaml (schema: references/route-schema.md). Write route: <route>/<node-id> into the new change's status.yaml, and add change: <name> to that node in the route's status.yaml. The route's "Decisions so far" and the result files of the node's blockers are context for every artifact below.

  3. Settle the preset

    Read status.yaml. If preset is already set (explore declared small and named minimal or technical, or the user passed one), use it and skip the question — say which preset is in effect and why. When the change comes from an issue, the body's 出口: line (written by /beat:to-issue, e.g. 出口:small(preset minimal)) names the preset the same way; use it and skip the question. English issues carry the same line as Exit: (e.g. Exit: small (preset minimal)); read it the same way. Skip the question only when the line names a preset: a bare 出口:standard / Exit: standard means no preset was agreed, so ask as below (unattended mode takes standard).

    Otherwise, for artifacts still pending, ask user once upfront:

    Use AskUserQuestion tool:

    "Which spec artifacts do you want? (Tasks are handled separately by /beat:plan)"

    1. Full: Proposal + Gherkin + Design (recommended for large features)
    2. Standard: Proposal + Gherkin (recommended for medium features)
    3. Minimal: Gherkin only (recommended for small bug fixes)
    4. Technical: Proposal only, no Gherkin (for tooling/infra/refactor changes with no behavior change)
    5. Custom: Let me choose each one

    Write preset: <full|standard|minimal|technical|custom> to status.yaml. The preset does more than pick artifacts: minimal and technical run /beat:plan with a test-coverage review only and /beat:verify with one independent subagent, and /beat:apply upgrades them to standard if the diff outgrows config.yaml preset_upgrade thresholds. Say this in one line when a small preset is chosen.

    Mark skipped artifacts as skipped in status.yaml. Tasks are always set to pending — task breakdown happens in /beat:plan. Update phase to match the latest completed spec artifact after each creation.

  4. Create artifacts in pipeline order

    Read beat/config.yaml if it exists (schema: references/config-schema.md). Use language for artifact output language, inject context, and apply matching rules per artifact type throughout creation.

    For each artifact to create (pipeline order: proposal -> gherkin -> design):

    • Read all completed artifacts for context
    • Invoke prerequisites per the table above (brainstorming before proposal/design — invoke once before the first artifact that needs it; skip for subsequent artifacts if already invoked)
    • Gherkin only — before writing scenarios: run the glossary four-challenge check (see sub-step below)
    • Create the artifact following the patterns below
    • After writing: run the spec self-review (see sub-step below); fix issues inline
    • Update status.yaml
    • Show brief progress: "Created <artifact>"
    • If context is critically unclear, pause and ask

    glossary four-challenge check (before writing gherkin):

    Read GLOSSARY.md if it exists (schema: references/context-format.md). Create it lazily when the first term is added — never preemptively.

    Walk through the brainstorming output and any draft scenario text. For each project-specific term, run these checks and update GLOSSARY.md inline as findings emerge (never batch). Insert each entry where "Where a new entry goes" in references/context-format.md says — a term goes inside its ## <group> section (or ## Language), never appended to the end of the file after ## Flagged ambiguities:

    1. Against the glossary — the term conflicts with an existing entry? Call it out, resolve, update.
    2. Sharpen fuzzy — the term is vague or overloaded (e.g. "account" meaning Customer and User both)? Pick the canonical word, list the others as _Avoid_.
    3. Stress-test — invent edge-case scenarios that probe term boundaries; force the boundary to be named.
    4. Cross-reference code — the user states behaviour that the code contradicts? Surface, decide source of truth, update the loser.

    Grilling: when a term fails a challenge and the inline resolution is not enough, call grilling (to sharpen the question) and domain-modeling (to write the glossary entry and any ADR) directly — both are model-invoked skills from mattpocock/skills. If they are not installed, continue inline with the four challenges. Do not offer grill-with-docs: it is user-invoked and unreachable from here; the user can run it themselves for a longer session.

    Every project-specific term used in scenarios MUST exist in GLOSSARY.md before the scenario is written. Bolded terms in scenarios are the canonical form.

    Spec self-review (after writing each artifact):

    Re-read the artifact with fresh eyes and check:

    1. Placeholder scan — any TBD, TODO, incomplete sections, vague requirements?
    2. Internal consistency — do sections contradict each other? Does the design match the gherkin scenarios?
    3. Scope check — is this focused enough for a single implementation plan, or does it need decomposition?
    4. Ambiguity check — could any requirement be read two different ways? If so, pick one and make it explicit.

    Fix issues inline. No need to re-review the fix — just fix and move on.

    Artifact patterns:

    • Proposal: Sections: ## Why, ## What Changes, ## Impact

    • Gherkin:

      • Read references/feature-writing.md for conventions on description blocks, scenario organization, and review checklist
      • Before writing, scan beat/features/**/*.feature and beat/changes/*/features/*.feature (excluding current change) — read Feature: and Scenario: lines to map existing coverage, deep-read only overlapping features, avoid duplication and align style
      • From an approved prototype: if the change's route node is blocked by a prototype node whose result names an approved variant, read that result and the stories it lists. Every story state becomes a scenario or is written under an explicit Out of scope note in the feature description — none is silently dropped. @e2e scenarios may point @covered-by at the story's play function.
      • SpecFlow style, tags @happy-path/@error-handling/@edge-case
      • Feature description carries PRD essence (must include: As a / I want / So that)
      • Every scenario MUST have a testing layer tag: @e2e (user journeys needing a running app) or @behavior (business logic testable without a full app; default @behavior)
      • Write at behavior level — describe what the system does ("Monthly billing adjusts for short months"), not how a function works ("calculateNextTransactionDate clamps to last day")
      • Use business language — no internal tuning numbers, code method names, or internal constants. Business-rule thresholds the user can observe ("locked after 5 attempts") and API contract constants are behavior: keep them.
      • Repeated Given steps use Background:
      • Tags must serve a filtering purpose — no decorative tags
      • BDD focuses on high-level acceptance; boundary values and algorithm details belong in unit tests
      • If option 4 (Technical) was chosen, skip gherkin entirely

      Modifying existing features (see references/testing-conventions.md for full mechanism):

      When the scan reveals scenarios in beat/features/ that need modification:

      1. Conflict check: scan beat/features/**/*.feature.orig — if a .orig exists for the same file, another change is modifying it. Warn and stop.
      2. Backup: rename the original in beat/features/ to .feature.orig (hides it from BDD runners)
      3. Copy: copy the original content to beat/changes/<name>/features/<file>.feature
      4. Modify: edit the scenario(s) in the changes/ copy (add/change/remove steps, add new scenarios)
      5. Record: add the original path to status.yaml gherkin.modified array

      New features that don't modify existing scenarios go directly to changes/<name>/features/ as before.

    • Design:

      • Sections: ## Approach, ## Key Decisions, ## Components
      • ADR gate — for each Key Decision, run the three-condition check from references/adr-format.md:
        1. Hard to reverse? (cost of changing your mind is meaningful)
        2. Surprising without context? (future reader will wonder "why on earth this way?")
        3. Result of a real trade-off? (genuine alternatives existed) A decision copied from the issue's locked section skips this gate. Otherwise, if all three hold, use AskUserQuestion tool: "This decision meets the ADR gate. Lift it into docs/adr/?" (unattended: this is a decision the human has not made — write a brief per references/decision-brief.md, stop with blocked-on: decision, and write the ADR only after the reply). On Yes, follow "Before writing an ADR" in references/adr-format.md (apply config rules.adr; use the project's docs/adr/TEMPLATE.md if it exists, otherwise Beat's front-matter template with source: beat/changes/<name>), write the 1-3 sentence ADR, increment the highest existing number in docs/adr/ by one, and add a cross-reference from design.md (See docs/adr/NNNN-slug.md). On No, continue. Create docs/adr/ lazily — only on first ADR. Track every ADR (and any project ADR index) written here — step 5 commits them with the change.
      • Sensitivity check: read sensitive from beat/config.yaml (schema: references/config-schema.md). Compare every Key Decision and every path design.md names against situations (judge it the way the ADR gate is judged — a plausible match is a match) and paths (any touch). Write the verdict to beat/changes/<name>/decisions/sensitive.md (yes|no, what matched, design) and as sensitive: yes|no in the handoff block; say in one line which situation matched. With no sensitive in the config the verdict is no and no file is written.
      • Architecture hub suggestion (Layer 3, advisory) — if design.md describes a module-level architecture change (new module, module split/merge, changed module boundaries or responsibilities), suggest updating beat/ARCHITECTURE.md — the hub diagram, modules table, or constraints (see references/architecture-format.md). Create the hub lazily, only if the project is multi-module and the user accepts. Never block.
  5. Lint, commit artifacts and show final status

    Run node <skill-dir>/scripts/lint-features.mjs beat/changes/<name>/features/*.feature (only when gherkin was written) and node <skill-dir>/scripts/validate-beat.mjs --file beat/changes/<name>/status.yaml (see references/lint-tools.md). Fix every error before committing; warnings are advisory here because tests do not exist yet.

    Commit the change directory and every living-documentation file this run wrote or modified — they are one unit of work:

    git add beat/changes/<name>/
    git add docs/adr/NNNN-<slug>.md   # each ADR written at the ADR gate, by file name
    git add docs/adr/<index-file>     # only if the project keeps an ADR index there and this run updated it
    git add GLOSSARY.md           # glossary entries from the four-challenge check
    git add beat/ARCHITECTURE.md      # if the hub suggestion was accepted
    git commit
    

    Stage files by name, never docs/adr/ as a directory: a path is staged when git status shows it and this run wrote it; a path that is absent, unchanged, or was modified by the user outside this run stays unstaged. Leaving an ADR or glossary entry uncommitted while the change directory is committed splits the work across two commits — or loses it.

    Use a descriptive message, e.g. "design(<name>): add spec artifacts".

    Update phase to the latest completed spec artifact in status.yaml.

    ## Design Complete: <change-name>
    
    Created:
    - proposal.md (or skipped)
    - features/*.feature (or skipped if Technical option)
    - design.md (or skipped)
    
    Preset: <preset>  Route: <route>/<node> (or "standalone")
    Tasks: pending (run `/beat:plan` to create execution plan)
    
    Spec artifacts ready! Review them, then run `/beat:plan` for task breakdown.
    

    Then end with the handoff block from references/handoff-report.md (next: /beat:plan <name>). When decision briefs were written, print every brief in full above the block, and set decision: D1 (or D1,D2), blocked-on: decision — <one line> and next to this same command.

Guardrails

  • Gherkin is mandatory by default -- only skip for purely technical changes (option 4: Technical)
  • Ask upfront which artifacts to include (don't ask per artifact)
  • If change already exists with some artifacts done, only create remaining
  • If context is critically unclear, ask -- but prefer reasonable defaults to keep momentum
  • Verify each artifact file exists after writing before proceeding
  • Tasks are NOT created in this skill — they are handled by /beat:plan
  • Always write preset to status.yaml — later phases read it to decide their strength
  • Never copy implementation code from a prototype/<node-id> branch into the change; only stories and the approved-variant note carry over

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/kirkchen/beat/design">View design on skillZs</a>