ClawHub

Spec Workflow Guide

Workflows

Use when medium-to-large changes need explicit requirements, technical design, and task planning before implementation, especially for multi-module work, unclear acceptance criteria, or architecture-heavy requests.

Install

openclaw skills install spec-workflow-guide

Standalone Install Note

If this environment only installed the current skill, start from the CloudBase main entry and use the published cloudbase/references/... paths for sibling skills.

  • CloudBase main entry: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md
  • Current skill raw source: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/spec-workflow/SKILL.md

Keep local references/... paths for files that ship with the current skill directory. When this file points to a sibling skill such as auth-tool or web-development, use the standalone fallback URL shown next to that reference.

Spec Workflow

Activation Contract

Use this first when

  • The request is a new feature, multi-step product change, cross-module integration, or architecture/design task.
  • Acceptance criteria are unclear and need to be made explicit before implementation.
  • The work involves multiple files, user flows, database design, or UI design that needs staged confirmation.

Read before writing code if

  • You are unsure whether the task should go straight to coding or should first go through requirements, design, and task planning.
  • The request mentions a new page, a new system, a redesign, a workflow, or a multi-module refactor.

Then also read

  • Frontend page or visual design work -> ../ui-design/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ui-design/SKILL.md)
  • Advanced data-model work -> ../data-model-creation/SKILL.md (standalone fallback: https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/data-model-creation/SKILL.md)

Do NOT use for

  • Small bug fixes with clear scope.
  • One-file documentation updates.
  • Straightforward config changes.
  • Tiny refactors where the user already gave exact implementation instructions.

Common mistakes / gotchas

  • Jumping into coding before acceptance criteria are explicit.
  • Skipping user confirmation between requirements, design, and tasks.
  • Writing vague tasks that do not map back to user-visible outcomes.
  • Treating UI work as purely technical implementation without clarifying design intent.

Minimal checklist

  • Decide whether the change really needs the full spec flow.
  • If yes, stop and produce requirements first.
  • If the change is small, low-risk, and acceptance is already clear, allow direct execution without forcing spec artifacts.
  • Use EARS-style acceptance criteria.
  • Get confirmation before moving to the next phase.

When to use this skill

Use this workflow for structured development when you need to:

  • Define or refine a new feature
  • Design complex architecture
  • Coordinate changes across modules
  • Plan database or UI-heavy work
  • Improve requirement quality and acceptance boundaries

Decision rule

Use the full workflow when

  • The task is medium or large
  • The impact spans multiple modules
  • Acceptance boundaries are fuzzy
  • The user wants disciplined planning before implementation

Skip the full workflow when

  • The task is small, low-risk, and already precise
  • Goal, scope, and acceptance are already clear enough to execute directly
  • The user explicitly wants a direct code change with no planning phase

Core workflow

Phase 1: Requirements

Create specs/<spec_name>/requirements.md.

What to do:

  • Restate the problem and scope
  • Write user stories
  • Write acceptance criteria in EARS style
  • Clarify business rules, constraints, and non-goals

EARS pattern:

While <optional precondition>, when <optional trigger>, the <system name> shall <system response>

Example:

When the user submits the form, the booking system shall validate required fields before creating the record.

Phase 2: Design

Create specs/<spec_name>/design.md.

What to do:

  • Describe architecture and module boundaries
  • Explain technology choices and trade-offs
  • Define data model, API, security, and testing strategy as needed
  • Use Mermaid only when a diagram materially improves clarity

Phase 3: Tasks

Create specs/<spec_name>/tasks.md.

What to do:

  • Break the design into executable tasks
  • Keep tasks specific and reviewable
  • Link each task back to the relevant requirement
  • Update task status as work progresses

Task format:

# Implementation Plan

- [ ] 1. Task title
  - Specific work item
  - Another concrete step
  - _Requirement: 1

Phase 4: Execution

Only start implementation after the user confirms the task plan.

During execution:

  • Keep task status current
  • Finish one meaningful unit at a time
  • Preserve traceability from change -> task -> requirement

Working rules for the agent

  1. Ask follow-up questions when the request is underspecified; do not guess core product behavior.
  2. Require confirmation between requirements, design, and task breakdown.
  3. Pull in ui-design early when the change includes end-user pages or visual decisions.
  4. Keep documents concise but testable.
  5. Prefer user-visible outcomes over implementation-detail task names.

Output expectations

  • requirements.md -> problem, scope, user stories, EARS acceptance criteria
  • design.md -> architecture, technical approach, data/API/security/test notes
  • tasks.md -> actionable implementation checklist tied to requirements
More in Workflows