spec-kitty-cli 0.12.1__py3-none-any.whl

specify_cli/templates/git-hooks/pre-commit-encoding-check

@@ -0,0 +1,142 @@
+#!/usr/bin/env bash
+#
+# Pre-commit hook to validate UTF-8 encoding in markdown files
+#
+# This hook prevents commits containing Windows-1252 smart quotes and other
+# problematic characters that cause UTF-8 encoding errors in the dashboard.
+#
+# Installation:
+#   cp templates/git-hooks/pre-commit-encoding-check .git/hooks/pre-commit
+#   chmod +x .git/hooks/pre-commit
+#
+# Or to install during spec-kitty init, this template will be copied automatically.
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# Check if spec-kitty CLI is available
+if ! command -v spec-kitty &> /dev/null; then
+    echo -e "${YELLOW}Warning: spec-kitty command not found. Skipping encoding validation.${NC}"
+    echo "Install spec-kitty CLI to enable automatic encoding validation."
+    exit 0
+fi
+
+# Get list of staged markdown files
+STAGED_MD_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$' || true)
+
+if [ -z "$STAGED_MD_FILES" ]; then
+    # No markdown files staged, skip check
+    exit 0
+fi
+
+echo "Checking encoding for staged markdown files..."
+
+# Temporary flag to track if any files have issues
+HAS_ISSUES=false
+
+# Check each staged file for encoding issues
+for file in $STAGED_MD_FILES; do
+    if [ ! -f "$file" ]; then
+        continue
+    fi
+
+    # Use Python to check for problematic characters
+    if ! python3 -c "
+import sys
+try:
+    with open('$file', 'rb') as f:
+        data = f.read()
+    # Try strict UTF-8 decode
+    data.decode('utf-8')
+    sys.exit(0)
+except UnicodeDecodeError as e:
+    print(f'${RED}✗ Encoding error in $file at byte {e.start}${NC}', file=sys.stderr)
+    sys.exit(1)
+except Exception as e:
+    print(f'${YELLOW}Warning: Could not check $file: {e}${NC}', file=sys.stderr)
+    sys.exit(0)
+" 2>&1; then
+        HAS_ISSUES=true
+
+        # Show example problematic characters
+        echo -e "${YELLOW}  Found problematic characters (likely Windows-1252 smart quotes)${NC}"
+
+        # Try to show the problematic bytes using Python
+        python3 - "$file" <<'PYTHON' || true
+import sys
+import re
+
+# Problematic characters map
+PROBLEMATIC = {
+    '\u2018': "'",  # LEFT SINGLE QUOTATION MARK
+    '\u2019': "'",  # RIGHT SINGLE QUOTATION MARK
+    '\u201c': '"',  # LEFT DOUBLE QUOTATION MARK
+    '\u201d': '"',  # RIGHT DOUBLE QUOTATION MARK
+    '\u2013': "--", # EN DASH
+    '\u2014': "---", # EM DASH
+    '\u00b1': "+/-", # PLUS-MINUS SIGN
+    '\u00d7': "x",  # MULTIPLICATION SIGN
+    '\u00b0': " degrees", # DEGREE SIGN
+}
+
+file_path = sys.argv[1]
+
+try:
+    # Try reading with fallback encodings
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            content = f.read()
+    except UnicodeDecodeError:
+        with open(file_path, 'rb') as f:
+            data = f.read()
+        for encoding in ('cp1252', 'latin-1'):
+            try:
+                content = data.decode(encoding)
+                break
+            except UnicodeDecodeError:
+                continue
+        else:
+            content = data.decode('utf-8', errors='replace')
+
+    # Find problematic characters
+    lines = content.splitlines()
+    found = 0
+    for line_num, line in enumerate(lines, 1):
+        for char, replacement in PROBLEMATIC.items():
+            if char in line:
+                col = line.index(char)
+                print(f"  Line {line_num}, col {col}: '{char}' (U+{ord(char):04X}) → '{replacement}'")
+                found += 1
+                if found >= 5:  # Limit output
+                    if sum(1 for l in lines for c in PROBLEMATIC if c in l) > 5:
+                        print(f"  ... and more")
+                    sys.exit(0)
+except Exception as e:
+    print(f"  Could not analyze file: {e}", file=sys.stderr)
+PYTHON
+    fi
+done
+
+if [ "$HAS_ISSUES" = true ]; then
+    echo ""
+    echo -e "${RED}❌ Commit blocked: Encoding errors detected in markdown files${NC}"
+    echo ""
+    echo -e "${YELLOW}To fix these issues:${NC}"
+    echo "  1. Run: spec-kitty validate-encoding --all --fix"
+    echo "  2. Review the changes"
+    echo "  3. Re-stage the fixed files: git add <files>"
+    echo "  4. Commit again"
+    echo ""
+    echo -e "${YELLOW}Or to bypass this check (not recommended):${NC}"
+    echo "  git commit --no-verify"
+    echo ""
+    exit 1
+fi
+
+echo -e "${GREEN}✓ All staged markdown files are properly UTF-8 encoded${NC}"
+exit 0

specify_cli/templates/plan-template.md

@@ -0,0 +1,108 @@
+# Implementation Plan: [FEATURE]
+*Path: [templates/plan-template.md](templates/plan-template.md)*
+
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/kitty-specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/spec-kitty.plan` command. See `.kittify/templates/commands/plan.md` for the execution workflow.
+
+The planner will not begin until all planning questions have been answered—capture those answers in this document before progressing to later phases.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```
+kitty-specs/[###-feature]/
+├── plan.md              # This file (/spec-kitty.plan command output)
+├── research.md          # Phase 0 output (/spec-kitty.plan command)
+├── data-model.md        # Phase 1 output (/spec-kitty.plan command)
+├── quickstart.md        # Phase 1 output (/spec-kitty.plan command)
+├── contracts/           # Phase 1 output (/spec-kitty.plan command)
+└── tasks.md             # Phase 2 output (/spec-kitty.tasks command - NOT created by /spec-kitty.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+*Fill ONLY if Constitution Check has violations that must be justified*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

specify_cli/templates/spec-template.md

@@ -0,0 +1,118 @@
+# Feature Specification: [FEATURE NAME]
+*Path: [templates/spec-template.md](templates/spec-template.md)*
+
+<!-- Replace [FEATURE NAME] with the confirmed friendly title generated during /spec-kitty.specify. -->
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

specify_cli/templates/task-prompt-template.md

@@ -0,0 +1,165 @@
+---
+work_package_id: "WPxx"
+subtasks:
+  - "Txxx"
+title: "Replace with work package title"
+phase: "Phase N - Replace with phase name"
+lane: "planned"  # Edit directly or use: spec-kitty agent tasks move-task <WPID> --to <lane>
+assignee: ""      # Optional friendly name when in doing/for_review
+agent: ""         # CLI agent identifier (claude, codex, etc.)
+shell_pid: ""     # PID captured when the task moved to the current lane
+review_status: "" # empty | has_feedback | acknowledged (populated by reviewers/implementers)
+reviewed_by: ""   # Agent ID of the reviewer (if reviewed)
+history:
+  - timestamp: "{{TIMESTAMP}}"
+    lane: "planned"
+    agent: "system"
+    shell_pid: ""
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+*Path: [templates/task-prompt-template.md](templates/task-prompt-template.md)*
+
+
+# Work Package Prompt: {{work_package_id}} – {{title}}
+
+## ⚠️ IMPORTANT: Review Feedback Status
+
+**Read this first if you are implementing this task!**
+
+- **Has review feedback?**: Check the `review_status` field above. If it says `has_feedback`, scroll to the **Review Feedback** section immediately (right below this notice).
+- **You must address all feedback** before your work is complete. Feedback items are your implementation TODO list.
+- **Mark as acknowledged**: When you understand the feedback and begin addressing it, update `review_status: acknowledged` in the frontmatter.
+- **Report progress**: As you address each feedback item, update the Activity Log explaining what you changed.
+
+---
+
+## Review Feedback
+
+> **Populated by `/spec-kitty.review`** – Reviewers add detailed feedback here when work needs changes. Implementation must address every item listed below before returning for re-review.
+
+*[This section is empty initially. Reviewers will populate it if the work is returned from review. If you see feedback here, treat each item as a must-do before completion.]*
+
+---
+
+## ⚠️ Dependency Rebase Guidance
+
+**If this WP depends on other WPs** (check frontmatter `dependencies:` field):
+
+When a parent WP changes during review:
+1. You'll need to rebase your workspace to get latest changes
+2. Command: `cd .worktrees/{{feature_slug}}-{{work_package_id}} && git rebase {{feature_slug}}-{{base_wp_id}}`
+3. Resolve any conflicts
+4. Continue work on updated foundation
+
+**Check if rebase needed**:
+```bash
+cd .worktrees/{{feature_slug}}-{{work_package_id}}
+git log --oneline main..{{base_branch}}  # Shows commits in base not in your workspace
+```
+
+**If this WP has dependent WPs** (other WPs depend on this one):
+
+When you make changes:
+1. Notify agents working on dependent WPs
+2. They'll need to rebase their workspaces to get your changes
+3. This is a git limitation - future jj integration will auto-rebase
+
+The `spec-kitty implement` command will display warnings when:
+- You resume work and the base has changed
+- You start work and other WPs depend on you
+
+---
+
+## Objectives & Success Criteria
+
+- Summarize the exact outcomes that mark this work package complete.
+- Call out key acceptance criteria or success metrics for the bundle.
+
+## Context & Constraints
+
+- Reference prerequisite work and related documents.
+- Link to supporting specs: `.kittify/memory/constitution.md`, `kitty-specs/.../plan.md`, `kitty-specs/.../tasks.md`, data model, contracts, research, quickstart.
+- Highlight architectural decisions, constraints, or trade-offs to honor.
+
+## Subtasks & Detailed Guidance
+
+### Subtask TXXX – Replace with summary
+- **Purpose**: Explain why this subtask exists.
+- **Steps**: Detailed, actionable instructions.
+- **Files**: Canonical paths to update or create.
+- **Parallel?**: Note if this can run alongside others.
+- **Notes**: Edge cases, dependencies, or data requirements.
+
+### Subtask TYYY – Replace with summary
+- Repeat the structure above for every included `Txxx` entry.
+
+## Test Strategy (include only when tests are required)
+
+- Specify mandatory tests and where they live.
+- Provide commands or scripts to run.
+- Describe fixtures or data seeding expectations.
+
+## Risks & Mitigations
+
+- List known pitfalls, performance considerations, or failure modes.
+- Provide mitigation strategies or monitoring notes.
+
+## Review Guidance
+
+- Key acceptance checkpoints for `/spec-kitty.review`.
+- Any context reviewers should revisit before approving.
+
+## Activity Log
+
+> **CRITICAL**: Activity log entries MUST be in chronological order (oldest first, newest last).
+
+### How to Add Activity Log Entries
+
+**When adding an entry**:
+1. Scroll to the bottom of this file (Activity Log section below "Valid lanes")
+2. **APPEND the new entry at the END** (do NOT prepend or insert in middle)
+3. Use exact format: `- YYYY-MM-DDTHH:MM:SSZ – agent_id – lane=<lane> – <action>`
+4. Timestamp MUST be current time in UTC (check with `date -u "+%Y-%m-%dT%H:%M:%SZ"`)
+5. Lane MUST match the frontmatter `lane:` field exactly
+6. Agent ID should identify who made the change (claude-sonnet-4-5, codex, etc.)
+
+**Format**:
+```
+- YYYY-MM-DDTHH:MM:SSZ – <agent_id> – lane=<lane> – <brief action description>
+```
+
+**Example (correct chronological order)**:
+```
+- 2026-01-12T10:00:00Z – system – lane=planned – Prompt created
+- 2026-01-12T10:30:00Z – claude – lane=doing – Started implementation
+- 2026-01-12T11:00:00Z – codex – lane=for_review – Implementation complete, ready for review
+- 2026-01-12T11:30:00Z – claude – lane=done – Review passed, all tests passing  ← LATEST (at bottom)
+```
+
+**Common mistakes (DO NOT DO THIS)**:
+- ❌ Adding new entry at the top (breaks chronological order)
+- ❌ Using future timestamps (causes acceptance validation to fail)
+- ❌ Lane mismatch: frontmatter says `lane: "done"` but log entry says `lane=doing`
+- ❌ Inserting in middle instead of appending to end
+
+**Why this matters**: The acceptance system reads the LAST activity log entry as the current state. If entries are out of order, acceptance will fail even when the work is complete.
+
+**Initial entry**:
+- {{TIMESTAMP}} – system – lane=planned – Prompt created.
+
+---
+
+### Updating Lane Status
+
+To change a work package's lane, either:
+
+1. **Edit directly**: Change the `lane:` field in frontmatter AND append activity log entry
+2. **Use CLI**: `spec-kitty agent tasks move-task <WPID> --to <lane> --note "message"`
+
+The CLI command updates both frontmatter and activity log automatically (recommended).
+
+**Valid lanes**: `planned`, `doing`, `for_review`, `done`
+
+### File Structure
+
+All WP files live in a flat `tasks/` directory. The lane is determined by the `lane:` frontmatter field, not the directory location.

specify_cli/templates/tasks-template.md

@@ -0,0 +1,161 @@
+---
+description: "Work package task list template for feature implementation"
+---
+*Path: [templates/tasks-template.md](templates/tasks-template.md)*
+
+
+# Work Packages: [FEATURE NAME]
+
+**Inputs**: Design documents from `/kitty-specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (user stories), research.md, data-model.md, contracts/, quickstart.md
+
+**Tests**: Only include explicit testing work when stakeholders request it.
+
+**Organization**: Fine-grained subtasks (`Txxx`) roll up into work packages (`WPxx`). Each work package must be independently deliverable and testable.
+
+**Prompt Files**: Each work package references a matching prompt file in `/tasks/` generated by `/spec-kitty.tasks`. Lane status is stored in YAML frontmatter (`lane: planned|doing|for_review|done`). Treat this file as the high-level checklist; keep deep implementation detail inside the prompt files.
+
+## Subtask Format: `[Txxx] [P?] Description`
+- **[P]** indicates the subtask can proceed in parallel (different files/components).
+- Include precise file paths or modules.
+
+## Path Conventions
+- **Single project**: `src/`, `tests/`
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/`, `android/src/`
+- Adjust paths to match the implementation plan.
+
+<!-- SAMPLE CONTENT BELOW. MUST BE REPLACED. -->
+
+---
+
+## Work Package WP01: Setup & Environment (Priority: P0)
+
+**Goal**: Establish project skeleton and shared tooling.
+**Independent Test**: Project bootstraps locally with linting and formatter hooks in place.
+**Prompt**: `/tasks/WP01-setup-and-environment.md`
+
+### Included Subtasks
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+### Implementation Notes
+- Major steps, commands, or configuration files required.
+
+### Parallel Opportunities
+- Highlight subtasks that can proceed concurrently.
+
+### Dependencies
+- None (starting package).
+
+### Risks & Mitigations
+- Example: Tooling compatibility across contributors; pin versions in `.tool-versions`.
+
+---
+
+## Work Package WP02: Foundational Platform (Priority: P0)
+
+**Goal**: Deliver shared services all user stories depend on.
+**Independent Test**: Foundational services pass smoke tests; downstream work packages can start.
+**Prompt**: `/tasks/WP02-foundational-platform.md`
+
+### Included Subtasks
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities shared across stories
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+### Implementation Notes
+- Provide sequencing, infrastructure CLI commands, secrets requirements.
+
+### Parallel Opportunities
+- Authentication and routing can proceed in parallel once schema scaffolding exists.
+
+### Dependencies
+- Depends on WP01.
+
+### Risks & Mitigations
+- Migration drift → enforce migration linting in CI.
+
+---
+
+## Work Package WP03: User Story 1 – [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of story outcome]
+**Independent Test**: [Describe how to validate the story independently]
+**Prompt**: `/tasks/WP03-user-story-1.md`
+
+### Included Subtasks
+- [ ] T010 [P] Contract test for [endpoint] in `tests/contract/test_[name].py`
+- [ ] T011 [P] Integration test for [journey] in `tests/integration/test_[name].py`
+- [ ] T012 [P] Create [Entity1] model in `src/models/[entity1].py`
+- [ ] T013 [P] Create [Entity2] model in `src/models/[entity2].py`
+- [ ] T014 Implement [Service] in `src/services/[service].py` (depends on T012, T013)
+- [ ] T015 Implement [endpoint/feature] in `src/[location]/[file].py`
+- [ ] T016 Add validation and error handling
+- [ ] T017 Add story-specific logging and metrics
+
+### Implementation Notes
+- Enumerate the workflow (tests first if required, then models → services → endpoints).
+
+### Parallel Opportunities
+- Mention any subtasks that can be split among engineers safely.
+
+### Dependencies
+- Depends on WP02.
+
+### Risks & Mitigations
+- Data integrity risk → include migration rollback plan.
+
+---
+
+## Work Package WP0N: Polish & Cross-Cutting (Priority: Px)
+
+**Goal**: Cross-story improvements and hardening work.
+**Independent Test**: Regression suite passes; observability and documentation updated.
+**Prompt**: `/tasks/WP0N-polish-and-cross-cutting.md`
+
+### Included Subtasks
+- [ ] T0XX Documentation updates in `docs/`
+- [ ] T0XX Code cleanup and refactoring
+- [ ] T0XX Performance optimization across stories
+- [ ] T0XX Security hardening
+- [ ] T0XX Validate quickstart.md scenario
+
+### Implementation Notes
+- Capture finishing touches and validation guidance.
+
+### Parallel Opportunities
+- Identify items safe to run alongside final story testing.
+
+### Dependencies
+- Depends on completion of relevant story packages.
+
+### Risks & Mitigations
+- Regression risk → enforce smoke test before release.
+
+---
+
+## Dependency & Execution Summary
+
+- **Sequence**: WP01 → WP02 → Story-driven packages (priority order) → WP0N polish.
+- **Parallelization**: Highlight safe parallel combinations once prerequisites complete.
+- **MVP Scope**: Call out which work packages constitute the minimal release.
+
+---
+
+## Subtask Index (Reference)
+
+| Subtask ID | Summary | Work Package | Priority | Parallel? |
+|------------|---------|--------------|----------|-----------|
+| T001       | Example | WP01         | P0       | No        |
+| T002       | Example | WP01         | P0       | Yes       |
+| T010       | Example | WP03         | P1       | Yes       |
+| T014       | Example | WP03         | P1       | No        |
+
+---
+
+> Replace all placeholder text above with feature-specific content. Keep this template structure intact so downstream automation can parse work packages reliably.