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日