
workflow
Unified workflow system with Stage A/B/C complexity routing (Spec → Dev → Exec)
- version
- 1.0.0
Install
/plugin install workflow@agent-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add TomazWang/agent-toolkit.
Contents
Discovered from sourceSkills 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:
- Research existing docs/specs/code
- Create initial spec document
- Run meta-testing automatically
- Iterate based on results
- 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:
- Verify meta-tests passed
- Create final spec document (design.md)
- Transition to Stage B for implementation
- 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
-
Research (unless skipped):
- Quick check of relevant code
- Understand current implementation
-
Create Plan:
- Break requirement into steps
- Identify files to modify
- Define success criteria
-
Convert to Tasks:
- If task-management installed: Create tasks with
/task - Otherwise: Use TodoWrite
- Link tasks to plan
- If task-management installed: Create tasks with
-
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:
- Setup email service
- Create NotificationService
- Implement email templates
- Add event hooks
- Write tests
- Integrate and validate
5. TDD Implementation
If tdd-workflow plugin installed:
- Launch
/tdd:startwith generated tests - Follow RED → GREEN → REFACTOR cycle
Otherwise:
- Guide manual TDD:
- Write failing tests (RED)
- Implement to pass (GREEN)
- 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
- Spec creation (OpenSpec if available)
- PoC validation tests
- BDD scenarios
- TDD implementation
- 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-specskill - Stage B →
stage-devskill - Stage C →
stage-execskill
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 aif 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
| Complexity | Stage A | Stage B | Stage C |
|---|---|---|---|
| Complex | Full spec + PoC validation | BDD + TDD | Full task tracking |
| Medium | Light spec change | BDD + TDD | Standard tracking |
| Simple | SKIP | TDD only | Minimal |
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:
- Auto-generated PoC tests - Generate and run minimal proof-of-concept code
- 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:
-
"Does this scale to 1000 tenants?" Context: Each tenant needs DB connection Concern: Connection pool limits
-
"What's the migration path?" Context: Schema changes affect all DBs Concern: Operational complexity
-
"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