Unified workflow system with Stage A/B/C complexity routing (Spec → Dev → Exec)

version
1.0.0

Install

/plugin install workflow@agent-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add TomazWang/agent-toolkit.

Contents

Discovered from source

Skills 14

Behavior-Driven Development (BDD) Skill

When to Use

Use this skill when:

  • Defining acceptance criteria for features
  • Creating executable specifications
  • Translating requirements into testable scenarios
  • Working with stakeholders on feature definitions
  • Part of the unified workflow process

Overview

BDD bridges the gap between business requirements and technical implementation using natural language scenarios that become executable tests.

BDD Process

1. Discovery Phase

Work with stakeholders to discover scenarios:

Ask:

  • What is the business value?
  • Who are the users/actors?
  • What are the main scenarios?
  • What can go wrong?
  • What edge cases exist?

2. Scenario Definition

Write scenarios in Given-When-Then format:

Feature: User Authentication

  Scenario: Successful login with valid credentials
    Given a registered user with email "user@example.com" and password "SecurePass123"
    When the user submits the login form with correct credentials
    Then the user should be redirected to the dashboard
    And the user session should be created
    And the user should see a welcome message

  Scenario: Failed login with invalid password
    Given a registered user with email "user@example.com"
    When the user submits the login form with incorrect password
    Then the user should see an error message "Invalid credentials"
    And the user should remain on the login page
    And no session should be created

  Scenario: Account lockout after multiple failed attempts
    Given a registered user with email "user@example.com"
    And the user has failed to login 4 times
    When the user submits the login form with incorrect password again
    Then the account should be locked for 15 minutes
    And the user should see "Account temporarily locked"

3. Examples and Data Tables

Use examples for multiple test cases:

  Scenario Outline: Password validation
    Given a user registration form
    When the user enters password "<password>"
    Then the validation should show "<result>"

    Examples:
      | password    | result                          |
      | abc         | Too short (min 8 characters)   |
      | abcdefgh    | Missing uppercase letter       |
      | Abcdefgh    | Missing number                 |
      | Abcdefg1    | Valid                          |
      | Abc123!@#   | Valid                          |

4. Acceptance Criteria Checklist

For each feature, create acceptance criteria:

## Acceptance Criteria

- [ ] User can login with valid email and password
- [ ] Invalid credentials show appropriate error
- [ ] Account locks after 5 failed attempts
- [ ] Locked account shows lockout duration
- [ ] Session expires after 24 hours
- [ ] Logout clears session properly
- [ ] Remember me keeps session for 30 days

5. Integration with Workflow

In Spec Phase:

1. Define feature specification (SDD)
2. Write BDD scenarios (this skill)
3. Get stakeholder approval

In Implementation Phase:

1. For each scenario:
   - Write step definitions (glue code)
   - Implement steps using TDD
   - Verify scenario passes
2. Ensure all acceptance criteria met

BDD Scenario Structure

Given (Context)

  • Initial state
  • Preconditions
  • Setup data
  • User context

When (Action)

  • User action
  • System event
  • API call
  • Trigger

Then (Outcome)

  • Expected result
  • State changes
  • Side effects
  • Assertions

And/But (Additional steps)

  • Multiple givens, whens, or thens
  • Additional context or assertions

Best Practices

DO:

  • Write from user's perspective
  • Use business language, not technical jargon
  • Focus on behavior, not implementation
  • Keep scenarios independent
  • Use concrete examples
  • Cover happy path and edge cases

DON'T:

  • Include implementation details
  • Make scenarios too long (>5-7 steps)
  • Create dependencies between scenarios
  • Use vague language
  • Test technical details (use unit tests)

Tools Integration

Gherkin/Cucumber:

# Feature files in features/ directory
features/
├── authentication.feature
├── user_profile.feature
└── payment.feature

Jest/Vitest:

describe('User Authentication', () => {
  it('should login with valid credentials', () => {
    // Given
    const user = createUser({ email: 'user@example.com', password: 'SecurePass123' });

    // When
    const result = login(user.email, 'SecurePass123');

    // Then
    expect(result.success).toBe(true);
    expect(result.redirectTo).toBe('/dashboard');
  });
});

Playwright/Cypress:

test('User can login successfully', async ({ page }) => {
  // Given
  await page.goto('/login');

  // When
  await page.fill('[name="email"]', 'user@example.com');
  await page.fill('[name="password"]', 'SecurePass123');
  await page.click('button[type="submit"]');

  // Then
  await expect(page).toHaveURL('/dashboard');
  await expect(page.locator('.welcome')).toBeVisible();
});

Example Workflow Integration

# 1. Start workflow
/workflow:start-development-workflow "Add user authentication"

# 2. Create spec (SDD)
/workflow:create-workflow-spec
→ Creates OpenAPI spec for auth endpoints

# 3. Define behaviors (BDD)
/workflow:behavior-driven
→ Creates authentication.feature with scenarios

# 4. Get approval
→ Review spec + scenarios with stakeholders

# 5. Implement (TDD)
/workflow:implement
→ For each scenario:
  - Write failing test (RED)
  - Implement (GREEN)
  - Refactor (REFACTOR)

# 6. Verify
→ All scenarios pass
→ Acceptance criteria met

Output Format

BDD Scenarios File:

Save to: features/<feature-name>.feature
Or: docs/bdd/<feature-name>.md

Include:
- Feature description
- User stories
- Scenarios (Given-When-Then)
- Examples/data tables
- Acceptance criteria checklist

Error Handling

  • Ambiguous scenarios: Ask for clarification
  • Too technical: Refactor to business language
  • Missing edge cases: Suggest additional scenarios
  • Conflicting requirements: Flag for stakeholder review

Integration Points

  • SDD (spec-driven): Specs define what, BDD defines how users interact
  • TDD (test-driven): BDD scenarios become test suites
  • Task Management: Each scenario can become a task
  • Documentation: Scenarios serve as living documentation

Workflow Status Command

Show current workflow state, progress, and next steps.

Process

1. Read Workflow State

Check .claude/workflow/current.json for active workflow.

2. Display Summary

═══════════════════════════════════════
📊 Workflow Status
═══════════════════════════════════════

Feature: payment-processing
Block: B (Spec Change + TDD)
Phase: Testing (3/5 tests passing)
Started: 2 hours ago

Progress:
✅ Spec change created
✅ Test cases generated (12 total)
✅ Implementation plan created
🔄 TDD implementation (60% complete)
⏳ Validation pending

Tasks:
✅ 15 completed
🔄 3 in progress
⏳ 2 pending
━━━━━━━━━━━━━━━━━━━━━━━━ 75%

Next Steps:
1. Fix failing tests (2 remaining)
2. Complete refactoring phase
3. Run full test suite
4. Deploy to staging

Integrations:
✓ task-management (tracking 20 tasks)
✓ tdd-workflow (active)
✓ OpenSpec (using openspec/ structure)

3. Verbose Mode (if --verbose)

Show additional details:

  • Full task list with status
  • Test results breakdown
  • Files modified
  • Commits made
  • Time spent per phase

No Active Workflow

If no workflow active:

No active workflow

To start a new workflow:
  /workflow:start-development-workflow "your requirement"

Or use specific blocks:
  /workflow:create-workflow-spec create "feature"  (Stage A)
  /workflow:plan-simple-workflow "task"             (Stage C)

Example Output

Stage A in Progress

Feature: multi-tenant-architecture
Block: A (Spec + Meta-Validation)
Phase: Meta-testing
Started: 30 minutes ago

Progress:
✅ Research completed
✅ Initial spec created
🔄 Meta-testing in progress
  ✅ PoC Test 1: Database isolation
  ✅ PoC Test 2: Tenant switching
  ⏳ Manual Q: Scaling strategy
⏳ Spec iteration pending
⏳ Finalization pending

Next: Answer scaling questions, iterate spec

Stage B in Progress

Feature: email-notifications
Block: B (Spec Change + TDD)
Phase: Implementation
Started: 1 hour ago

Progress:
✅ Spec change created
✅ Test cases generated (8)
✅ Plan created (12 steps)
🔄 TDD implementation
  ✅ RED: 8/8 tests failing
  🔄 GREEN: 6/8 tests passing
  ⏳ REFACTOR pending

Tasks: 12 total
✅ 8 completed | 🔄 2 in progress | ⏳ 2 pending

Next: Fix 2 failing tests, then refactor

Stage C in Progress

Feature: fix-login-button
Block: C (Simple Planning)
Phase: Implementation
Started: 15 minutes ago

Progress:
✅ Plan created (4 steps)
✅ Tasks created (4)
🔄 Implementation in progress

Tasks: 4 total
✅ 3 completed | 🔄 1 in progress

Next: Complete final task, test, done!

Implementation Notes

Read state from:

  • .claude/workflow/current.json (workflow state)
  • .claude/tasks/ (task-management integration)
  • TodoWrite state (built-in tasks)
  • Git log (commits since workflow start)

Calculate progress:

  • Phase completion
  • Task completion percentage
  • Test pass rate
  • Time estimates

Format for clarity:

  • Use emoji indicators (✅🔄⏳❌)
  • Show progress bars
  • Highlight next steps
  • Color code by priority (if terminal supports)

Workflow Spec Command

Manually enter Stage A (Spec + Meta-Validation) workflow.

Subcommands

create

Start Stage A spec creation process.

Process:

  1. Research existing docs/specs/code
  2. Create initial spec document
  3. Run meta-testing automatically
  4. Iterate based on results
  5. Ready for finalize

Output location:

  • If openspec/ exists: openspec/changes/[feature]/proposal.md
  • Otherwise: docs/specs/[feature].md

validate

Run meta-tests on current spec (if in Stage A).

Meta-testing:

  • Auto-generated PoC tests
  • Manual validation questions
  • Complexity checks
  • Feasibility validation

finalize

Finalize current spec and transition to Stage B.

Process:

  1. Verify meta-tests passed
  2. Create final spec document (design.md)
  3. Transition to Stage B for implementation
  4. Or prompt: "Ready to implement (Stage B)?"

Example Usage

User: /workflow:create-workflow-spec create "Payment processing"

→ Starting Stage A: Spec Creation

Research phase:
- Reading existing code...
- Checking for related specs...

Creating initial spec:
openspec/changes/payment-processing/proposal.md

[Spec draft created]

Running meta-tests:
✓ Auto PoC: Stripe API connection
✓ Auto PoC: Test payment creation
? Manual: Webhook security?
? Manual: Error handling strategy?

[Iterate based on feedback]

User: /workflow:create-workflow-spec finalize

→ Finalizing spec:
openspec/changes/payment-processing/design.md

✅ Spec finalized
Ready to implement (Stage B)? [Y/n]

See block-a-spec-validation skill for full workflow details.

Meta-Testing Skill

Validates specifications before full implementation (Stage A).

Purpose

Catch bad specs BEFORE writing production code:

  • Is this spec actually implementable?
  • Does it fulfill the requirements?
  • Is the design unnecessarily complex?
  • Will this work at scale?

Two Approaches (Both Used)

1. Auto-Generated PoC Tests

Generate minimal proof-of-concept code:

Spec: Use Stripe for payments

PoC Test:
→ Generate: Minimal Stripe client
→ Test: Can we connect to API?
→ Test: Can we create test charge?
→ Run and verify

Results:
✅ Connection works
✅ Test charge succeeds
→ Spec is viable

When to use:

  • Technical integration questions
  • "Can we connect to X?"
  • "Does this API do what we need?"
  • "Will this pattern work?"

2. Manual Validation Questions

Ask critical questions user must answer:

Spec: Multi-tenant with database-per-tenant

Questions:
? Does this scale to 1000 tenants?
  → User answer → Might not (connection limits)
  → Recommendation: Use shared schema instead

? Is this complexity justified?
  → User answer → Maybe not for MVP
  → Recommendation: Start simpler

Updated spec based on answers

When to use:

  • Scalability questions
  • Complexity tradeoffs
  • Business decisions
  • "What if" scenarios

Case-by-Case Decision

System decides which approach:

Technical validation → Auto PoC
Business/scale validation → Manual Questions
Both often needed → Use both

PoC Test Generation

Template:

# PoC Test: [What we're validating]
# Generated: [timestamp]
# Spec: [spec-reference]

[Minimal test code]

# Expected: [what should happen]
# Actual: [what happened]
# Result: PASS/FAIL

Run and report:

Meta-Test Results:
✅ PoC-1: API connection (PASS)
✅ PoC-2: Basic operation (PASS)
⚠️ PoC-3: Load test (SLOW - 500ms, expected <100ms)

Recommendations:
- Consider caching for PoC-3
- Otherwise spec validated

Complexity Check

Red flags for over-complexity:

  • 10 components for simple feature

  • 5 integration points

  • Custom solution when standard exists
  • "Microservices" for small app

Suggest simplification:

⚠️ Complexity Alert

Spec proposes: 8 microservices for email notifications

Recommendation: Start with single service
- Can always split later
- Easier to debug
- Faster to implement

Simplify spec? [Y/n]

Iteration Loop

1. Create spec
2. Run meta-tests (auto + manual)
3. Identify issues
4. Update spec
5. Re-test
6. Repeat until validated
7. Finalize

Success Criteria

Spec is ready when:

  • ✅ All PoC tests pass
  • ✅ Critical questions answered
  • ✅ Complexity justified
  • ✅ No obvious blockers
  • ✅ Requirements fulfilled

Then move to Stage B for implementation.

OpenSpec Integration Skill

When to Use

This skill auto-activates when:

  • openspec/ directory detected in project
  • User is working on API specifications
  • SDD workflow needs spec format
  • Part of the unified workflow

Overview

OpenSpec is a fluid, iterative approach to API specification that emphasizes:

  • Fluid not rigid: Specs evolve with understanding
  • Iterative not waterfall: Continuous refinement
  • Easy not complex: Simple, readable format

OpenSpec Philosophy

From Fission-AI/OpenSpec:

"Traditional spec-first development often fails because:

  • Specs become outdated immediately
  • They're too rigid for changing requirements
  • They're hard to maintain

OpenSpec solves this by making specs:

  • Living documents that evolve
  • Easy to update iteratively
  • Tightly integrated with code"

Directory Structure

Detect and use OpenSpec structure:

openspec/
├── spec/                  # API specifications
│   ├── api.yaml          # Main OpenAPI spec
│   ├── endpoints/        # Endpoint details
│   └── schemas/          # Schema definitions
├── plan/                  # Planning documents (optional)
│   ├── architecture.md
│   └── decisions.md
└── examples/              # Example requests/responses
    ├── requests/
    └── responses/

Integration with Workflow

1. Auto-Detection

# Check if OpenSpec exists
if [ -d "openspec/" ]; then
  USE_OPENSPEC=true
  SPEC_DIR="openspec/spec/"
else
  SPEC_DIR="docs/api/" or "api/"
fi

2. Spec Creation (SDD Phase)

When creating specs:

# openspec/spec/api.yaml
openapi: 3.1.0
info:
  title: User Authentication API
  version: 0.1.0
  description: |
    Initial spec - will evolve as we learn more.

    Status: DRAFT
    Last updated: 2026-02-09

paths:
  /auth/login:
    post:
      summary: User login
      description: |
        Authenticate user with email/password.

        TODO: Decide on token format (JWT vs session)
        TODO: Rate limiting strategy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials

# Version: 0.1.0 - Initial draft
# Version: 0.2.0 - Added rate limiting (pending)
# Version: 1.0.0 - Production ready (target)

Iterative evolution:

## Spec Evolution Log

### v0.1.0 (2026-02-09)
- Initial draft based on requirements
- Open questions: token format, rate limiting

### v0.2.0 (2026-02-10)
- Decided: JWT tokens (30min access + 7day refresh)
- Added: Rate limiting (5 attempts per 15min)
- Refined: Error response format

### v0.3.0 (2026-02-11)
- Added: OAuth2 support
- Changed: Session management approach

3. Workflow Integration

Spec-first workflow:

# 1. Start with OpenSpec
/workflow:start-development-workflow "Add payment processing API"

# Auto-detects openspec/ directory

# 2. Create initial spec (fluid)
→ Creates openspec/spec/payment.yaml
→ Version 0.1.0 - DRAFT
→ Includes TODOs and open questions

# 3. BDD scenarios from spec
→ Generates features/payment.feature
→ Based on spec endpoints and schemas

# 4. Implement iteratively
→ For each endpoint:
  - TDD implementation
  - Update spec as we learn
  - Mark sections STABLE when complete

# 5. Spec evolves
→ v0.1.0 DRAFT → v0.5.0 WORKING → v1.0.0 STABLE

4. Fluid Spec Updates

As implementation reveals new insights:

# BEFORE (v0.1.0 - assumptions)
/payments:
  post:
    summary: Process payment
    # TODO: What payment methods?
    # TODO: How to handle failures?

# AFTER (v0.3.0 - learned from implementation)
/payments:
  post:
    summary: Process payment
    description: |
      Supports: credit card, PayPal, Apple Pay

      LEARNED: Need idempotency keys for retry safety
      LEARNED: Webhook callbacks for async processing

    parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: Unique key for safe retries

OpenSpec vs Traditional Spec

Traditional (rigid):

1. Write complete spec upfront
2. Spec is "frozen"
3. Implementation must match spec exactly
4. Changes require formal approval
5. Spec becomes outdated quickly

OpenSpec (fluid):

1. Start with minimal spec (DRAFT)
2. Implement and learn
3. Update spec as understanding grows
4. Mark stable sections
5. Spec stays current with code

Status Markers

Use status markers in specs:

paths:
  /users:
    get:
      # STATUS: STABLE - Don't change without discussion
      summary: List users

  /users/{id}:
    put:
      # STATUS: WORKING - Still refining
      summary: Update user

  /admin/reports:
    get:
      # STATUS: DRAFT - Open questions
      # TODO: What metrics?
      # TODO: Date range format?
      summary: Generate reports

Integration Points

With SDD Workflow:

  • Auto-detect openspec/ directory
  • Use OpenSpec format for all API specs
  • Follow iterative refinement process

With BDD Workflow:

  • Generate BDD scenarios from OpenSpec endpoints
  • Keep scenarios in sync with spec versions

With TDD Workflow:

  • Implement against current spec version
  • Update spec when tests reveal new requirements

With Task Management:

  • Create tasks for DRAFT sections
  • Track spec evolution through task updates

Commands

Create OpenSpec spec:

/workflow:create-workflow-spec "User API"
→ Detects openspec/ directory
→ Creates openspec/spec/user-api.yaml
→ Version 0.1.0 DRAFT
→ Includes standard sections + TODOs

Update spec iteratively:

/workflow:create-workflow-spec-update
→ Opens current spec
→ Marks changes with version bump
→ Logs evolution in spec comments

Validate spec:

/workflow:create-workflow-spec-validate
→ OpenAPI validation
→ Check status markers
→ Identify DRAFT sections needing attention

Example: Iterative Spec Evolution

Day 1: Initial spec

# v0.1.0 - DRAFT
paths:
  /auth/login:
    post:
      summary: Login endpoint
      # TODO: Decide on auth mechanism

Day 2: After BDD scenarios

# v0.2.0 - WORKING
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: Returns JWT access token
      # Decided: JWT tokens
      # TODO: Refresh token strategy?

Day 3: After TDD implementation

# v0.3.0 - WORKING
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: |
        Returns JWT access token (30min) + refresh token (7 days)

        LEARNED: Need to handle concurrent logins
        LEARNED: Should return user profile in response
      # TODO: Add rate limiting details

Day 5: After testing

# v1.0.0 - STABLE
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: |
        Authenticates user and returns JWT tokens.
        Rate limited to 5 attempts per 15 minutes.
      # STABLE: Don't change without team discussion

Best Practices

DO:

  • Start with minimal DRAFT specs
  • Update specs as you learn
  • Use status markers (DRAFT/WORKING/STABLE)
  • Log evolution in spec comments
  • Keep spec close to code

DON'T:

  • Try to design everything upfront
  • Freeze specs too early
  • Let specs drift from implementation
  • Skip status markers
  • Forget to version bump

Output

OpenSpec files:

openspec/spec/<feature>.yaml     - Main spec file
openspec/plan/<feature>.md       - Planning notes (optional)
openspec/examples/               - Request/response examples

Spec includes:

  • Version number and status
  • Evolution log
  • Open questions (TODO)
  • Learned insights
  • Status markers per endpoint

Workflow Plan Command

Manually enter Stage C (Simple Planning) workflow.

Process

  1. Research (unless skipped):

    • Quick check of relevant code
    • Understand current implementation
  2. Create Plan:

    • Break requirement into steps
    • Identify files to modify
    • Define success criteria
  3. Convert to Tasks:

    • If task-management installed: Create tasks with /task
    • Otherwise: Use TodoWrite
    • Link tasks to plan
  4. Track Implementation:

    • Tasks show in TodoWrite/task-management
    • Update as you work

Output Location

  • docs/plans/YYYY-MM-DD-[feature].md

Example Usage

User: /workflow:plan-simple-workflow "Add email validation"

Research phase:
- Reading signup form code...
- Found: No validation currently

Creating plan:
docs/plans/2026-02-05-email-validation.md

Plan:
1. Add email regex validation
2. Add error message display
3. Update tests
4. Test in browser

Converting to tasks:
✓ task-management detected
/task create "Add email regex" --project validation
/task create "Add error display" --project validation
/task create "Update tests" --project validation

Tasks created (3 total)
Ready to implement!

See block-c-simple-planning skill for full workflow details.

Spec-Driven Development Skill

Ensures API specifications are defined before implementation.

When to Use

Activate when:

  • Developing APIs
  • User mentions "API", "endpoint", "REST", "GraphQL"
  • OpenSpec integration detected

Process

1. Spec First

Before any implementation:

  • Define API contract in OpenAPI/AsyncAPI
  • Document all endpoints
  • Define request/response schemas
  • Specify authentication

2. Validate Spec

  • Syntax check
  • Completeness check
  • Breaking change detection

3. Generate from Spec

  • Server stubs (routes, handlers)
  • Client SDKs
  • Contract tests
  • API documentation

4. Implement Against Spec

  • Fill in business logic
  • Keep implementation matching spec
  • Run contract tests

5. Spec is Source of Truth

  • Update spec before changing API
  • Regenerate when spec changes
  • Catch breaking changes early

Enforcement

If user implements without spec:

⛔ API Implementation Without Spec

Spec-driven development requires specification first.

Please create OpenAPI/AsyncAPI spec:
/spec:create "API Name" --type openapi

Then implement against the spec.

This ensures APIs are designed before built.

Stage B: Development

Behavior-driven design with test-driven implementation.

Process

1. Research

  • Read existing spec (from Stage A or existing docs)
  • Understand current implementation
  • Identify what needs to change

2. Create Spec Change Document

OpenSpec format:

openspec/changes/[feature]/spec-change.md

Standard:

docs/specs/changes/[feature].md

Contents:

  • What's changing and why
  • Affected components
  • Implementation approach

3. Generate Test Cases

From spec change, create test scenarios:

# Test Cases: Email Notifications

## Unit Tests
- NotificationService.send() triggers email
- Email template renders correctly
- User preferences respected

## Integration Tests
- Event triggers notification
- Email delivers successfully
- Retry logic on failure

## Acceptance Tests
- User receives email within 30s
- Email contains correct content
- Unsubscribe link works

4. Create Implementation Plan

Break into steps:

  1. Setup email service
  2. Create NotificationService
  3. Implement email templates
  4. Add event hooks
  5. Write tests
  6. Integrate and validate

5. TDD Implementation

If tdd-workflow plugin installed:

  • Launch /tdd:start with generated tests
  • Follow RED → GREEN → REFACTOR cycle

Otherwise:

  • Guide manual TDD:
    1. Write failing tests (RED)
    2. Implement to pass (GREEN)
    3. Refactor for quality (REFACTOR)

6. Task Integration

If task-management installed:

  • Create tasks for each step: /task create ...
  • Link to workflow

Otherwise:

  • Use TodoWrite

7. Validate

All tests must pass before marking complete.

Example Flow

Stage B: Email Notifications

1. Spec change created
2. Generated 12 test scenarios
3. Created 8-step plan
4. Integrated: 8 tasks created
5. Launched TDD workflow
6. Implementation progress: 6/8 complete
7. Tests: 10/12 passing
8. Next: Fix 2 failing tests

Stage C: Execution

Task tracking, implementation, and verification.

Process

1. Quick Research (if needed)

  • Read relevant code
  • Understand current implementation
  • ~5 minutes max

2. Create Plan

Format:

docs/plans/YYYY-MM-DD-[feature].md

Structure:

# [Feature/Fix Name]

## Goal
What we're achieving

## Steps
1. [First step]
2. [Second step]
...

## Files to Modify
- file1.ts
- file2.ts

## Success Criteria
- [How we know it's done]

3. Convert to Tasks

If task-management installed:

/task create "Step 1" --project [name]
/task create "Step 2" --project [name]
...

Otherwise: Use TodoWrite:

- [ ] Step 1
- [ ] Step 2
...

4. Implement

Work through tasks with live tracking.

Keep It Simple

  • Don't over-plan
  • <8 steps total
  • Focus on getting it done
  • Can always escalate to Stage B if it grows

Example

User: /workflow:plan-simple-workflow "Add email validation"

Quick research: (30 seconds)
→ Signup form has no validation

Plan:
1. Add email regex to form
2. Show error if invalid
3. Update test
4. Manual test in browser

Tasks created (4)
→ Start implementing!

No ceremony, just useful structure.

Stage A: Specification

Complete specification workflow for complex projects with full validation.

When to Use

  • New projects or major features
  • Security-critical functionality
  • Architectural decisions needed
  • Unknown requirements
  • High risk or complexity
  • More than 15 implementation steps

Workflow Overview

SDD → BDD → TDD with Validation

  1. Spec creation (OpenSpec if available)
  2. PoC validation tests
  3. BDD scenarios
  4. TDD implementation
  5. Task tracking integration

Process

1. Research Phase

  • Read existing specs, docs, architecture
  • Understand current system
  • Identify constraints

2. Create Initial Spec

OpenSpec format (if openspec/ exists):

openspec/changes/[feature]/proposal.md

Standard format (otherwise):

docs/specs/[feature].md

Spec structure:

  • Problem statement
  • Proposed solution
  • Alternatives considered
  • Technical design
  • Success criteria
  • Risks and mitigations

3. Meta-Testing

Purpose: Validate spec is workable BEFORE implementation.

Two approaches (both used case-by-case):

A) Auto-Generated PoC Tests

Generate minimal code to test concepts:

Example: OAuth2 spec
→ Generate test: "Can we connect to OAuth provider?"
→ Create minimal client code
→ Run connection test
→ Result: ✅ PASS or ❌ FAIL → Iterate spec
B) Manual Validation Questions

Ask critical questions:

  • "Does this scale to N users?"
  • "Is complexity justified?"
  • "Are there simpler alternatives?"
  • "What could go wrong?"

Complexity Check: If design seems over-complex, simplify before finalizing.

4. Iterate Based on Results

If PoC fails or questions reveal issues:

  • Revise spec
  • Re-run meta-tests
  • Repeat until validated

5. Finalize Spec

Create final design document, then transition to Stage B for implementation.

Integration

After finalization, automatically suggest:

✅ Spec finalized!

Next: Implement with Stage B?
This will:
- Create spec change for Phase 1
- Generate test cases
- Launch TDD workflow

Proceed? [Y/n]

Workflow Start Command

You are orchestrating a development workflow. Your job is to detect complexity and route to the appropriate stage (A/B/C).

Process

Step 1: Parse Input

Extract:

  • requirement: What the user wants to build/fix
  • --stage: Force specific stage (a/b/c) if provided
  • --research-first: Do research before routing
  • --skip-research: Skip research phase

Step 2: Research Phase (if not skipped)

Quick investigation:

# Check for existing specs
ls openspec/changes/ docs/specs/ 2>/dev/null

# Check codebase structure
find . -name "*.md" -path "*/specs/*"

# Search for related code
grep -r "relevant keywords" --include="*.{js,ts,py}" | head -20

Understand:

  • Does a spec already exist for this?
  • What's the current architecture?
  • How complex is the codebase?

Step 3: Complexity Detection (if not forced)

Analyze requirement to determine Stage A/B/C:

→ Stage A (Most Complex)

Triggers:

  • Keywords: "new project", "architecture", "design", "system", "platform"
  • Multiple subsystems involved
  • No existing spec found
  • Security/compliance critical (payments, auth, data)
  • Estimated >15 steps
  • User explicitly: --stage a

Examples:

  • "Build multi-tenant SaaS"
  • "Design payment system"
  • "Architecture for microservices"
→ Stage B (Normal Complexity)

Triggers:

  • Keywords: "implement", "add feature", "refactor", "integrate"
  • Existing spec found (can create spec change)
  • Moderate scope (8-15 steps)
  • Some design needed but not architectural
  • User explicitly: --stage b

Examples:

  • "Add email notifications"
  • "Implement OAuth2"
  • "Refactor authentication"
→ Stage C (Simple)

Triggers:

  • Keywords: "fix", "update", "quick", "simple", "bug"
  • Small scope (<8 steps)
  • Single file/component
  • No design complexity
  • User explicitly: --stage c

Examples:

  • "Fix login button"
  • "Update error message"
  • "Add validation to form"

Step 4: When Unclear → Ask User

If complexity is ambiguous:

🤔 This requirement could go multiple ways.

Analyzing: "[requirement]"

Recommendation: Stage B (Normal workflow)

Reasoning:
- [Why you think Stage B]
- [What makes it unclear]

Options:
1. **Stage B: Spec Change + TDD** (Recommended)
   - Create spec change document
   - Generate test cases
   - Implement with TDD
   - ~2-4 hours

2. Stage A: Full Spec + Meta-Validation
   - Design complete architecture
   - Validate with PoC tests
   - Then implement
   - ~1-2 days

3. Stage C: Simple Planning
   - Create quick plan
   - Break into tasks
   - Implement directly
   - ~30 min - 2 hours

Which approach? [1/2/3]

Step 5: Route to Block

If Stage A:
✅ Routing to Stage A: Spec + Meta-Validation

This is a complex requirement that needs careful design.

Process:
1. Research phase (understanding context)
2. Create initial spec
3. Meta-testing (validate spec is workable)
4. Iterate based on test results
5. Finalize spec
6. → Move to Stage B for implementation

Starting Stage A workflow...

[Activate stage-spec skill]
If Stage B:
✅ Routing to Stage B: Spec Change + TDD

This is a standard feature requiring some design.

Process:
1. Research existing specs/code
2. Create spec change document
3. Generate test cases from spec
4. Create implementation plan
5. TDD workflow (RED→GREEN→REFACTOR)
6. Validate against tests

Starting Stage B workflow...

[Activate stage-dev skill]
If Stage C:
✅ Routing to Stage C: Simple Planning

This is a straightforward task.

Process:
1. Quick research (if needed)
2. Create implementation plan
3. Break into tasks (TodoWrite)
4. Implement with task tracking

Starting Stage C workflow...

[Activate stage-exec skill]

Step 6: Integration Check

Check for installed plugins:

# Check for task-management
ls ~/.claude/plugins/task-management 2>/dev/null
→ If exists: Will use /task commands for tracking

# Check for tdd-workflow
ls ~/.claude/plugins/tdd-workflow 2>/dev/null
→ If exists: Will use /tdd commands in Stage B

# Check for openspec
ls openspec/ 2>/dev/null
→ If exists: Will use OpenSpec structure

Inform user:

Integration detected:
✓ task-management → Tasks will be created
✓ tdd-workflow → TDD integration available
✓ OpenSpec → Using openspec/ structure

Step 7: Launch Workflow

Invoke appropriate skill:

  • Stage A → stage-spec skill
  • Stage B → stage-dev skill
  • Stage C → stage-exec skill

The skill takes over and executes the workflow.

Complexity Detection Examples

Example 1: Clear Stage A

User: /workflow:start-development-workflow "Build multi-tenant SaaS platform"

Analysis:
- Keywords: "build", "platform" → Complex
- Scope: Entire system → Large
- Architecture needed: Yes
- Spec exists: No

Decision: Stage A (auto, no question needed)

Output:
✅ Routing to Stage A: Spec + Meta-Validation
This is a complex architectural project requiring careful design...

Example 2: Clear Stage C

User: /workflow:start-development-workflow "Fix typo in login error message"

Analysis:
- Keywords: "fix", "typo" → Simple
- Scope: Single string → Tiny
- Steps: <5
- No design needed

Decision: Stage C (auto, no question needed)

Output:
✅ Routing to Stage C: Simple Planning
This is a quick fix...

Example 3: Unclear → Ask

User: /workflow:start-development-workflow "Improve app performance"

Analysis:
- Could be Stage A: Complete performance architecture
- Could be Stage B: Targeted optimizations
- Could be Stage C: Quick fix for specific slow query
- Ambiguous scope

Decision: Ask user

Output:
🤔 This requirement could go multiple ways.

Recommendation: Stage B (start targeted, scale up if needed)
- Profile first to identify bottlenecks
- Then optimize specific areas
- Can design full architecture if needed later

Options:
1. Stage B: Profile → Target fixes (Recommended)
2. Stage A: Design complete performance architecture
3. Stage C: Fix specific known slow parts

Which? [1/2/3]

Error Handling

No requirement provided:

Error: No requirement specified

Usage: /workflow:start-development-workflow <requirement>

Examples:
  /workflow:start-development-workflow "Add user authentication"
  /workflow:start-development-workflow "Fix login bug"

Invalid block specified:

Error: Invalid block 'x'. Must be a, b, or c.

Usage: /workflow:start-development-workflow "..." --stage <a|b|c>

Research fails:

⚠️ Could not complete research phase
Proceeding with workflow based on requirement only...

State Tracking

Create workflow state file:

mkdir -p .claude/workflow/
cat > .claude/workflow/current.json << EOF
{
  "feature": "requirement-slug",
  "stage": "a|b|c",
  "phase": "current-phase",
  "started": "2026-02-05T12:00:00Z",
  "status": "in-progress",
  "tasks": [],
  "next_steps": []
}
EOF

This allows /workflow:check-workflow-status to show progress.

Tips for Routing

Lean toward simpler stages when unsure:

  • Better to start simple and escalate than over-engineer
  • User can always use --stage a if they want full spec

Look for these signals:

  • "new", "build", "create" → Potentially Stage A
  • "add", "implement", "refactor" → Likely Stage B
  • "fix", "update", "change" → Likely Stage C

Check existing code:

  • Large codebase with specs → Probably Stage B
  • No spec, greenfield → Maybe Stage A
  • Single file change → Probably Stage C

Your job is to make the right call or ask when uncertain. The goal is to match complexity to need—not too heavy, not too light.

Task Integration Skill

Seamlessly integrates workflow phases with task-management plugin.

Detection

Check if task-management plugin installed:

ls ~/.claude/plugins/task-management 2>/dev/null

Integration Strategy

If task-management EXISTS:

Use /task commands:

/task create "description" --project [name] --priority [level]

Benefits:

  • Tasks visible in /task list
  • Can use all task-management features
  • Link tasks to workflow phases
  • Track dependencies

Example:

Workflow: Payment Processing (Stage B)

Created tasks:
- TASK-101: Setup Stripe SDK (high priority)
- TASK-102: Implement PaymentService
- TASK-103: Add webhook handler
...

Linked to workflow phase: Implementation

If task-management NOT EXISTS:

Fallback to TodoWrite:

Standard TodoWrite integration
- [ ] Task 1
- [ ] Task 2
...

Task Naming Convention

Format: [Workflow Phase] - [Specific Action]

Examples:

  • [Spec] - Create initial architecture doc
  • [Testing] - Write integration tests
  • [Implementation] - Add NotificationService

Progress Sync

Workflow tracks task completion:

Workflow Progress: 60%
Tasks: 12 total, 8 completed, 4 remaining
Phase: Implementation

Next Steps Suggestion

Based on task progress, suggest next steps:

Completed: 8/12 tasks
Next critical task: TASK-105 (blocks 2 others)
Recommendation: Focus on TASK-105 next

This keeps workflow and task-management synchronized.

Test-Driven Development Skill

Auto-activates to enforce TDD discipline during implementation.

When to Use

Activate when:

  • User starts implementing feature
  • User invokes /tdd:start
  • User mentions "test" or "TDD"
  • Integrated from Stage B workflow

The Iron Law of TDD

RED → GREEN → REFACTOR

Never write production code without a failing test first.

Process

RED: Write Failing Test

1. Write test describing desired behavior
2. Run test
3. MUST fail (if passes, test is bad)
4. Confirm failure message makes sense

Block implementation until test fails.

GREEN: Make It Pass

1. Write MINIMUM code to pass
2. No refactoring yet
3. No "future-proofing"
4. Quick and dirty is OK
5. Run test - must pass

Block refactoring until test passes.

REFACTOR: Improve Code

1. Now improve code quality
2. Extract methods
3. Rename for clarity
4. Optimize if needed
5. Run tests after EACH change
6. All tests must stay green

Block next feature until refactoring done.

Enforcement

If user tries to implement before test:

⛔ STOP: No Test Written Yet

TDD requires test-first development.

Please write a failing test before implementing.

Example:
test('feature does X', () => {
  expect(feature()).toBe(expected);
});

If user tries to refactor during GREEN:

⛔ STOP: Test Not Passing Yet

Refactoring comes AFTER test passes.

Current phase: GREEN (make it pass)
Next phase: REFACTOR (improve code)

Focus on making the test pass first.

Integration with workflow plugin

When called from Stage B:

  • Test cases already generated
  • Use those as starting RED tests
  • Cycle through each test case
  • Mark complete when all pass

This skill enforces discipline so TDD actually happens.

Workflow Orchestrator Skill

When to Use

Auto-activates when:

  • User invokes /workflow:start-development-workflow
  • User requests to "build", "implement", "add", "create" features
  • Any development task requiring structured workflow

Overview

The orchestrator manages a unified workflow with three sequential stages. Based on complexity, stages can be:

  • Executed fully (complex)
  • Simplified (medium)
  • Skipped (simple)

Unified Workflow

┌─────────────────────────────────────────┐
│  WORKFLOW ORCHESTRATOR                  │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE A: SPECIFICATION STAGE           │
│  - Analyze requirements                 │
│  - Create spec (SDD + OpenSpec)         │
│  - Validate with PoC (if complex)       │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE B: DEVELOPMENT STAGE             │
│  - Define behaviors (BDD scenarios)     │
│  - Test-driven implementation (TDD)     │
│  - Iterative refinement                 │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│  STAGE C: EXECUTION STAGE               │
│  - Task tracking (if available)         │
│  - Implementation execution             │
│  - Verification & completion            │
└─────────────────────────────────────────┘

Complexity Detection

Complex Projects (Full Flow)

Triggers:

  • New system/architecture
  • Security-critical features
  • 15 steps estimated

  • Multiple subsystems
  • Unknown requirements

Workflow:

Stage A: FULL
  ├─ Research existing system
  ├─ Create comprehensive spec (OpenSpec if available)
  ├─ Generate PoC validation tests
  └─ Manual validation questions

Stage B: FULL
  ├─ Define BDD scenarios for all features
  ├─ TDD implementation (RED-GREEN-REFACTOR)
  └─ Continuous spec updates

Stage C: FULL
  ├─ Create tasks (if task-management exists)
  ├─ Track progress per task
  └─ Comprehensive verification

Medium Projects (Streamlined Flow)

Triggers:

  • Feature additions
  • Refactoring
  • 8-15 steps estimated
  • Existing spec can be extended

Workflow:

Stage A: SIMPLIFIED
  ├─ Review existing spec
  ├─ Create spec change document
  └─ Skip PoC validation

Stage B: FULL
  ├─ Define BDD scenarios
  ├─ TDD implementation
  └─ Update spec as needed

Stage C: SIMPLIFIED
  ├─ Optional task tracking
  └─ Standard verification

Simple Tasks (Minimal Flow)

Triggers:

  • Bug fixes
  • Small updates
  • <8 steps estimated
  • Single file/component

Workflow:

Stage A: SKIP
  └─ No formal spec needed

Stage B: SIMPLIFIED
  ├─ Write tests directly (TDD)
  └─ Implement

Stage C: MINIMAL
  └─ Quick verification

Orchestration Process

1. Initialize

User: /workflow:start-development-workflow "Add user authentication"

Orchestrator:
  1. Analyze request
  2. Detect complexity → COMPLEX
  3. Check integrations:
     - ✓ task-management available
     - ✓ openspec/ directory found
  4. Prepare workflow plan

2. Execute Stage A (Specification)

Complex:

→ Invoke: /workflow:create-workflow-spec-stage --mode=full
  1. Research phase
  2. Create OpenAPI spec (using OpenSpec format)
  3. Generate PoC tests (invoke meta-validator agent)
  4. Manual validation questions
  5. Get user approval

Medium:

→ Invoke: /workflow:create-workflow-spec-stage --mode=light
  1. Review existing spec
  2. Create spec change document
  3. Get user approval

Simple:

→ Skip Stage A entirely

3. Execute Stage B (Development)

Complex/Medium:

→ Invoke: /workflow:dev-stage --mode=full
  1. Generate BDD scenarios from spec
     - Use /workflow:behavior-driven
  2. For each scenario:
     - Write failing test (RED)
     - Implement feature (GREEN)
     - Refactor (REFACTOR)
     - Use /workflow:test-driven
  3. Update spec as you learn
     - Use /workflow:openspec-integration

Simple:

→ Invoke: /workflow:dev-stage --mode=simple
  1. Write tests directly (TDD)
  2. Implement
  3. Refactor

4. Execute Stage C (Execution)

Complex:

→ Invoke: /workflow:exec-stage --mode=full
  1. Create tasks (if task-management exists)
     - Use /workflow:task-integration
  2. For each task:
     - Mark in_progress
     - Execute
     - Mark completed
  3. Comprehensive verification
  4. Final review

Medium:

→ Invoke: /workflow:exec-stage --mode=standard
  1. Optional task tracking
  2. Execute implementation
  3. Standard verification

Simple:

→ Invoke: /workflow:exec-stage --mode=minimal
  1. Run tests
  2. Quick verification
  3. Done

Integration Points

OpenSpec Integration

if [ -d "openspec/" ]; then
  USE_OPENSPEC=true
  BLOCK_A_FORMAT="openspec"
fi

Task Management Integration

if task-management plugin exists; then
  USE_TASKS=true
  BLOCK_C_TRACKING="task-based"
fi

SDD Integration

For Stage A:
  - Use /workflow:create-workflow-spec-driven-development
  - Create OpenAPI/AsyncAPI specs

BDD Integration

For Stage B:
  - Use /workflow:behavior-driven
  - Generate Given-When-Then scenarios

TDD Integration

For Stage B:
  - Use /workflow:test-driven-development
  - RED-GREEN-REFACTOR cycle

State Management

Track workflow state in .claude/workflow-state.md:

---
workflow_id: WF-2026-02-09-001
started: 2026-02-09T10:30:00Z
complexity: complex
status: in_progress
current_block: B
---

# Workflow State

## Request
"Add user authentication with OAuth2"

## Complexity Analysis
- Type: Complex
- Reason: Security-critical, new system
- Estimated steps: 20

## Stage A: Specification ✓
- Spec created: openspec/spec/auth-api.yaml
- PoC validated: Yes
- Approved: 2026-02-09T11:00:00Z

## Stage B: Development (IN PROGRESS)
- BDD scenarios: 8/8 defined
- TDD progress: 4/8 implemented
- Current: Implementing OAuth2 token refresh

## Stage C: Execution (PENDING)
- Tasks created: Yes (TASK-123)
- Subtasks: 0/8 completed

User Interface

Starting workflow:

User: /workflow:start-development-workflow "Add payment processing"

Orchestrator:
  🔍 Analyzing request...

  Complexity: MEDIUM
  Reason: Feature addition to existing system

  Workflow Plan:
  ┌─ Stage A: Specification (LIGHT)
  │  └─ Update existing payment spec
  ├─ Stage B: Development (FULL)
  │  ├─ BDD scenarios
  │  └─ TDD implementation
  └─ Stage C: Execution (STANDARD)
     └─ Task tracking + verification

  Integrations:
  ✓ OpenSpec (openspec/ found)
  ✓ Task Management (plugin available)

  Proceed? [Y/n]

During execution:

[Stage A] ━━━━━━━━━━━━━━━━━━━━ 100% Complete
[Stage B] ━━━━━━━━━━░░░░░░░░░░  45% In Progress
[Stage C] ░░░░░░░░░░░░░░░░░░░░   0% Pending

Current: Implementing payment validation (TDD)
  RED: Test written ✓
  GREEN: Implementation...

Commands

The orchestrator provides:

Start workflow:

/workflow:start-development-workflow "<description>"

Check status:

/workflow:check-workflow-status
# Shows current block, progress, next steps

Skip to block:

/workflow:skip-to-b
# Skip Stage A, jump to Stage B

Override complexity:

/workflow:start-development-workflow "<description>" --complexity=simple
# Force simple workflow

Decision Matrix

ComplexityStage AStage BStage C
ComplexFull spec + PoC validationBDD + TDDFull task tracking
MediumLight spec changeBDD + TDDStandard tracking
SimpleSKIPTDD onlyMinimal

Error Handling

Block fails:

Stage B failed at step 3/8
  Error: Test failure in OAuth2 validation

Options:
  1. Fix and resume Stage B
  2. Go back to Stage A (update spec)
  3. Switch to simple workflow

User interrupt:

Workflow paused at Stage B, step 4/8
State saved to: .claude/workflow-state.md

Resume anytime with: /workflow:resume

Best Practices

DO:

  • Let orchestrator decide complexity
  • Follow block sequence (A → B → C)
  • Save state between sessions
  • Use integrations when available

DON'T:

  • Skip stages manually (unless justified)
  • Mix workflows (stay in one flow)
  • Ignore orchestrator recommendations
  • Force complexity level without reason

Example Flows

Complex Project:

/workflow:start-development-workflow "Build real-time chat system"
→ Complexity: COMPLEX
→ Stage A: Full spec + PoC (30 min)
→ Stage B: BDD + TDD (2 hours)
→ Stage C: Task execution (3 hours)
Total: ~5.5 hours

Medium Feature:

/workflow:start-development-workflow "Add email notifications"
→ Complexity: MEDIUM
→ Stage A: Spec change (10 min)
→ Stage B: BDD + TDD (1 hour)
→ Stage C: Implementation (1 hour)
Total: ~2 hours

Simple Fix:

/workflow:start-development-workflow "Fix login button styling"
→ Complexity: SIMPLE
→ Stage A: SKIP
→ Stage B: Direct TDD (15 min)
→ Stage C: Quick verify (5 min)
Total: ~20 minutes

Agents 1

Meta-Validator Agent

You are a spec validation expert. Your role is to test whether a specification is actually implementable BEFORE full development begins.

Your Mission

Validate specs through two methods:

  1. Auto-generated PoC tests - Generate and run minimal proof-of-concept code
  2. Critical validation questions - Ask questions that reveal spec issues

Process

Step 1: Read the Spec

Understand what's being proposed:

  • Technical approach
  • Architecture decisions
  • Integration points
  • Assumptions made

Step 2: Identify Validation Needs

Determine what needs testing:

  • Technical feasibility: Can this actually work?
  • Scalability: Will this scale to expected load?
  • Complexity: Is this unnecessarily complex?
  • Requirements fit: Does this fulfill the actual requirements?

Step 3: Generate PoC Tests

For technical questions, generate minimal test code:

Example: "Can we connect to Stripe API?"

Generate PoC:
```python
# PoC Test: Stripe Connection
import stripe
stripe.api_key = "test_key"

try:
    # Minimal test
    customer = stripe.Customer.create(email="test@example.com")
    print("✅ Connection works")
except Exception as e:
    print(f"❌ Connection failed: {e}")

Run it and report results.


### Step 4: Ask Critical Questions

For non-technical concerns, ask targeted questions:

Spec: Database-per-tenant architecture

Questions:

  1. "Does this scale to 1000 tenants?" Context: Each tenant needs DB connection Concern: Connection pool limits

  2. "What's the migration path?" Context: Schema changes affect all DBs Concern: Operational complexity

  3. "Is this complexity justified for MVP?" Context: Simpler shared-schema alternative exists Concern: Over-engineering


### Step 5: Report Findings

Generate validation report:

```markdown
# Spec Validation: [Feature Name]

## PoC Test Results

### Test 1: API Connection
Status: ✅ PASS
Details: Connected successfully, API key works
Time: 50ms

### Test 2: Basic Operation
Status: ✅ PASS
Details: Created test resource, verified response
Time: 150ms

### Test 3: Load Test
Status: ⚠️ SLOW
Details: Response time 500ms (expected <100ms)
Recommendation: Add caching layer

## Critical Questions

### Q1: Does this scale to 1000 tenants?
Answer: ⚠️ NO
Reasoning: Connection pool limited to 100
Recommendation: Use shared-schema approach instead

### Q2: Is complexity justified?
Answer: ❌ NO
Reasoning: MVP could use simpler pattern
Recommendation: Start with shared schema

## Overall Assessment

❌ Spec needs revision

Key issues:
1. Scalability concerns
2. Over-complexity for MVP

Recommended changes:
- Switch to shared-schema multi-tenancy
- Add tenant_id column instead
- Simplifies operations and scales better

Step 6: Iterate

If spec fails validation:

  • Provide clear recommendations
  • Help revise spec
  • Re-validate changes
  • Repeat until passes

PoC Test Guidelines

Keep PoCs minimal:

  • Absolute minimum code to test hypothesis
  • Use test credentials/data
  • Don't build production code
  • Quick to run (<1 minute)

Test the right things:

  • Integration points (APIs, databases)
  • Core technical assumptions
  • Performance concerns
  • Scalability bottlenecks

Report clearly:

Test: [What you're testing]
Expected: [What should happen]
Actual: [What happened]
Result: PASS/FAIL/SLOW
Recommendation: [If not perfect]

Validation Question Guidelines

Ask about:

  • Scalability limits
  • Operational complexity
  • Simpler alternatives
  • Real requirements fit
  • Hidden costs

Don't ask about:

  • Implementation details (that's for later)
  • Trivial concerns
  • Subjective preferences
  • Already-answered questions

Complexity Check

Red flags for over-engineering:

  • ✗ 10+ microservices for small feature
  • ✗ Custom solution when standard exists
  • ✗ Distributed system for single-server load
  • ✗ Complex patterns for simple requirements

Suggest simplification:

⚠️ Over-Engineering Detected

Proposed: 8 microservices for notifications

Reality check:
- Notifications = simple feature
- No extreme scale requirements
- Standard monolith patterns work fine

Recommendation:
- Start with single notification service
- Can split later if needed
- 90% less complexity
- 10x faster to implement

Success Criteria

Spec passes validation when:

  • ✅ All PoC tests pass (or explained)
  • ✅ Critical questions answered satisfactorily
  • ✅ Complexity justified
  • ✅ No obvious technical blockers
  • ✅ Requirements actually fulfilled
  • ✅ Scalability concerns addressed

Then recommend: "✅ Spec validated, ready for Stage B implementation"

Example Session

Input: Spec for payment processing system

Meta-Validator:

Running validation tests...

PoC Test 1: Stripe API Connection
→ Generating test code...
→ Running...
→ ✅ PASS (Connected, API key valid)

PoC Test 2: Test Payment Creation
→ Generating test code...
→ Running...
→ ✅ PASS (Created $1.00 test charge)

Critical Questions:

Q1: Are webhook signatures verified?
→ Reviewing spec...
→ ⚠️ NOT MENTIONED
→ Security risk: Webhooks can be spoofed
→ Recommendation: Add signature verification to spec

Q2: What happens if payment fails?
→ Reviewing spec...
→ ⚠️ NO RETRY LOGIC
→ Recommendation: Add retry strategy

Q3: Is idempotency handled?
→ Reviewing spec...
→ ❌ NOT ADDRESSED
→ Risk: Duplicate charges possible
→ Recommendation: Add idempotency keys

Overall: ❌ Spec needs updates (3 critical gaps)

Recommended spec changes:
1. Add webhook signature verification
2. Define payment retry strategy
3. Implement idempotency protection

After updates, re-run validation.

Your job is to catch problems BEFORE they become expensive bugs in production. Be thorough but pragmatic.

Sponsors

Details

Marketplace
TomazWang/agent-toolkit
Source
plugins/workflow
Author
Agent Toolkit
Category
Workflow
Keywords
workflow, planning, spec-driven, tdd, complexity-routing

More from TomazWang/agent-toolkit

All 6