scene-capability-engine 3.0.0

package/docs/spec-numbering-guide.md

@@ -0,0 +1,348 @@
+# Spec Numbering Strategy Guide
+
+> A comprehensive guide to choosing the right numbering strategy for your Specs
+
+## Overview
+
+Kiro Spec Engine uses a two-part numbering system: `{major}-{minor}-{description}`
+
+- **Major number**: Represents a feature domain or theme (01, 02, 03, ...)
+- **Minor number**: Represents iterations or sub-features within that domain (00, 01, 02, ...)
+- **Description**: A kebab-case description of the Spec
+
+**Examples**:
+- `01-00-user-authentication`
+- `01-01-add-oauth-support`
+- `02-00-payment-system`
+
+## When to Use Major vs Minor Numbers
+
+### Strategy 1: Simple Projects (Recommended for Most Cases)
+
+**Use Case**: Projects with < 20 independent features
+
+**Approach**: Use only major numbers with minor always as `00`
+
+```
+01-00-user-authentication
+02-00-payment-integration
+03-00-notification-system
+04-00-reporting-dashboard
+05-00-api-gateway
+```
+
+**Advantages**:
+- ✅ Simple and clear
+- ✅ Easy to understand at a glance
+- ✅ No need to plan groupings upfront
+- ✅ Works well for independent features
+
+**When to use**:
+- Building a tool or library
+- Features are relatively independent
+- Project is in early stages
+- Team is small (< 5 people)
+
+### Strategy 2: Complex Projects with Themes
+
+**Use Case**: Large projects with clear feature domains
+
+**Approach**: Group related Specs under the same major number
+
+```
+# User Management Domain (01-xx)
+01-00-user-authentication-foundation
+01-01-add-oauth-support
+01-02-add-two-factor-auth
+01-03-add-sso-integration
+
+# Payment Domain (02-xx)
+02-00-payment-system-mvp
+02-01-add-subscription-billing
+02-02-add-invoice-generation
+02-03-add-refund-workflow
+
+# Notification Domain (03-xx)
+03-00-notification-email
+03-01-notification-sms
+03-02-notification-push
+03-03-notification-in-app
+```
+
+**Advantages**:
+- ✅ Clear thematic grouping
+- ✅ Easy to track evolution of a feature
+- ✅ Shows relationships between Specs
+- ✅ Scales well for large projects
+
+**When to use**:
+- Building a complex application
+- Features have clear domains (user, payment, notification, etc.)
+- Multiple iterations expected per domain
+- Large team with domain ownership
+
+### Strategy 3: Hybrid Approach (Flexible)
+
+**Use Case**: Start simple, add structure as needed
+
+**Approach**: Begin with major numbers only, introduce minor numbers when needed
+
+**Phase 1 - Early Development**:
+```
+01-00-mvp-core-features
+02-00-user-management
+03-00-data-storage
+04-00-api-gateway
+```
+
+**Phase 2 - Iteration Needed**:
+```
+01-00-mvp-core-features
+02-00-user-management
+03-00-data-storage-basic
+03-01-data-storage-add-caching      ← Added iteration
+03-02-data-storage-add-replication  ← Added iteration
+04-00-api-gateway
+05-00-monitoring-system
+```
+
+**Advantages**:
+- ✅ Start simple, grow as needed
+- ✅ No premature planning required
+- ✅ Adapts to project evolution
+- ✅ Best of both worlds
+
+**When to use**:
+- Uncertain about project scope
+- Want flexibility
+- Agile development approach
+- Learning the Spec workflow
+
+## Semantic Numbering Rules
+
+### Rule 1: XX-00 for First or Independent Specs
+
+Use `XX-00` for:
+- The first Spec in a domain
+- Independent features that don't need iterations
+- Standalone functionality
+
+```
+01-00-authentication-system    # First in domain
+02-00-payment-integration      # Independent feature
+03-00-email-notifications      # Standalone
+```
+
+### Rule 2: XX-01+ for Iterations and Enhancements
+
+Use `XX-01`, `XX-02`, etc. for:
+- Bug fixes related to a previous Spec
+- Feature enhancements
+- Iterations on the same theme
+- Related functionality
+
+```
+01-00-authentication-system
+01-01-fix-session-timeout-bug       # Bug fix
+01-02-add-remember-me-feature       # Enhancement
+01-03-add-password-reset            # Related feature
+```
+
+### Rule 3: Keep Related Specs Together
+
+Group Specs that:
+- Share the same codebase area
+- Have dependencies on each other
+- Belong to the same feature domain
+- Will be maintained by the same team
+
+```
+# Good: Related notification features grouped
+03-00-notification-email
+03-01-notification-sms
+03-02-notification-push
+
+# Avoid: Unrelated features under same major number
+03-00-notification-email
+03-01-payment-refunds        # ❌ Not related to notifications
+```
+
+## Practical Examples
+
+### Example 1: Tool/Library Project (kiro-spec-engine)
+
+**Project Type**: CLI tool with independent features
+
+**Strategy**: Simple numbering (XX-00)
+
+```
+01-00-user-space-diagnosis
+02-00-oauth-api-upgrade
+03-00-multi-user-collaboration
+04-00-watch-mode-automation
+05-00-agent-hooks-and-automation
+06-00-test-stability-and-reliability
+07-00-user-onboarding-and-documentation
+08-00-document-lifecycle-management
+09-00-document-governance-automation
+```
+
+**Why**: Each feature is independent and complete
+
+### Example 2: E-commerce Platform
+
+**Project Type**: Complex web application
+
+**Strategy**: Thematic grouping
+
+```
+# User Domain
+01-00-user-registration-and-login
+01-01-user-profile-management
+01-02-user-preferences-and-settings
+
+# Product Domain
+02-00-product-catalog-foundation
+02-01-product-search-and-filters
+02-02-product-recommendations
+
+# Order Domain
+03-00-shopping-cart-system
+03-01-checkout-process
+03-02-order-tracking
+03-03-order-history
+
+# Payment Domain
+04-00-payment-gateway-integration
+04-01-multiple-payment-methods
+04-02-payment-security-enhancements
+```
+
+**Why**: Clear domains with multiple related features
+
+### Example 3: SaaS Application
+
+**Project Type**: Multi-tenant SaaS
+
+**Strategy**: Hybrid approach
+
+```
+# Core Features (Independent)
+01-00-tenant-management
+02-00-user-authentication
+03-00-billing-system
+
+# Analytics Domain (Grouped)
+04-00-analytics-foundation
+04-01-analytics-custom-dashboards
+04-02-analytics-export-reports
+
+# Integration Domain (Grouped)
+05-00-api-gateway
+05-01-webhook-system
+05-02-third-party-integrations
+
+# More Independent Features
+06-00-email-templates
+07-00-notification-center
+```
+
+**Why**: Mix of independent features and grouped domains
+
+## Decision Tree
+
+Use this flowchart to decide your numbering strategy:
+
+```
+Is this your first Spec?
+├─ Yes → Use 01-00-{description}
+└─ No → Continue...
+
+Is this related to an existing Spec?
+├─ Yes → Use same major number, increment minor
+│        Example: 01-00 exists → use 01-01
+└─ No → Continue...
+
+Do you expect multiple iterations in this domain?
+├─ Yes → Plan major number for the domain
+│        Example: 03-00, 03-01, 03-02 for notifications
+└─ No → Use next available major number with -00
+         Example: 05-00-new-feature
+```
+
+## Best Practices
+
+### ✅ Do
+
+1. **Start simple**: Use XX-00 until you need complexity
+2. **Be consistent**: Stick to one strategy per project
+3. **Document your approach**: Add a note in your project README
+4. **Use descriptive names**: Make the description clear
+5. **Reserve major numbers**: If planning domains, reserve ranges
+
+### ❌ Don't
+
+1. **Don't over-plan**: Don't create 50 major numbers upfront
+2. **Don't mix unrelated features**: Keep major numbers thematic
+3. **Don't skip numbers**: Use sequential numbering
+4. **Don't change strategy mid-project**: Stick to your approach
+5. **Don't stress**: The numbering is for organization, not perfection
+
+## Migration Between Strategies
+
+### From Simple to Thematic
+
+If you started with simple numbering and need to add structure:
+
+**Before**:
+```
+01-00-user-auth
+02-00-user-profile
+03-00-payment-basic
+04-00-payment-subscriptions
+```
+
+**After** (optional reorganization):
+```
+01-00-user-auth
+01-01-user-profile          # Grouped with auth
+02-00-payment-basic
+02-01-payment-subscriptions # Grouped with payment
+```
+
+**Note**: Renaming existing Specs is optional. You can keep old numbers and use new strategy going forward.
+
+## Tool Support
+
+Kiro Spec Engine provides commands to help with numbering:
+
+```bash
+# List all Specs with their numbers
+kse status
+
+# View Specs grouped by major number
+kse workflows
+
+# Get next available number suggestion
+kse workflows --suggest-next
+```
+
+## Summary
+
+**Choose your strategy based on project complexity**:
+
+- **Simple projects**: Use `XX-00` for everything
+- **Complex projects**: Group by domain with `XX-YY`
+- **Uncertain**: Start simple, add structure later
+
+**Remember**: The goal is organization and clarity, not perfection. Choose what works for your team and project.
+
+---
+
+**Related Documentation**:
+- [Spec Workflow Guide](./spec-workflow.md)
+- [Quick Start Guide](./quick-start.md)
+- [FAQ](./faq.md)
+
+**Version**: 1.42.0  
+**Last Updated**: 2026-01-24