alexbruno/dev-skills

spec-driven-workflow

Default software engineering workflow using a workflow/ directory with optional UPSTREAM.md and VALIDATION.md alongside SPEC.md, PLAN.md, TASKS.md, and REVIEW.md.

ソースを見る

使い方

  1. インストールコマンドをコピーし、自分の環境へ導入する前にソースを確認します。
  2. 必要なツール、認証情報、対応環境を原文で確認します。
  3. 入力と成果物を指定し、出力を資料と照合します。
npx skills add https://github.com/alexbruno/dev-skills --skill spec-driven-workflow

開始前の確認

  • 導入にはモデル契約、API枠、ファイルへのアクセス許可は含まれません。
  • スター数や導入数は活動の指標であり、独立した品質・安全性試験ではありません。
リポジトリの原文

見出し、例、コード、表、リンク、参照画像を含む原文を表示しています。

Spec-Driven Workflow

Adopt this workflow as the standard software engineering process for any non-trivial change. Do not jump straight into writing code; follow the gated lifecycle below using the workflow/ directory to separate why/value (UPSTREAM.md), what needs to change (SPEC.md), how it will be built (PLAN.md), who executes independent pieces (TASKS.md), what needs attention after implementation (REVIEW.md), and whether the delivered value meets product expectations (VALIDATION.md).

Standard Operating Flow

Follow these phases in order:

  1. Discover & Frame (`UPSTREAM.md`, conditional) — Capture product intent, user value, priority, or a prioritized mini-backlog of evolutions/bugs (typically owned by the product-owner role) before technical specification.
  2. Specify (`SPEC.md`) — Define the problem, scope, constraints, and acceptance criteria (consuming UPSTREAM.md when present) before designing or coding.
  3. Plan (`PLAN.md`) — Map the technical approach, affected files, ordered steps, and verification strategy.
  4. Shard (`TASKS.md`, conditional) — Break the plan into trackable tasks only when complexity, multi-scope work, or parallel execution warrants it.
  5. Implement — Execute against PLAN.md (or TASKS.md), keeping artifact statuses current as work progresses.
  6. Review (`REVIEW.md`) — Record code review findings (human or agent) and resolve blockers/major issues before completion.
  7. Validate (`VALIDATION.md`, conditional) — Hand the approved delivery back to the Product Owner (or stakeholder) with plain-language summary and validation scenarios to confirm product value before cleanup.
Trivial changes exception: Skip workflow/ artifacts only for trivial, self-contained edits (e.g., typo fixes, single-line formatting, or minor comment updates) where specification and planning add no value.

Directory Layout

By default, create artifacts at the repository root under workflow/:

text
workflow/
├── UPSTREAM.md   # Optional: Product Owner backlog, product intent, and Ready brief
├── SPEC.md       # Required for any non-trivial change
├── PLAN.md       # Required before implementation starts
├── TASKS.md      # Optional: only for large plans or parallel/async agent work
├── REVIEW.md     # Created during human or agent code review
└── VALIDATION.md # Optional: Architect-to-PO delivery handoff and value sign-off

If multiple independent initiatives run concurrently in the same repository, scope each one under workflow/<change-slug>/ instead of overwriting root files.

If the workflow/ directory or any required artifact does not exist yet, create the directory and initialize the missing files automatically using the templates in ./resources/.

Version Control (.gitignore)

The workflow/ directory contains local process-management and guidance artifacts and must never be tracked by Git:

  • Ensure workflow/ is listed in the repository's .gitignore (add it automatically when initializing workflow/ if missing).
  • Never stage (git add) or commit workflow/ or any files inside it. If workflow/ is somehow already tracked, warn the user before untrack/cleanup operations.

Artifact Lifecycle

0. workflow/UPSTREAM.md — Capture Product Intent & Backlog (Conditional)

Create or update UPSTREAM.md when a Product Owner (or stakeholder) wants to frame a new feature, improvement, or bug fix—or maintain a prioritized mini-backlog of software evolutions—before engineering specification begins.

  • Purpose: Separate product discovery, priority, and user value (why and who) from technical design (SPEC.md).
  • Template: Start from UPSTREAM.md.
  • Rules:
  • Maintain an ordered Upstream Backlog table for candidate evolutions, features, and bug reports (Idea, Refining, Ready, In Downstream, Done).
  • Complete the Active Demand Brief and Definition of Ready (DoR) before handing an item off to SPEC.md.
  • Keep UPSTREAM.md free of technical implementation details (file paths, schemas, or code).

1. workflow/SPEC.md — Define the Change

Create SPEC.md first for any new feature, bug fix, or architectural change.

  • Purpose: Align on scope, behavior, constraints, and acceptance criteria before writing code.
  • Template: Start from SPEC.md.
  • Rules:
  • State both Goals and Non-Goals to prevent scope creep.
  • Write testable Acceptance Criteria so completion is objective.
  • For bug fixes, document reproduction steps, expected vs. actual behavior, and root cause (once known).

2. workflow/PLAN.md — Map Execution Steps

Create PLAN.md once SPEC.md is clear.

  • Purpose: Translate the specification into concrete, ordered engineering steps.
  • Template: Start from PLAN.md.
  • Rules:
  • Reference SPEC.md requirements; do not duplicate the full spec.
  • List affected files/modules, ordered implementation steps, and a concrete verification strategy (tests, linters, manual checks).
  • Highlight risks, migrations, or rollback considerations if applicable.

3. workflow/TASKS.md — Shard Large or Parallel Work (Conditional)

Create TASKS.md only when at least one of these conditions holds:

  1. The PLAN.md is too large or comprehensive to execute cleanly in a single pass.
  2. The PLAN.md spans two or more distinct project scopes (e.g., frontend, backend, infra, or multiple packages), task types (feature, bugfix, refactor, docs), or independent deliverables that benefit from separate tracking.
  3. Work can be split into independent units executed in parallel or asynchronously by different agents or contributors.
  • Template: Start from TASKS.md.
  • Rules:
  • Skip TASKS.md for small, linear changes where PLAN.md is sufficient.
  • Every task must specify an ID, status (pending, in_progress, blocked, done), dependencies, owned files/scope (to avoid merge conflicts between parallel agents), and clear done criteria.
  • Keep task statuses updated as work progresses.

4. workflow/REVIEW.md — Record Code Review Findings

Create or update REVIEW.md when a human or reviewing agent inspects the implemented changes.

  • Purpose: Centralize actionable review observations that require attention before merging.
  • Template: Start from REVIEW.md.
  • Rules:
  • Categorize every observation by severity (blocker, major, minor, question).
  • Point to exact file paths, line ranges, or symbols, and explain why the issue matters.
  • Track resolution status (open, resolved, wontfix) so nothing is lost across review rounds.

5. workflow/VALIDATION.md — Product Delivery Validation (Conditional)

Create VALIDATION.md after REVIEW.md is approved whenever UPSTREAM.md was used or a Product Owner / stakeholder needs a structured handoff to validate the delivered value.

  • Purpose: Translate the completed engineering delivery back into plain-language product outcomes, validation steps, and formal acceptance sign-off.
  • Template: Start from VALIDATION.md.
  • Rules:
  • Prepared by the Architect (or lead engineer) with a Delivery Summary, Upstream Value Mapping, and observable How to Validate scenarios.
  • Reviewed and signed off by the Product Owner (Approved or Changes Requested) before closing the cycle.

Verification & Cleanup

Before considering the workflow complete:

  1. Every acceptance criterion in workflow/SPEC.md is satisfied and verified by tests or explicit checks.
  2. All steps in workflow/PLAN.md (and workflow/TASKS.md, if used) are completed or explicitly deferred.
  3. All blocker and major items in workflow/REVIEW.md are marked resolved (or wontfix with rationale).
  4. If workflow/VALIDATION.md is used, the Product Owner has marked it Approved (and updated any UPSTREAM.md backlog item status to Done).
  5. Ask the user for final sign-off and cleanup: Once the plan, tasks (if any), review, and validation (if used) are complete, explicitly ask the user if everything is ready and whether the workflow/ artifacts can be cleaned up.
  • Never delete the root workflow/ directory or its root files (UPSTREAM.md, SPEC.md, PLAN.md, TASKS.md, REVIEW.md, VALIDATION.md).
  • When the user confirms cleanup, clear/reset the contents of the root files (e.g., emptying them or resetting them to their blank templates) while keeping the directory and files intact. If UPSTREAM.md holds ongoing backlog items the user wants to keep, preserve the backlog table and clear only the completed demand brief.
  • Exception: Subdirectories created inside workflow/ by agents working in parallel on independent executions (e.g., workflow/<change-slug>/) may be deleted upon user confirmation.
同じリポジトリから

関連する Skills

すべての Skills
alexbruno
コミュニティ

architect-worker

Role-based multi-agent software engineering pattern separating high-level architecture, specification, planning, and code review (Architect) from focused code implementation and verification (Worker). Use this skill whenever assigned the Architect or Worker role (in any language), or when coordinating work between planning/review agents and implementation agents via workflow/.

1時間の導入数
1
GitHub Stars
0
更新日
11月13日
alexbruno
コミュニティ

changelog-management

Maintain and update a standardized root CHANGELOG.md following Keep a Changelog and Semantic Versioning. Use this skill to initialize or update changelog entries, categorize changes, prepare release cuts, and proactively prompt the user when notable changes warrant updating the changelog.

1時間の導入数
1
GitHub Stars
0
更新日
11月13日
alexbruno
コミュニティ

code-review

Perform structured, multi-dimensional code reviews aligned with the spec-driven-workflow (workflow/SPEC.md, workflow/PLAN.md, workflow/REVIEW.md). Use this skill after implementing a feature or bug fix, before merging a PR, or when reviewing changes written by another agent or human.

1時間の導入数
1
GitHub Stars
0
更新日
11月13日
alexbruno
コミュニティ

code-simplification

Simplify code for human readability, clarity, and directness without changing behavior. Use this skill after implementing a feature, during refactoring, or when addressing code review feedback—especially when code feels over-engineered, deeply nested, or takes unnecessary detours to do simple things.

1時間の導入数
1
GitHub Stars
0
更新日
11月13日