teamspec 3.2.0

package/teamspec-core/copilot-instructions.md

@@ -0,0 +1,356 @@
+# Copilot Instructions for TeamSpec 2.0
+
+> **Version:** 2.0  
+> **Last Updated:** 2026-01-08  
+> **Status:** Active (Installed Instance)
+
+You are an expert Agile assistant working in a **TeamSpec 2.0** enabled workspace — utilizing the Feature Canon operating model for requirements management.
+
+---
+
+## What is TeamSpec?
+
+TeamSpec is an operating model that treats the **Feature Canon** as the SINGLE SOURCE OF TRUTH for all system behavior. All other artifacts (stories, test cases, dev plans) derive from or reference it.
+
+### Core Principle
+
+```
+The Feature Canon is the SINGLE SOURCE OF TRUTH for all system behavior.
+Everything else derives from or references it.
+```
+
+---
+
+## Workspace Structure
+
+This workspace uses TeamSpec with the following structure:
+
+```
+.teamspec/                   # Core framework (installed)
+├── templates/               # Document templates for all artifacts
+├── definitions/             # DoR/DoD checklists
+├── profiles/                # Profile overlays (regulated, startup, etc.)
+└── context/                 # Team configuration and custom rules
+    ├── team.yml             # Team metadata and preferences
+    └── _schema.yml          # Context schema definition
+
+projects/<project-id>/       # Project artifacts
+├── project.yml              # Project metadata (REQUIRED)
+├── features/                # Feature Canon (source of truth)
+│   ├── F-001-feature.md
+│   ├── features-index.md
+│   └── story-ledger.md
+├── stories/                 # Workflow folders
+│   ├── backlog/             # FA creates here
+│   ├── ready-to-refine/     # FA moves here for refinement
+│   └── ready-for-development/ # DEV moves here when ready
+├── adr/                     # Architecture Decision Records
+├── decisions/               # Business decisions
+├── dev-plans/               # Development task breakdowns
+├── qa/test-cases/           # Test documentation
+├── epics/                   # Epic definitions
+└── sprints/                 # Sprint folders
+    └── sprint-N/sprint-goal.md
+```
+
+---
+
+## Document Hierarchy
+
+| Level | Artifacts | Owner | Purpose |
+|-------|-----------|-------|---------|
+| **Source of Truth** | Feature Canon, Decision Log, ADR | BA/FA/SA | Defines WHAT exists |
+| **Execution** | Stories, Dev Plans, Test Cases | FA/DEV/QA | Defines WHAT to change |
+| **Operational** | Sprints, Status Reports | SM | Tracks progress |
+
+---
+
+## Role Boundaries (STRICT)
+
+| Role | Owns | Does NOT Own |
+|------|------|--------------|
+| **BA** | Purpose, Value, Scope, Business Decisions | Technical design, Implementation |
+| **FA** | Behavior, Flows, Business Rules, Stories | Architecture, Code |
+| **SA** | Architecture, ADRs, Technical Decisions | Business requirements |
+| **DEV** | Implementation, Dev Plans | Functional requirements |
+| **QA** | Test Cases, Bug Reports | Feature definitions |
+| **SM** | Sprint Management, Process | Content of deliverables |
+
+---
+
+## Story-as-Delta Philosophy
+
+Stories describe **CHANGES** to the Feature Canon:
+- **Before:** Reference current Canon behavior
+- **After:** Describe the delta (new/changed behavior)
+- **Impact:** Which Canon sections are affected
+
+**Example:**
+```markdown
+## Before
+Users can only log in with email/password (per F-001-authentication §2.1)
+
+## After
+Users can also log in with Google OAuth (adds new flow to F-001-authentication §2.3)
+
+## Impact
+- F-001-authentication: New section 2.3 "OAuth Login Flow"
+- F-001-authentication: Modified section 3.1 "Security Rules" to include OAuth tokens
+```
+
+---
+
+## Agent System
+
+TeamSpec uses **role-specific agents** located in `.teamspec/agents/`:
+
+| Agent | File | Purpose |
+|-------|------|---------|
+| Bootstrap | `AGENT_BOOTSTRAP.md` | Core rules inherited by all agents |
+| BA | `AGENT_BA.md` | Business Analysis tasks |
+| FA | `AGENT_FA.md` | Functional Analysis tasks |
+| SA | `AGENT_SA.md` | Solution Architecture tasks |
+| DEV | `AGENT_DEV.md` | Development tasks |
+| QA | `AGENT_QA.md` | Quality Assurance tasks |
+| SM | `AGENT_SM.md` | Scrum Master tasks |
+| DES | `AGENT_DES.md` | Design tasks |
+| FIX | `AGENT_FIX.md` | Auto-fix linting errors |
+
+### Using Agents
+
+To invoke an agent's capabilities:
+```
+ts:agent <role>           # Load role-specific agent
+ts:agent fix              # Run linter fix agent
+```
+
+---
+
+## Command Reference
+
+### CLI Commands (Terminal)
+
+```bash
+teamspec lint             # Lint all projects against TeamSpec rules
+teamspec lint --project X # Lint specific project
+teamspec update           # Update TeamSpec core files
+```
+
+### Copilot Commands (Chat)
+
+#### Agent Commands
+- `ts:agent ba` → Load BA agent from `.teamspec/agents/AGENT_BA.md`
+- `ts:agent fa` → Load FA agent from `.teamspec/agents/AGENT_FA.md`
+- `ts:agent dev` → Load DEV agent from `.teamspec/agents/AGENT_DEV.md`
+- `ts:agent qa` → Load QA agent from `.teamspec/agents/AGENT_QA.md`
+- `ts:agent sm` → Load SM agent from `.teamspec/agents/AGENT_SM.md`
+- `ts:agent sa` → Load SA agent from `.teamspec/agents/AGENT_SA.md`
+- `ts:agent fix` → Load FIX agent, auto-fix lint errors
+
+#### BA Commands (Business Analysis)
+- `ts:ba project` → Create/manage project structure
+- `ts:ba epic` → Propose epic structure
+- `ts:ba feature` → Extract feature from requirements
+- `ts:ba decision` → Log business decision
+- `ts:ba analysis` → Create business analysis document (process documentation)
+
+#### FA Commands (Functional Analysis)
+- `ts:fa story` → Create story in backlog
+- `ts:fa slice` → Slice requirements into stories
+- `ts:fa refine` → Move story to ready-to-refine
+- `ts:fa sync` → Update Feature Canon after story completion
+
+#### DEV Commands (Development)
+- `ts:dev plan` → Create dev plan for story
+- `ts:dev implement` → Execute implementation
+- `ts:dev ready` → Move story to ready-for-development
+
+#### QA Commands (Quality Assurance)
+- `ts:qa test` → Design test cases
+- `ts:qa dor-check` → Validate Definition of Ready
+- `ts:qa dod-check` → Validate Definition of Done
+
+#### SM Commands (Scrum Master)
+- `ts:sm sprint create` → Create new sprint
+- `ts:sm sprint plan` → Plan sprint backlog
+- `ts:sm sprint close` → Close sprint with metrics
+
+#### Universal Commands
+- `ts:status` → Project status overview
+- `ts:lint` → Run linter (equivalent to `teamspec lint`)
+- `ts:fix` → Auto-fix lint errors (invokes AGENT_FIX)
+
+---
+
+## Linting Rules
+
+The TeamSpec linter enforces these rule categories:
+
+| Category | Rules | Severity |
+|----------|-------|----------|
+| **TS-PROJ** | Project registration, project.yml metadata | ERROR |
+| **TS-FEAT** | Feature file existence, required sections, unique IDs | ERROR |
+| **TS-STORY** | Feature links, delta format, AC, DoR | ERROR |
+| **TS-ADR** | ADR requirements, feature linking | ERROR |
+| **TS-DEVPLAN** | Dev plan existence for sprint stories | ERROR |
+| **TS-DOD** | Canon sync when behavior changes | BLOCKER |
+| **TS-NAMING** | File naming conventions | WARNING |
+
+### Running the Linter
+
+```bash
+# From any TeamSpec-enabled workspace:
+teamspec lint
+
+# For specific project:
+teamspec lint --project acme-webshop
+```
+
+### Auto-Fixing Lint Errors
+
+Use the FIX agent to automatically resolve lint errors:
+```
+ts:agent fix
+```
+
+Or manually follow the rules in `.teamspec/agents/AGENT_FIX.md`.
+
+---
+
+## Naming Conventions
+
+| Artifact | Pattern | Example |
+|----------|---------|---------|
+| Feature | `F-NNN-description.md` | `F-001-user-auth.md` |
+| Story | `S-NNN-description.md` | `S-042-password-reset.md` |
+| ADR | `ADR-NNN-description.md` | `ADR-003-jwt-tokens.md` |
+| Decision | `DECISION-NNN-description.md` | `DECISION-015-pricing.md` |
+| Dev Plan | `story-NNN-tasks.md` | `story-042-tasks.md` |
+| Epic | `EPIC-NNN-description.md` | `EPIC-002-checkout.md` |
+
+---
+
+## Quality Gates
+
+### Definition of Ready (DoR)
+
+Before a story enters `ready-for-development/`:
+- [ ] Linked to Feature Canon
+- [ ] Before/After delta clearly described
+- [ ] Acceptance Criteria are testable
+- [ ] No TBD/placeholder content
+- [ ] Estimate assigned
+
+### Definition of Done (DoD)
+
+Before a story is marked Done:
+- [ ] All AC verified
+- [ ] Code reviewed and merged
+- [ ] Tests passing
+- [ ] **Feature Canon updated** (if behavior changed)
+- [ ] Documentation updated
+
+---
+
+## Templates
+
+All document templates are available in `.teamspec/templates/`:
+
+- `feature-template.md` → Feature Canon entries
+- `story-template.md` → User stories
+- `adr-template.md` → Architecture Decision Records
+- `decision-log-template.md` → Business decisions
+- `sprint-goal-template.md` → Sprint goals
+- `testcases-template.md` → Test cases
+- `bug-report-template.md` → Bug reports
+- `business-analysis-template.md` → Business analysis documents
+
+### Using Templates
+
+When creating artifacts, always reference the appropriate template:
+```
+ts:fa story    # Uses story-template.md
+ts:ba feature  # Uses feature-template.md
+ts:sa adr      # Uses adr-template.md
+```
+
+---
+
+## Output Guidelines
+
+When assisting with TeamSpec:
+
+1. **Template First**: Always use templates from `.teamspec/templates/`
+2. **No Placeholders**: Never leave TBD/TODO unless explicitly asked
+3. **Markdown Strict**: Output properly formatted Markdown
+4. **Feature Canon Reference**: Always link behavior to Feature Canon
+5. **Role Awareness**: Ask which role the user is acting as if unclear
+6. **Delta Format**: Stories MUST describe changes (before/after/impact)
+7. **Unique IDs**: Ensure all artifacts have unique sequential IDs
+
+---
+
+## Team Context
+
+This workspace has been configured with team-specific context in `.teamspec/context/team.yml`:
+
+```yaml
+# View your team's configuration:
+cat .teamspec/context/team.yml
+```
+
+Team context includes:
+- Organization and team name
+- Selected profile (regulated, startup, platform-team, enterprise)
+- Development cadence (Scrum, Kanban, Scrumban)
+- Sprint length (if applicable)
+- Industry and compliance requirements
+
+**Always respect the team context when making suggestions.**
+
+---
+
+## Common Workflows
+
+### Creating a New Feature
+1. Use `ts:ba feature` to extract from requirements
+2. Save to `projects/<project-id>/features/F-NNN-description.md`
+3. Update `features-index.md` with new feature entry
+4. Link from related stories
+
+### Creating a New Story
+1. Use `ts:fa story` to create in `stories/backlog/`
+2. Ensure Before/After/Impact sections reference Feature Canon
+3. Define testable Acceptance Criteria
+4. Move to `ready-to-refine/` when ready for refinement
+
+### Completing a Story
+1. Mark all AC as verified
+2. **Update Feature Canon** if behavior changed
+3. Create/update dev plan if needed
+4. Run `teamspec lint` to verify compliance
+5. Move story to Done
+
+### Making Architecture Decisions
+1. Use `ts:sa adr` to create ADR in `adr/`
+2. Link to affected Feature Canon sections
+3. Document decision, context, consequences
+4. Update team.yml if needed
+
+---
+
+## Getting Help
+
+- View all templates: `ls .teamspec/templates/`
+- View agent prompts: `ls .teamspec/agents/`
+- Check definitions: `cat .teamspec/definitions/definition-of-ready.md`
+- Run linter: `teamspec lint`
+- Update core files: `teamspec update`
+
+---
+
+## Version Information
+
+This workspace is using **TeamSpec 2.0** (Feature Canon Operating Model).
+
+For updates or issues, run `teamspec update` to get the latest core files.

package/teamspec-core/definitions/definition-of-done.md

@@ -0,0 +1,129 @@
+# Definition of Done (DoD)
+
+> **Version:** 2.0  
+> **Owner:** QA (validates completeness), SM (enforces at sprint close)
+
+A story is **Done** when ALL of the following are satisfied.
+
+---
+
+## Mandatory Checklist
+
+### 1. Code Complete ✓
+
+| Check | Required |
+|-------|----------|
+| All tasks in dev plan marked complete | ✓ |
+| Code merged to main/develop branch | ✓ |
+| No outstanding TODOs in code (for this story) | ✓ |
+
+### 2. Tests Pass ✓
+
+| Check | Required |
+|-------|----------|
+| Unit tests written and passing | ✓ |
+| Integration tests passing (if applicable) | ✓ |
+| Test coverage meets team threshold | ✓ |
+
+**Linter Rule:** `TS-DOD-002` — Tests are feature-level
+
+### 3. Code Reviewed ✓
+
+| Check | Required |
+|-------|----------|
+| Pull request reviewed and approved | ✓ |
+| All review comments addressed | ✓ |
+| CI/CD pipeline passing | ✓ |
+
+### 4. Acceptance Criteria Verified ✓
+
+| Check | Required |
+|-------|----------|
+| All ACs tested and passing | ✓ |
+| QA sign-off obtained | ✓ |
+| No critical bugs outstanding | ✓ |
+
+### 5. Feature Canon Updated ✓ (CRITICAL)
+
+| Check | Required |
+|-------|----------|
+| Feature file updated to reflect new behavior | ✓ |
+| Change Log entry added with story reference | ✓ |
+| Story Ledger updated | ✓ |
+| FA verified Canon sync | ✓ |
+
+**Linter Rule:** `TS-DOD-001` — Canon sync required before Done
+
+> ⚠️ **A story CANNOT be Done if it changes behavior and the Feature Canon is NOT updated.**
+
+---
+
+## Canon Sync Process
+
+Before marking a story Done:
+
+1. **FA runs `ts:fa sync`** — Updates Feature Canon
+2. **FA updates Change Log** — Links to story ID
+3. **FA updates Story Ledger** — Records in `features/story-ledger.md`
+4. **QA verifies** — Tests match updated Canon
+
+### Change Log Entry Format
+
+```markdown
+| Date | Story | Change Summary | Author |
+|------|-------|----------------|--------|
+| YYYY-MM-DD | S-XXX | Brief description | FA Name |
+```
+
+### Story Ledger Entry Format
+
+```markdown
+| Story ID | Title | Sprint | Features Modified | Merged Date |
+|----------|-------|--------|-------------------|-------------|
+| S-XXX | Story title | Sprint N | F-001, F-002 | YYYY-MM-DD |
+```
+
+---
+
+## Optional (Profile-Dependent)
+
+These checks apply based on team profile:
+
+### Regulated Profile
+
+| Check | Applies To |
+|-------|------------|
+| Compliance checklist signed off | regulated |
+| Audit trail documented | regulated |
+| Release notes updated | regulated |
+
+### Enterprise Profile
+
+| Check | Applies To |
+|-------|------------|
+| Documentation updated | enterprise |
+| Stakeholder notification sent | enterprise |
+
+---
+
+## Sprint Close Verification
+
+At sprint close, SM verifies:
+
+| Check | Owner |
+|-------|-------|
+| All "Done" stories have Canon sync | SM |
+| Story Ledger is current | FA |
+| No orphan stories (behavior change without Canon update) | QA |
+
+---
+
+## Quick Reference
+
+```
+DoD = Code + Tests + Review + ACs + Feature Canon Updated
+```
+
+**Most Common Failure:** Story marked "Done" without updating Feature Canon.
+
+If Canon is not updated, the story is **NOT DONE**.

package/teamspec-core/definitions/definition-of-ready.md

@@ -0,0 +1,104 @@
+# Definition of Ready (DoR)
+
+> **Version:** 2.0  
+> **Owner:** FA (gates story readiness), SM (enforces in sprint planning)
+
+A story is **Ready** for development when ALL of the following are satisfied.
+
+---
+
+## Mandatory Checklist
+
+### 1. Feature Canon Link ✓
+
+| Check | Required |
+|-------|----------|
+| Story links to existing Feature(s) in Feature Canon | ✓ |
+| Feature file exists in `features/` folder | ✓ |
+| Feature link uses correct format: `[F-XXX](../../features/F-XXX-name.md)` | ✓ |
+
+**Linter Rule:** `TS-STORY-001` — Feature link required
+
+### 2. Delta Format ✓
+
+| Check | Required |
+|-------|----------|
+| Story uses Before/After delta format | ✓ |
+| "Before" section references Feature Canon | ✓ |
+| "After" section describes ONLY the change | ✓ |
+| Story does NOT restate full feature behavior | ✓ |
+
+**Linter Rule:** `TS-STORY-002` — Delta-only format required
+
+### 3. Acceptance Criteria ✓
+
+| Check | Required |
+|-------|----------|
+| All ACs are testable (Given/When/Then or clear assertions) | ✓ |
+| No ambiguous terms ("should work well", "user-friendly") | ✓ |
+| ACs cover the delta, not the entire feature | ✓ |
+
+**Linter Rule:** `TS-STORY-003` — ACs must be testable
+
+### 4. FA Acceptance Gate ✓
+
+| Check | Required |
+|-------|----------|
+| FA has reviewed and initialed the story | ✓ |
+| FA confirms delta is correctly scoped | ✓ |
+| FA confirms feature link is correct | ✓ |
+
+**Gate:** FA Acceptance section complete in story
+
+### 5. Dev Plan Exists ✓
+
+| Check | Required |
+|-------|----------|
+| Dev plan file exists in `dev-plans/` | ✓ |
+| Story links to dev plan | ✓ |
+| Dev plan has no TBD/TODO items | ✓ |
+
+**Linter Rule:** `TS-DEVPLAN-001` — Dev plan required before implementation
+
+---
+
+## Optional (Profile-Dependent)
+
+These checks apply based on team profile:
+
+### Regulated Profile
+
+| Check | Applies To |
+|-------|------------|
+| Risk assessment completed | regulated |
+| Compliance impact documented | regulated |
+| Sign-off from compliance officer | regulated |
+
+### Enterprise Profile
+
+| Check | Applies To |
+|-------|------------|
+| Architecture review completed | enterprise |
+| Cross-team dependencies identified | enterprise |
+
+---
+
+## Workflow Gate
+
+Stories MUST be in `stories/ready-for-development/` folder to enter sprint.
+
+| From Folder | To Folder | Owner |
+|-------------|-----------|-------|
+| `backlog/` | `ready-to-refine/` | FA |
+| `ready-to-refine/` | `ready-for-development/` | DEV (after refinement) |
+| `ready-for-development/` | Sprint | SM (sprint planning) |
+
+---
+
+## Quick Reference
+
+```
+DoR = Feature Link + Delta Format + Testable ACs + FA Gate + Dev Plan
+```
+
+If any check fails, the story is **NOT READY** for development.

package/teamspec-core/profiles/enterprise.yml

@@ -0,0 +1,127 @@
+# Enterprise Profile
+
+> **Version:** 2.0  
+> **Applies To:** Large organizations, multi-team environments, enterprise software
+
+This profile adds governance, audit trails, and cross-team coordination.
+
+---
+
+## Profile Characteristics
+
+| Aspect | Configuration |
+|--------|---------------|
+| Governance Level | High |
+| Sign-off Required | Yes |
+| Audit Trail | Yes |
+| Change Control Board | Optional |
+| Documentation | Comprehensive |
+
+---
+
+## Additional Checkpoints
+
+### Definition of Ready Additions
+
+| Check | Enforcement |
+|-------|-------------|
+| Architecture review completed | Required |
+| Cross-team dependencies identified | Required |
+| Stakeholder approval obtained | Required |
+| Resource allocation confirmed | Required |
+
+### Definition of Done Additions
+
+| Check | Enforcement |
+|-------|-------------|
+| Documentation fully updated | Required |
+| Stakeholder sign-off obtained | Required |
+| Training materials updated (if user-facing) | Required |
+| Release communication sent | Required |
+
+---
+
+## Required Artifacts
+
+Enterprise stories SHOULD include:
+
+1. **Stakeholder Section**
+   ```markdown
+   ## Stakeholders
+   
+   | Stakeholder | Role | Sign-off Required |
+   |-------------|------|-------------------|
+   ```
+
+2. **Dependencies Section**
+   ```markdown
+   ## Dependencies
+   
+   | Dependency | Team | Status |
+   |------------|------|--------|
+   ```
+
+3. **Communication Plan**
+   ```markdown
+   ## Communication Plan
+   
+   - **Announcement Channel:** [Slack/Email/etc.]
+   - **Training Required:** [Yes/No]
+   - **Documentation Link:** [URL]
+   ```
+
+---
+
+## Governance Structure
+
+### Approval Hierarchy
+
+| Artifact | Approver |
+|----------|----------|
+| Feature (new) | BA + Product Owner |
+| Epic (new) | BA + Director |
+| Architecture Decision | SA + Tech Lead |
+| Story (high impact) | FA + BA |
+
+### Review Cadence
+
+| Review | Frequency | Participants |
+|--------|-----------|--------------|
+| Architecture Review | Weekly | SA, Tech Leads |
+| Feature Review | Bi-weekly | BA, FA, Product |
+| Sprint Review | End of sprint | Full team + stakeholders |
+
+---
+
+## Multi-Team Coordination
+
+For stories affecting multiple teams:
+
+1. **Identify teams** — List all affected teams
+2. **Align sprints** — Coordinate timing
+3. **Integration testing** — Plan cross-team testing
+4. **Communication** — Establish sync meetings
+
+---
+
+## Feature Canon Requirements
+
+For enterprise environments:
+
+1. **Version control** — All changes tracked
+2. **Approval history** — Who approved what
+3. **Impact analysis** — Dependencies documented
+4. **Traceability** — Link to business objectives
+
+---
+
+## Metrics and Reporting
+
+Track and report:
+
+| Metric | Purpose |
+|--------|---------|
+| Lead time | Story creation to deployment |
+| Cycle time | Development start to deployment |
+| Throughput | Stories per sprint |
+| Canon coverage | % features documented |