teamspec 3.2.0 → 4.1.0

package/teamspec-core/templates/dev-plan-template.md

@@ -0,0 +1,168 @@
+# Dev Plan: `dp-e{EEE}-s{SSS}-{description}`
+
+<!--
+  TEAMSPEC 4.0 DEV PLAN TEMPLATE
+
+  Dev Plans document the implementation approach for a Story.
+
+  NAMING PATTERN: dp-e{EEE}-s{SSS}-{description}.md
+  EXAMPLE: dp-e001-s042-oauth-implementation.md
+
+  RULES:
+  - Must link to Story (via filename pattern matching s-e{EEE}-{SSS})
+  - Created by DEV before implementation starts
+  - Required before story moves to In Progress
+
+  TEAMSPEC RULES ENFORCED:
+  - TS-DEVPLAN-001: Dev plan required before implementation
+-->
+
+> **Template Version**: 4.0
+> **Last Updated**: 2026-01-11
+
+---
+
+**Document Owner:** DEV (Developer)
+**Artifact Type:** Execution (Implementation Plan)
+**Lifecycle:** Sprint-bound, archived after story completion
+
+---
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Dev Plan ID** | dp-e{EEE}-s{SSS} |
+| **Story** | [s-e{EEE}-{SSS}](../stories/in-progress/s-e{EEE}-{SSS}-*.md) |
+| **Epic** | epic-{PRX}-{NNN} |
+| **Product** | {product-id} ({PRX}) |
+| **Author** | [DEV Name] |
+| **Created** | YYYY-MM-DD |
+| **Status** | Draft / Approved / In Progress / Complete |
+
+---
+
+## Linked Story
+
+> **MANDATORY**: Link to the Story this plan implements.
+
+| Story ID | Title | Feature-Increment |
+|----------|-------|-------------------|
+| [s-e{EEE}-{SSS}](../stories/in-progress/s-e{EEE}-{SSS}-*.md) | [Story Title] | [fi-{PRX}-{NNN}](../feature-increments/fi-{PRX}-{NNN}-*.md) |
+
+---
+
+## 1. Implementation Approach
+
+_High-level approach to implementing the story._
+
+### 1.1 Strategy
+
+[Describe the overall implementation strategy]
+
+### 1.2 Key Components
+
+| Component | Change Type | Description |
+|-----------|-------------|-------------|
+| [Component 1] | New / Modified | [Brief description] |
+| [Component 2] | New / Modified | [Brief description] |
+
+---
+
+## 2. Technical Design
+
+### 2.1 Files to Create/Modify
+
+| File Path | Action | Purpose |
+|-----------|--------|---------|
+| `src/path/file.ts` | Create / Modify | [Purpose] |
+
+### 2.2 Dependencies
+
+| Dependency | Type | Status |
+|------------|------|--------|
+| [Library/Service] | New / Existing | Approved / Pending |
+
+### 2.3 API Changes
+
+_If applicable, document any API changes._
+
+| Endpoint | Method | Change |
+|----------|--------|--------|
+| `/api/endpoint` | POST | New / Modified |
+
+---
+
+## 3. Testing Strategy
+
+### 3.1 Unit Tests
+
+- [ ] [Test case 1]
+- [ ] [Test case 2]
+
+### 3.2 Integration Tests
+
+- [ ] [Integration test 1]
+
+### 3.3 Manual Testing
+
+- [ ] [Manual test scenario]
+
+---
+
+## 4. Risks & Mitigations
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [Mitigation plan] |
+
+---
+
+## 5. Acceptance Criteria Mapping
+
+> Map each AC from the Story to implementation details.
+
+| AC # | Acceptance Criteria | Implementation Notes |
+|------|---------------------|---------------------|
+| 1 | [AC from Story] | [How it will be implemented] |
+| 2 | [AC from Story] | [How it will be implemented] |
+
+---
+
+## 6. Checklist
+
+### Pre-Implementation
+
+- [ ] Story requirements understood
+- [ ] Feature-Increment AS-IS/TO-BE reviewed
+- [ ] Technical approach approved
+- [ ] Dependencies identified
+
+### Implementation
+
+- [ ] Code implemented
+- [ ] Unit tests written
+- [ ] Code reviewed
+- [ ] Tests passing
+
+### Post-Implementation
+
+- [ ] Integration tests passing
+- [ ] Documentation updated (if needed)
+- [ ] Ready for QA verification
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | @author | Initial plan |
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description |
+|------|-------------|
+| TS-DEVPLAN-001 | Dev plan required before implementation |

package/teamspec-core/templates/epic-template.md

@@ -0,0 +1,204 @@
+# Epic: `epic-PRX-XXX-description`
+
+<!-- 
+  ⚠️ TEAMSPEC 4.0 EPIC TEMPLATE
+  
+  This Epic groups related Feature-Increments for delivery.
+  
+  RULES:
+  - Must link to at least one Feature-Increment (fi-PRX-XXX)
+  - Must define TO-BE/Business Value section
+  - Stories belong to Epics via filename (s-eXXX-YYY)
+  
+  TEAMSPEC RULES ENFORCED:
+  - TS-EPIC-001: Epic must link to Feature-Increments
+  - TS-EPIC-002: Epic must define TO-BE state
+  - TS-EPIC-003: Epic ID must be unique
+-->
+
+> **Template Version**: 4.0  
+> **Last Updated**: 2026-01-10
+
+---
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Epic ID** | epic-{PRX}-{NNN} |
+| **Status** | Draft / Proposed / Approved / In Progress / Done |
+| **Product** | {product-id} ({PRX}) |
+| **Owner** | FA (Functional Analyst) |
+| **Created** | YYYY-MM-DD |
+
+**Document Owner:** FA (Functional Analyst)
+**Artifact Type:** Execution (Groups Feature-Increments)
+**Lifecycle:** Project-bound, archived after completion
+
+---
+
+## Epic Summary
+
+_One to three sentences describing the epic's purpose and value._
+
+**As a** [Persona/Stakeholder],  
+**I want** [High-level capability],  
+**So that** [Business value/outcome].
+
+---
+
+## Linked Product
+
+> ⚠️ **MANDATORY**: Link to the target product.
+
+| Product ID | PRX | Product Name |
+|------------|-----|--------------|
+| [product-id](../../products/product-id/product.yml) | PRX | [Product Name] |
+
+---
+
+## Feature-Increments
+
+> ⚠️ **MANDATORY**: At least one Feature-Increment must be linked.  
+> **TEAMSPEC RULE:** TS-EPIC-001 - Feature-Increment link required
+
+| FI ID | Description | Status |
+|-------|-------------|--------|
+| [fi-PRX-001](../feature-increments/fi-PRX-001-description.md) | [Brief description] | Draft |
+| [fi-PRX-002](../feature-increments/fi-PRX-002-description.md) | [Brief description] | Draft |
+
+---
+
+## TO-BE / Business Value
+
+> ⚠️ **MANDATORY**: Define the target state or business value.  
+> **TEAMSPEC RULE:** TS-EPIC-002 - TO-BE section required
+
+### Value Proposition
+
+_What value does completing this Epic deliver?_
+
+- **User Impact**: [How does this improve user experience?]
+- **Business Impact**: [Revenue, efficiency, compliance, etc.]
+- **Success Metrics**: [How do we measure success?]
+
+### Target State
+
+_Describe the expected state after this Epic is completed._
+
+---
+
+## Scope
+
+### In Scope
+
+- [ ] [Capability/Change 1]
+- [ ] [Capability/Change 2]
+- [ ] [Capability/Change 3]
+
+### Out of Scope
+
+- [ ] [Excluded capability 1]
+- [ ] [Excluded capability 2]
+
+---
+
+## Stories
+
+_Stories belonging to this Epic follow the naming pattern `s-eXXX-YYY-description.md`._
+
+| Story ID | Description | Status | Sprint |
+|----------|-------------|--------|--------|
+| [s-eXXX-001](../stories/backlog/s-eXXX-001-description.md) | [Brief description] | Backlog | — |
+| [s-eXXX-002](../stories/backlog/s-eXXX-002-description.md) | [Brief description] | Backlog | — |
+
+**Total Stories:** X  
+**Completed:** X  
+**Remaining:** X
+
+---
+
+## Dependencies
+
+### Depends On
+
+_Other Epics or Features this Epic depends on._
+
+| Dependency | Type | Status | Impact |
+|------------|------|--------|--------|
+| [epic-PRX-XXX](../epics/epic-PRX-XXX-description.md) | Blocks | Done | Must complete first |
+| [f-PRX-XXX](../../products/product-id/features/f-PRX-XXX-description.md) | Requires | Active | Feature must exist |
+
+### Blocked By
+
+_External blockers or waiting items._
+
+- [ ] [Blocker 1]
+- [ ] [Blocker 2]
+
+---
+
+## Risks & Assumptions
+
+### Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk 1] | High/Medium/Low | High/Medium/Low | [Mitigation plan] |
+
+### Assumptions
+
+- [Assumption 1]
+- [Assumption 2]
+
+---
+
+## Technical Considerations
+
+_High-level technical approach (SA input)._
+
+- **Architecture Impact**: [Description]
+- **Related TAI**: [tai-PRX-XXX if applicable]
+- **Performance Considerations**: [Description]
+
+---
+
+## Acceptance Criteria
+
+_Epic-level acceptance criteria (rolled up from stories)._
+
+- [ ] All linked stories marked as Done
+- [ ] Feature Canon updated via `ts:po sync`
+- [ ] UAT completed and signed off
+
+---
+
+## Timeline
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| Epic Approved | YYYY-MM-DD | [ ] |
+| All Stories Refined | YYYY-MM-DD | [ ] |
+| Development Start | YYYY-MM-DD | [ ] |
+| Development Complete | YYYY-MM-DD | [ ] |
+| UAT Sign-off | YYYY-MM-DD | [ ] |
+| Canon Synced | YYYY-MM-DD | [ ] |
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | @author | Initial draft |
+
+---
+
+## Linter Rules Enforced
+
+| Rule | Description | Status |
+|------|-------------|--------|
+| TS-EPIC-001 | Feature-Increment link required | Checked on save |
+| TS-EPIC-002 | TO-BE section required | Checked on save |
+| TS-EPIC-003 | Epic ID must be unique | Checked on save |
+| TS-NAMING-EPIC | Naming convention check | Checked on save |

package/teamspec-core/templates/feature-increment-template.md

@@ -0,0 +1,84 @@
+# Feature Increment: `<fi-PRX-XXX-description>`
+
+> **ID:** fi-PRX-XXX  
+> **Product:** `<product-id>` (PRX)  
+> **Target Feature:** `<f-PRX-XXX-feature-name>`  
+> **Epic:** `<epic-PRX-XXX>` _(link when assigned)_  
+> **Status:** draft | proposed | approved | implemented | synced
+
+---
+
+## 1. Overview
+
+_Brief description of what this increment changes._
+
+---
+
+## 2. AS-IS (Current State)
+
+> _Auto-populated from Product Feature. DO NOT EDIT unless correcting errors._
+
+### 2.1 Current Behavior
+
+_Copy relevant sections from the Product Feature Canon._
+
+### 2.2 Current Limitations
+
+_What can't the current system do that this increment addresses?_
+
+---
+
+## 3. TO-BE (Proposed State)
+
+### 3.1 New/Changed Behavior
+
+_Describe what the feature WILL do after this increment is implemented._
+
+### 3.2 Acceptance Criteria
+
+- [ ] AC-1: _Testable criterion_
+- [ ] AC-2: _Testable criterion_
+- [ ] AC-3: _Testable criterion_
+
+### 3.3 Out of Scope
+
+_Explicitly state what this increment does NOT include._
+
+---
+
+## 4. Impact Analysis
+
+### 4.1 Affected Features
+
+| Feature | Impact Type | Description |
+|---------|-------------|-------------|
+| f-PRX-XXX | Modified | _What changes_ |
+| f-PRX-YYY | Referenced | _No change, just dependency_ |
+
+### 4.2 Dependencies
+
+_Other increments or features this depends on._
+
+### 4.3 Risks
+
+_What could go wrong? How will we mitigate?_
+
+---
+
+## 5. Implementation Notes
+
+### 5.1 Technical Considerations
+
+_High-level technical approach (SA input)._
+
+### 5.2 Testing Strategy
+
+_How will this be validated? (QA input)_
+
+---
+
+## Change Log
+
+| Date | Author | Change |
+|------|--------|--------|
+| YYYY-MM-DD | @author | Initial draft |

package/teamspec-core/templates/feature-template.md

@@ -1,24 +1,34 @@
-# F-XXX: [Feature Name]
+# Feature: `f-{PRX}-{NNN}-{description}`
 
-<!-- 
+<!--
   ⚠️ FEATURE CANON RULES
-  
+
   This Feature file is the SOURCE OF TRUTH for system behavior.
-  
+
   RULES:
   1. Implementation-agnostic (describe WHAT, not HOW)
   2. No technical implementation details
-  3. Business rules use BR-XXX format
+  3. Business rules use BR-{PRX}-NNN format
   4. Change Log is append-only
-  
+  5. Feature ID uses product prefix (PRX)
+
+  NAMING PATTERN: f-{PRX}-{NNN}-{description}.md
+  EXAMPLE: f-ACME-001-user-login.md
+
   TEAMSPEC RULES ENFORCED:
   - TS-FEAT-001: Feature must have unique ID
   - TS-FEAT-002: All required sections must be present
   - TS-FEAT-003: Feature ID must be unique
 -->
 
-> **Template Version**: 2.0  
-> **Last Updated**: 2026-01-07
+> **Template Version**: 4.0
+> **Last Updated**: 2026-01-11
+
+---
+
+**Document Owner:** FA (Functional Analyst)
+**Artifact Type:** Feature (Product Canon)
+**Lifecycle:** Permanent, updated via Canon Sync after deployment
 
 ---
 
@@ -26,15 +36,16 @@
 
 | Field | Value |
 |-------|-------|
-| **Feature ID** | F-XXX |
+| **Feature ID** | f-{PRX}-{NNN} |
+| **Product** | {product-id} ({PRX}) |
 | **Status** | Planned / Active / Deprecated / Retired |
-| **Owner** | [BA creates, FA maintains behavior] |
+| **Owner** | FA (Functional Analyst) |
 | **Created** | YYYY-MM-DD |
 | **Last Updated** | YYYY-MM-DD |
 
-**Document Ownership:**
-- **BA owns:** Purpose, Business Value, Scope (In/Out)
-- **FA owns:** Current Behavior, Business Rules, Edge Cases
+**Section Ownership:**
+- **BA provides:** Purpose, Business Value, Scope (In/Out) via Business Analysis
+- **FA owns:** Current Behavior, Business Rules, Edge Cases, all updates
 
 ---
 
@@ -50,12 +61,12 @@
 | Scope (Out) | [ ] | What's excluded |
 | Actors/Personas | [ ] | Who uses it |
 | Current Behavior | [ ] | Primary behavior (authoritative) |
-| Business Rules | [ ] | BR-XXX format |
+| Business Rules | [ ] | BR-{PRX}-NNN format |
 | Edge Cases | [ ] | Known exceptions |
 | Non-Goals | [ ] | Explicitly excluded capabilities |
-| Change Log | [ ] | Story references |
+| Change Log | [ ] | Feature-Increment references |
 
-> ⚠️ Feature cannot be referenced by stories until all sections are complete.
+> ⚠️ Feature cannot be referenced by Feature-Increments until all sections are complete.
 
 ---
 
@@ -65,7 +76,7 @@ _Business decisions that shaped this feature's scope, behavior, or priority._
 
 | Decision ID | Summary | Impact on This Feature |
 |-------------|---------|------------------------|
-| [DEC-XXX](../decisions/DEC-XXX-*.md) | [One-line decision summary] | [Scoped in / Scoped out / Behavior changed / Priority set] |
+| [dec-{PRX}-{NNN}](../decisions/dec-{PRX}-{NNN}-*.md) | [One-line decision summary] | [Scoped in / Scoped out / Behavior changed / Priority set] |
 
 ---
 
@@ -165,8 +176,8 @@ _Logic that governs this feature's behavior._
 
 | Rule ID | Rule Description | Applies When |
 |---------|------------------|--------------|
-| BR-XXX-001 | [Rule description] | [Context] |
-| BR-XXX-002 | [Rule description] | [Context] |
+| BR-{PRX}-001 | [Rule description] | [Context] |
+| BR-{PRX}-002 | [Rule description] | [Context] |
 
 ---
 
@@ -220,7 +231,7 @@ _Features that interact with or depend on this one._
 
 | Feature ID | Relationship |
 |------------|--------------|
-| [F-XXX] | [Depends on / Extends / Conflicts with] |
+| [f-{PRX}-{NNN}](../features/f-{PRX}-{NNN}-*.md) | [Depends on / Extends / Conflicts with] |
 
 ---
 
@@ -231,21 +242,23 @@ _Features that interact with or depend on this one._
 > ⚠️ **APPEND-ONLY**: Never delete entries. This is the audit trail.  
 > Every completed story that adds/changes behavior MUST be logged here.
 
-| Date | Story ID | Change Summary | Author |
-|------|----------|----------------|--------|
-| YYYY-MM-DD | — | Initial feature creation | [BA Name] |
-| YYYY-MM-DD | S-XXX | [Description of change] | [FA Name] |
+| Date | Source | Change Summary | Author |
+|------|--------|----------------|--------|
+| YYYY-MM-DD | — | Initial feature creation | [FA Name] |
+| YYYY-MM-DD | fi-{PRX}-{NNN} | [Description of change synced from FI] | [FA Name] |
 
 ---
 
-## Story Ledger Reference
+## Feature-Increment Ledger
 
-> All stories that have modified this feature:
+> All Feature-Increments that have modified this feature (via Canon Sync):
 
-See [story-ledger.md](./story-ledger.md) for the complete history.
+| FI ID | Project | Sync Date | Summary |
+|-------|---------|-----------|---------|
+| [fi-{PRX}-{NNN}](../../projects/{project-id}/feature-increments/fi-{PRX}-{NNN}-*.md) | {project-id} | YYYY-MM-DD | [Change summary] |
 
-**Last Story:** S-XXX  
-**Last Update:** YYYY-MM-DD
+**Last FI:** fi-{PRX}-{NNN}
+**Last Sync:** YYYY-MM-DD
 
 ---
 
@@ -263,7 +276,7 @@ _Links to code, APIs, or technical documentation. Maintained by DEV._
 
 | Rule | Description |
 |------|-------------|
-| TS-FEAT-001 | Feature file must exist before stories can reference it |
+| TS-FEAT-001 | Feature file must exist before Feature-Increments can reference it |
 | TS-FEAT-002 | All required sections must be present |
-| TS-FEAT-003 | Feature ID must be unique |
-| TS-DOD-001 | Change Log must be updated when stories complete |
+| TS-FEAT-003 | Feature ID must be unique within product |
+| TS-NAMING-FEAT | Feature naming must follow f-{PRX}-{NNN}-{description}.md pattern |

package/teamspec-core/templates/increments-index-template.md

@@ -0,0 +1,53 @@
+# Feature Increments Index
+
+> **Project:** `<project-id>`  
+> **Target Products:** _List products this project modifies_
+
+## Overview
+
+Feature Increments (FI) describe **TO-BE** changes to Product Features.
+They are NOT the source of truth — the Product Canon is.
+
+When this project deploys and Canon is synced, these increments become part of the Product Canon.
+
+## Increment Registry
+
+| ID | Product | Feature | Status | Epic | Description |
+|----|---------|---------|--------|------|-------------|
+| _(none yet)_ | | | | | |
+
+## Increment Statuses
+
+| Status | Meaning |
+|--------|---------|
+| `draft` | Being written, not yet reviewed |
+| `proposed` | Ready for review |
+| `approved` | Accepted, ready for implementation |
+| `implemented` | Stories completed, ready for deployment |
+| `synced` | Deployed and merged to Product Canon |
+
+## ID Convention
+
+Feature Increment IDs inherit the Product Prefix:
+
+```
+fi-PRX-XXX-description.md
+│   │   │
+│   │   └── Sequential number (001, 002, ...)
+│   └────── Product Prefix (3-4 uppercase chars)
+└────────── Feature Increment prefix
+```
+
+**Example:** `fi-DIT-001-initiative-tracking.md` for DnD Initiative Tracker product
+
+---
+
+## Creating Feature Increments
+
+Use Copilot: `ts:fa feature-increment <product-id> <feature-id>`
+
+This command:
+1. Loads the AS-IS from the Product Feature
+2. Creates a new FI with TO-BE section to fill
+3. Registers it in this index
+4. Links the project to the product (if not already linked)

package/teamspec-core/templates/product-template.yml

@@ -0,0 +1,44 @@
+# Product Configuration Template
+# TeamSpec 4.0 - Product/Project Operating Model
+#
+# Usage: Copy this template to products/<product-id>/product.yml
+# Replace placeholders marked with <...>
+
+product:
+  # Unique slug identifier (lowercase, hyphens)
+  id: "<product-id>"
+  
+  # Human-readable name
+  name: "<Product Name>"
+  
+  # 3-4 uppercase character unique prefix
+  # Used in all artifact naming: f-PRX-001, ba-PRX-001, etc.
+  prefix: "<PRX>"
+  
+  # Product description (AS-IS state)
+  description: |
+    # TODO: Describe what this product IS (current state)
+    # - What problem does it solve?
+    # - Who are the users?
+    # - What are the key capabilities?
+  
+  # Product lifecycle status
+  status: active  # Options: active, deprecated, archived
+  
+  # List of projects currently modifying this product
+  # Automatically managed by TeamSpec when creating feature-increments
+  active_projects: []
+
+# Optional: Product metadata
+metadata:
+  # Product owner
+  owner: "<name or team>"
+  
+  # Creation date
+  created: "<YYYY-MM-DD>"
+  
+  # Domain/category
+  domain: "<domain>"
+  
+  # Related products (for cross-references)
+  related_products: []