bubbles-scope-workflow-runtime

Guides creation and management of Bubbles scope artifacts with DoD, Test Plan, and DAG rules.

1|Updated Mar 17, 2026
One-click install
npx skills add https://github.com/pkirsanov/bubbles --skill bubbles-scope-workflow-runtime-pkirsanov
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: bubbles-scope-workflow-runtime
Source: https://github.com/pkirsanov/bubbles/tree/main/skills/bubbles-scope-workflow-runtime
Command: npx skills add https://github.com/pkirsanov/bubbles --skill bubbles-scope-workflow-runtime-pkirsanov

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Multi-scope feature work in the Bubbles framework fails lint and state-transition gates when scope files use the wrong layout, mismatched Test Plan and Definition-of-Done rows, or violated isolation rules. This Skill encodes the exact conventions so scope artifacts pass state-transition-guard.sh and artifact-lint.sh on the first attempt. ## Core Features & Use Cases - Layout and DoD Decisions: Choose between a single scopes.md file (≤5 scopes) and per-scope directories (6+ scopes), and between single-file and tiered DoD formats. - Test Plan / DoD Parity Enforcement: Ensures Test Plan row counts match DoD test items, includes stress-test rows when latency SLAs exist, and applies the v4.1.0 scope-kind taxonomy (runtime-behavior, contract-only, deploy-pointer, and others) to control E2E enforcement. - DAG-Based Work Selection: Picks the next scope by dependency readiness, enforces per-scope isolation, and surfaces pre-existing bugs before starting new work. - Use Case: When splitting a feature into eight scopes, use this Skill to create specs/<NNN>/scopes/_index.md plus per-scope directories with valid Gherkin scenarios, Test Plans, and tiered DoD sections that pass artifact lint. ## Quick Start Ask the agent to create the scopes for a new feature in specs/ following the Bubbles scope workflow rules, including the Test Plan and tiered Definition of Done.

Frequently Asked Questions about bubbles-scope-workflow-runtime

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure scopes for a feature in the Bubbles framework?▼

Use a single specs/<NNN>/scopes.md file when the feature has five or fewer scopes. For six or more scopes, create specs/<NNN>/scopes/_index.md plus a per-scope directory scopes/NN-name/scope.md for each scope.

What sections are required in every Bubbles scope file?▼

Every scope needs a Status field, a Depends On list forming a cycle-free DAG, Gherkin Given/When/Then scenarios, an implementation plan, a Test Plan table with file paths and commands, and a tiered Definition of Done with Core Items plus a Build Quality Gate.

Why does artifact-lint reject my scope's Test Plan?▼

The lint enforces Test Plan and DoD parity, so the Test Plan row count must equal the number of test-related DoD items. It also rejects catch-all DoD items like "all tests passing" and pre-checked boxes without real execution evidence.

When is a stress test row required in the Test Plan?▼

A stress row is required whenever the scope's Gherkin scenarios or design define a latency or throughput target, such as p95 under a threshold. The DoD must then include a matching stress evidence item per gate G026.

How does DAG-based scope pickup decide what to work on next?▼

List scopes with Status Not Started whose Depends On entries are all Done, then prefer the smallest, most foundational scope. Also scan the feature's bugs directory for in-progress bugs and surface them before starting new scope work.

What is the Scope-Kind header used for in Bubbles scopes?▼

Scope-Kind declares the scope's evidence type, with valid values like runtime-behavior, contract-only, deploy-pointer, ci-config, docs-only, and bootstrap. Only runtime-behavior scopes enforce the three-row E2E DoD and Test Plan requirement.