specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/templates/spec-template.md

@@ -0,0 +1,267 @@
+# Feature Specification: [FEATURE NAME]
+
+**Version**: [VERSION]
+**Last Updated**: [DATE]
+**Status**: Draft | Active | Deprecated
+**Input**: User description: "$ARGUMENTS"
+
+---
+
+## Overview *(mandatory)*
+
+[What this feature is, who it is for, and what problem it solves — the reader's entry
+point to the spec. Two or three sentences; the requirements below carry the detail.]
+
+---
+
+<!--
+  ============================================================================
+  USER STORY WRITING GUIDE - READ CAREFULLY BEFORE PROCEEDING
+  ============================================================================
+
+  PART 1: INDEPENDENT TEST
+
+  Purpose: Enable non-technical PMs/stakeholders to verify features
+
+  KEY FORMULA:
+  Independent Test = [Specific Action] + [Observable Result] + [User Value]
+
+  QUALITY CHECKLIST:
+  □ Concrete: Can actually perform the test
+  □ Observable: Results are visible without code
+  □ Non-technical: No coding or technical tools needed
+  □ Independent: Can verify without other features
+  □ Valuable: Delivers clear user value
+
+  GOOD EXAMPLE (US2 - Remote Viewing):
+  "1. Launch the remote desktop app
+   2. Enter 192.168.1.100:5900 in the connection input field
+   3. Click the 'Connect' button
+   4. Observe the remote window open (< 3 seconds)
+   5. Open a text editor on the student computer and type some text
+   6. See the typed content appear on the teacher's screen (< 200ms latency)
+   7. Click 'Disconnect'; the window closes with no errors
+
+   Pass criteria: all steps complete smoothly, latency acceptable, no crashes
+   User value: the teacher can monitor student computers in real time and step in promptly"
+
+  BAD EXAMPLE:
+  ❌ "Test that the connection works" (too vague)
+  ❌ "Verify the protocol implementation" (technical)
+
+  ===========================================================================
+
+  PART 2: ACCEPTANCE SCENARIOS
+
+  Purpose: Comprehensive scenario coverage (5-9 scenarios per User Story)
+
+  COVERAGE REQUIREMENTS:
+  - Total: 5-9 scenarios per User Story
+  - Happy Path: 1-2 scenarios (core success case)
+  - Error Scenarios: 2-3 scenarios (error handling and recovery)
+  - Edge Cases: 1-2 scenarios (boundary conditions, constraints)
+  - Permission Scenarios: 1-2 scenarios (access control, authentication)
+
+  FORMAT:
+  Given [initial state]
+  When [action]
+  Then [expected outcome]
+
+  QUALITY CHECKLIST:
+  □ Functional: Describes WHAT, not HOW
+  □ Observable: Results can be seen/verified
+  □ Specific: Clear state, action, outcome
+  □ Independent: Each scenario stands alone
+  □ Complete: Covers all 4 scenario types
+
+  EXAMPLE (US2 - Remote Viewing - 7 scenarios):
+
+  Happy Path (1-2):
+  1. Given the teacher opens the remote viewing app and enters a valid server address 192.168.1.100:5900,
+     When clicking the "Connect" button,
+     Then the connection is established within 3 seconds and the remote desktop window opens showing the student's full desktop
+
+  2. Given a remote connection is established and the teacher can see the student's desktop,
+     When the student performs actions on their computer (opening apps, typing, moving windows),
+     Then the teacher's screen reflects all changes within 200ms
+
+  Error Scenarios (2-3):
+  3. Given the teacher opens the app and enters an invalid server address 192.168.1.999:5900,
+     When clicking the "Connect" button,
+     Then a friendly error message appears within 5 seconds: "Cannot connect to the server. Please check: 1) the server address, 2) that the server is running, 3) the network connection"
+
+  4. Given a remote connection is established and the teacher is viewing the student's desktop,
+     When the network suddenly drops (unplug the cable or turn off Wi-Fi),
+     Then the app detects the disconnection within 10 seconds, shows "Connection lost, reconnecting...", and attempts auto-reconnect 3 times within 30 seconds
+
+  Edge Cases (1-2):
+  5. Given a remote connection is established and a static desktop is displayed (using lossless encoding),
+     When the student starts playing a video (screen content becomes dynamic),
+     Then the app detects the content change within 2 seconds, switches to lossy H.264 encoding automatically, and video plays smoothly (> 15 FPS)
+
+  6. Given a remote connection is established and the student's screen resolution is 1920x1080,
+     When the student changes the resolution dynamically (e.g., to 2560x1440 or down to 1280x720),
+     Then the app detects the resolution change and resizes the remote window seamlessly without reconnecting
+
+  Permission Scenarios (1-2):
+  7. Given the server is password protected,
+     When the teacher attempts to connect without a password or with a wrong password,
+     Then a password dialog appears; a wrong password shows "Incorrect password, please retry" and the correct password connects successfully
+
+  COMMON MISTAKES:
+  ❌ Too few scenarios (<5): Missing edge cases or error handling
+  ❌ Too many scenarios (>9): Story is too large, needs splitting
+  ❌ Missing scenario type: Incomplete coverage
+  ❌ Technical details: "Database returns error" (should be: "System shows error message")
+  ❌ Vague outcomes: "Should work" (should be: "User sees confirmation message")
+  ❌ Performance metrics in scenarios: Use performance metrics in FR, not scenarios
+     (Exception: User-perceivable metrics like "200ms latency" are acceptable)
+
+  ===========================================================================
+-->
+
+## Change Summary *(auto-generated on update)*
+
+**Current Version**: [VERSION]
+**Previous Version**: [PREV_VERSION] (if applicable)
+**Update Type**: [Initial | Feature Addition | Refactor | Breaking Change | Bug Fix]
+
+### Changes Overview
+
+- **Added**: N new User Stories, M new Requirements
+- **Modified**: X existing items
+- **Deprecated**: Y items (marked as deprecated, kept for reference)
+
+<!-- ⚠️ **A four-table `### Detailed Changes` block used to sit here, and it was DELETED, not
+     moved** (`T239` / `ISS-212`). Two reasons, both checkable:
+     · **No consumer**: `grep -rn 'Detailed Changes' templates/ commands/` matched the heading
+       itself and nothing else — the sibling `### Changes Overview` *is* read (`specpro.specify.md`
+       greps it to build the commit message); this block was not.
+     · **It restated** what the per-item `**Lifecycle**:` fields and `### Changes Overview`
+       already carry — a second source for the same fact (形态 3), and the rule two paragraphs
+       down says why that is not allowed to stand.
+     ⇒ **Do not restore it.** Need the per-item detail? Read that item's own Lifecycle field —
+     that is the single source. -->
+> Change Summary logs CHANGED items only ([create]/[update]/[deprecated]);
+> unchanged items receive no entry (their Lifecycle fields stay as-is).
+>
+> ⚠️ **Never write a REMOVED value back into the summary.** When this block says
+> it stopped restating something, point at the thing itself (the field, the
+> section, the artifact) — **do not quote what was removed**, not even as a
+> quotation in backticks. A value sitting in prose is **indistinguishable from a
+> real Lifecycle field to any mechanical reader** (a `grep`, a leg count, a
+> propagation scan), and a human scanning the file takes it as current. The rule
+> is about the *action* of restating, not about the one instance that prompted
+> it: it applies equally to counts and to identifiers.
+
+---
+
+## 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
+-->
+
+### US1 - [Brief Title] (Priority: P1)
+
+**Lifecycle**: [specify:create][plan:create][tasks:create]
+
+[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]
+
+---
+
+### US2 - [Brief Title] (Priority: P2)
+
+**Lifecycle**: [specify:create][plan:create][tasks:create]
+
+[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]
+
+---
+
+### US3 - [Brief Title] (Priority: P3)
+
+**Lifecycle**: [specify:create][plan:create][tasks:create]
+
+[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]
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+All functional requirements are organized under the **"System MUST"** format and grouped by User Story for clear traceability.
+
+#### [User Story Title] (US[ID])
+
+  - **FR-XXX**: [Requirement Title]
+    **Lifecycle**: [specify:create][plan:create][tasks:create]
+    System MUST [specific requirement].
+
+  - **FR-XXX**: [Requirement Title]
+    **Lifecycle**: [specify:create][plan:create][tasks:create]
+    System MUST [specific requirement].
+
+#### [Another User Story Title] (US[ID])
+
+  - **FR-XXX**: [Requirement Title]
+    **Lifecycle**: [specify:create][plan:create][tasks:create]
+    System MUST [specific requirement].
+
+---
+
+## External Dependencies *(if applicable)*
+
+[The outside systems this feature's requirements depend on — and, for each, the product's
+behaviour when that system cannot be reached. ⚠️ Name the **functional** dependency (the
+system the product talks to), never the library, protocol or vendor product that happens to
+implement the connection: the implementation may change while the dependency stays the same.
+Omit this section entirely when the feature depends on no outside system.]
+
+- [Outside system] — [the product's behaviour when that system cannot be reached]
+
+---
+
+## Constitution Constraints *(if applicable)*
+
+[Add constitution constraints if any]
+
+---

specpro_cli/assets/templates/tasks-template.md

@@ -0,0 +1,252 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: Unit test tasks MAY be included here (OPTIONAL - only if explicitly requested in the feature specification). High-level tests (integration / component E2E / app E2E) are NOT defined in tasks.md.
+
+**High-Level Test Ownership**: Integration, component E2E, and application E2E tests are planned by `/specpro-test-plan` into `specs/test-tasks.md` and executed by `/specpro-test-implement`.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /specpro-tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] 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 that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> High-level tests are owned by `/specpro-test-plan` (see `specs/test-tasks.md`). Only unit-test tasks, if any, remain here.
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+> High-level tests are owned by `/specpro-test-plan` (see `specs/test-tasks.md`). Only unit-test tasks, if any, remain here.
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+> High-level tests are owned by `/specpro-test-plan` (see `specs/test-tasks.md`). Only unit-test tasks, if any, remain here.
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in the project's REAL unit-test source set (ground the path — never invent tests/unit/)
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence
+
+---
+
+> High-level tests (integration / component E2E / app E2E) are OUT of tasks.md scope: planned by `/specpro-test-plan`, executed by `/specpro-test-implement` (see `specs/test-tasks.md`).