kiro-spec-engine 1.3.0 → 1.4.1

package/docs/spec-workflow.md

@@ -0,0 +1,453 @@
+# Spec Workflow Guide
+
+> Understanding the Spec-driven development workflow in kse
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23  
+**Audience**: Intermediate  
+**Estimated Time**: 10 minutes
+
+---
+
+## Overview
+
+A **Spec** (specification) is the fundamental unit of work in kse. It's a structured description of a feature or component that guides both human developers and AI assistants through the implementation process.
+
+Every Spec follows a three-stage workflow: **Requirements → Design → Tasks**
+
+---
+
+## The Spec Creation Workflow
+
+```mermaid
+graph LR
+    A[Idea/Feature Request] --> B[Requirements]
+    B --> C[Design]
+    C --> D[Tasks]
+    D --> E[Implementation]
+    E --> F[Completion]
+    F --> G[Archive/Document]
+```
+
+### Stage Descriptions
+
+1. **Idea/Feature Request** - The initial concept or need
+2. **Requirements** - What you're building and why (user stories, acceptance criteria)
+3. **Design** - How you'll build it (architecture, APIs, components)
+4. **Tasks** - Step-by-step implementation plan
+5. **Implementation** - Actual coding (often AI-assisted)
+6. **Completion** - All tasks done, feature working
+7. **Archive/Document** - Spec serves as documentation
+
+---
+
+## Stage 1: Requirements
+
+**Purpose:** Define WHAT you're building and WHY
+
+**File:** `requirements.md`
+
+**Key Components:**
+- **Overview** - Brief description of the feature
+- **User Stories** - "As a... I want... So that..."
+- **Functional Requirements** - Specific capabilities the system must have
+- **Acceptance Criteria** - "WHEN... THEN..." statements
+- **Non-Functional Requirements** - Performance, security, usability
+
+**Example Structure:**
+
+```markdown
+# Feature Name
+
+## Overview
+Brief description of what this feature does
+
+## User Stories
+- As a [user type], I want to [action], so that [benefit]
+
+## Functional Requirements
+### FR-1: Requirement Name
+Description of what the system must do
+
+## Acceptance Criteria
+- WHEN [condition] THEN [expected result]
+
+## Non-Functional Requirements
+- Performance: Response time < 500ms
+- Security: Data encrypted at rest
+```
+
+**Best Practices:**
+- ✅ Write from user perspective
+- ✅ Be specific and measurable
+- ✅ Include edge cases
+- ✅ Consider security and performance
+- ❌ Don't include implementation details (that's for Design)
+
+---
+
+## Stage 2: Design
+
+**Purpose:** Define HOW you'll build it
+
+**File:** `design.md`
+
+**Key Components:**
+- **Architecture Overview** - High-level system structure
+- **Component Design** - Individual components and their responsibilities
+- **API Design** - Endpoints, request/response formats
+- **Data Models** - Database schemas, data structures
+- **Technology Stack** - Languages, frameworks, libraries
+- **Requirements Traceability** - Map requirements to design components
+
+**Example Structure:**
+
+```markdown
+# Feature Name - Design
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Database]
+```
+
+## API Design
+### POST /api/endpoint
+Request: { ... }
+Response: { ... }
+
+## Component Design
+### ComponentName
+**Responsibility:** What it does
+**Methods:**
+- method1() - Description
+- method2() - Description
+
+## Data Models
+```javascript
+{
+  field1: type,
+  field2: type
+}
+```
+
+## Technology Stack
+- Backend: Node.js + Express
+- Database: PostgreSQL
+
+## Requirements Traceability
+| Requirement | Design Component |
+|-------------|------------------|
+| FR-1 | ComponentA.method1() |
+```
+
+**Best Practices:**
+- ✅ Use diagrams to visualize architecture
+- ✅ Define clear component responsibilities
+- ✅ Specify all APIs and data formats
+- ✅ Link back to requirements
+- ❌ Don't skip the traceability section
+
+---
+
+## Stage 3: Tasks
+
+**Purpose:** Break down implementation into actionable steps
+
+**File:** `tasks.md`
+
+**Key Components:**
+- **Task List** - Checkbox list of implementation steps
+- **Task Hierarchy** - Organized by phase or component
+- **Task IDs** - Numbered for easy reference (1.1, 1.2, 2.1, etc.)
+- **Dependencies** - Implicit through ordering
+
+**Example Structure:**
+
+```markdown
+# Feature Name - Tasks
+
+## Phase 1: Setup
+- [ ] 1.1 Set up project structure
+- [ ] 1.2 Install dependencies
+- [ ] 1.3 Configure environment
+
+## Phase 2: Core Implementation
+- [ ] 2.1 Implement ComponentA
+  - [ ] 2.1.1 Create class structure
+  - [ ] 2.1.2 Implement method1()
+  - [ ] 2.1.3 Write unit tests
+- [ ] 2.2 Implement ComponentB
+
+## Phase 3: Integration
+- [ ] 3.1 Connect components
+- [ ] 3.2 Integration testing
+- [ ] 3.3 End-to-end testing
+
+## Phase 4: Documentation
+- [ ] 4.1 API documentation
+- [ ] 4.2 User guide
+```
+
+**Best Practices:**
+- ✅ Break large tasks into subtasks
+- ✅ Order tasks logically (dependencies first)
+- ✅ Include testing tasks
+- ✅ Be specific enough for AI to understand
+- ❌ Don't make tasks too granular (not every line of code)
+
+---
+
+## The Complete Workflow in Action
+
+### Example: User Login Feature
+
+**1. Create the Spec:**
+```bash
+kse create-spec 01-00-user-login
+```
+
+**2. Write Requirements** (`.kiro/specs/01-00-user-login/requirements.md`):
+```markdown
+# User Login
+
+## User Stories
+- As a user, I want to log in with email and password
+
+## Acceptance Criteria
+- WHEN user enters valid credentials THEN they are logged in
+- WHEN user enters invalid credentials THEN they see an error
+```
+
+**3. Write Design** (`.kiro/specs/01-00-user-login/design.md`):
+```markdown
+# User Login - Design
+
+## API Design
+POST /api/auth/login
+Request: { email, password }
+Response: { token } or { error }
+
+## Components
+- AuthController - handles login requests
+- AuthService - validates credentials
+- UserRepository - database access
+```
+
+**4. Write Tasks** (`.kiro/specs/01-00-user-login/tasks.md`):
+```markdown
+- [ ] 1.1 Create AuthController
+- [ ] 1.2 Create AuthService
+- [ ] 1.3 Create UserRepository
+- [ ] 1.4 Implement login endpoint
+- [ ] 1.5 Write tests
+```
+
+**5. Export Context:**
+```bash
+kse context export 01-00-user-login
+```
+
+**6. Implement with AI:**
+- Provide context to your AI tool
+- AI implements tasks based on your Spec
+- Update task checkboxes as you complete them
+
+**7. Track Progress:**
+```bash
+kse status
+```
+
+---
+
+## Workflow Variations
+
+### Iterative Refinement
+
+You don't have to complete all three stages before starting implementation:
+
+```mermaid
+graph TD
+    A[Write Basic Requirements] --> B[Write Basic Design]
+    B --> C[Write First Tasks]
+    C --> D[Implement First Tasks]
+    D --> E{Need More Detail?}
+    E -->|Yes| F[Refine Requirements/Design]
+    F --> C
+    E -->|No| G[Continue Implementation]
+```
+
+**When to use:**
+- Exploring new features
+- Prototyping
+- Learning new technologies
+
+### Waterfall Approach
+
+Complete each stage fully before moving to the next:
+
+```mermaid
+graph TD
+    A[Complete Requirements] --> B[Review Requirements]
+    B --> C[Complete Design]
+    C --> D[Review Design]
+    D --> E[Complete Tasks]
+    E --> F[Begin Implementation]
+```
+
+**When to use:**
+- Well-understood features
+- Critical systems
+- Team collaboration (clear handoffs)
+
+---
+
+## Integration with AI Tools
+
+### Context Export Workflow
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant kse as kse
+    participant AI as AI Tool
+    
+    Dev->>kse: Create Spec (requirements, design, tasks)
+    Dev->>kse: kse context export spec-name
+    kse->>Dev: context-export.md
+    Dev->>AI: Provide context
+    AI->>Dev: Generate code
+    Dev->>kse: Update task status
+    Dev->>kse: kse status (check progress)
+```
+
+### Automated Workflow (Windsurf/Cline)
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant AI as AI Tool
+    participant kse as kse
+    
+    Dev->>AI: "Implement user login feature"
+    AI->>kse: kse context export 01-00-user-login
+    kse->>AI: Return context
+    AI->>AI: Generate code
+    AI->>kse: kse task claim 01-00-user-login 1.1
+    AI->>Dev: Code generated, task claimed
+```
+
+---
+
+## Best Practices
+
+### Requirements Stage
+1. **Start with user stories** - Understand the user's perspective
+2. **Use EARS format** for acceptance criteria (WHEN... THEN...)
+3. **Include non-functional requirements** - Don't forget performance, security
+4. **Think about edge cases** - What could go wrong?
+
+### Design Stage
+1. **Visualize with diagrams** - A picture is worth a thousand words
+2. **Define clear interfaces** - APIs, method signatures, data formats
+3. **Maintain traceability** - Link every design decision to a requirement
+4. **Choose appropriate technologies** - Document your tech stack
+
+### Tasks Stage
+1. **Break down logically** - Group related tasks into phases
+2. **Order by dependencies** - What needs to be done first?
+3. **Include testing** - Every feature needs tests
+4. **Be AI-friendly** - Tasks should be clear enough for AI to implement
+
+### Throughout
+1. **Keep it updated** - Specs are living documents
+2. **Use version control** - Commit Spec changes
+3. **Review regularly** - Ensure Spec matches implementation
+4. **Archive completed Specs** - They become documentation
+
+---
+
+## Common Pitfalls
+
+### ❌ Too Vague
+**Bad:**
+```markdown
+- [ ] Make login work
+```
+
+**Good:**
+```markdown
+- [ ] 1.1 Implement AuthController.login() method
+  - Accept email and password
+  - Validate inputs
+  - Return JWT token on success
+  - Return error message on failure
+```
+
+### ❌ Too Detailed
+**Bad:**
+```markdown
+- [ ] 1.1 Create variable named 'email'
+- [ ] 1.2 Create variable named 'password'
+- [ ] 1.3 Write if statement to check email
+```
+
+**Good:**
+```markdown
+- [ ] 1.1 Implement input validation
+  - Validate email format
+  - Validate password length
+  - Return validation errors
+```
+
+### ❌ Missing Traceability
+**Bad:** Design with no connection to requirements
+
+**Good:** Design with clear traceability table:
+```markdown
+| Requirement | Design Component |
+|-------------|------------------|
+| FR-1: User can log in | AuthController.login() |
+| FR-2: Validate inputs | ValidationService |
+```
+
+---
+
+## Related Documentation
+
+- **[Quick Start Guide](quick-start.md)** - Get started with your first Spec
+- **[Integration Modes](integration-modes.md)** - How to use Specs with AI tools
+- **[Command Reference](command-reference.md)** - All kse commands
+- **[Examples](examples/)** - Complete example Specs
+
+---
+
+## Summary
+
+The Spec workflow is:
+1. **Requirements** - Define WHAT and WHY
+2. **Design** - Define HOW
+3. **Tasks** - Define STEPS
+4. **Implementation** - Build it (with AI assistance)
+5. **Completion** - Verify and document
+
+**Key Benefits:**
+- ✅ Clear structure for features
+- ✅ Better AI assistance (AI understands your intent)
+- ✅ Built-in documentation
+- ✅ Progress tracking
+- ✅ Team collaboration
+
+**Start your next Spec:** 🚀
+```bash
+kse create-spec 02-00-your-feature
+```
+
+---
+
+**Version**: 1.0.0  
+**Last Updated**: 2026-01-23