specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/templates/agent-context-template.md

@@ -0,0 +1,49 @@
+# Agent Context Template
+
+SpecPro template for AI-agent context files (`CLAUDE.md` for Claude Code; `AGENTS.md` / `.cursorrules` / equivalent for other terminals).
+
+**Used by**: `/specpro-plan` Step 4.4 (Agent context check)
+
+- File missing or empty → generate from the template below
+- File exists → check equivalence against this template; equivalent → leave untouched; entries missing/contradictory → add/fix ONLY those entries
+
+**Rendering rules**:
+- Structural anchors (headings, command names, file paths) stay in English as written
+- Prose rendered in the project's Artifact Language
+- The ONLY project-specific content is the Project Overview sentence — fill the two placeholders; everything else is generic specpro guidance
+
+---
+
+## Template
+
+```markdown
+# Project Guide
+
+## Project Overview
+<Project> is a <one-line application domain> application built with SDD (Specification-Driven Development).
+
+## Project Navigation
+[docs/implement/PROJECT_NAVIGATION.md](docs/implement/PROJECT_NAVIGATION.md)
+<!-- may not exist: this file is created by /specpro-implement (up-front or with the first
+     technical document in docs/implement/). Omit this section when absent. -->
+
+## Coding Iron Rules ⚠️
+- **Never code directly on user instruction** — e.g. when the user says "add feature X to module Y", do NOT modify code directly.
+- All coding work MUST happen inside the specpro command context (`/specpro-constitution` → `/specpro-specify` → `/specpro-plan` → `/specpro-tasks` → `/specpro-implement`, ...).
+- Test planning & execution: `/specpro-test-plan` → `/specpro-test-implement`.
+- Manual acceptance testing: `/specpro-manual-test` drives `specs/manual-test-tasks.md`; after all pass, `specs/acceptance.md` is generated at the acceptance gate.
+- End-user manual: `/specpro-user-manual` generates `docs/user_manual/user-guide.md` from implemented features only.
+
+## Working Method
+- ⚠️ **Where a finding goes — one pointer, no copy.** The criterion for *which ledger section a finding belongs to* has **one authority**: `commands/specpro.analyze.md` → its **Routing** table (together with that step's pre-exclusion and shape gate). **Never restate its branches**, here or in any other artifact: two copies of one criterion diverge silently, and a reader who follows the stale copy files the finding where its consumer never looks. `specs/contracts/ledger.md` and the specification's routing requirement **point at** that table rather than repeating it — follow the same shape. ⚠️ **This pointer deliberately carries no branch of its own**: a pointer that helpfully lists the branches *has become* a copy of the thing it points at. The pointer is exactly this: *"which section? → that table."*
+- AI development starts from invoking specpro commands; the files to read (spec.md, plan.md, tasks.md, test-tasks.md, ...) are indicated step by step by specpro commands.
+- This file keeps only required-reading pointers and NEVER repeats technical details. Tech stack, architecture, and test standards live in specs/ (constitution.md, plan.md).
+```
+
+---
+
+## Content Discipline ⚠️
+
+- The ONLY project-specific line is the Project Overview sentence (application scope + "built with SDD"). **NO module lists, NO directory trees, NO tech-stack detail** — they rot into misinformation, and AI agents can explore the repo / read plan.md themselves. Technology architecture single source: plan.md.
+- The Project Navigation section links `docs/implement/PROJECT_NAVIGATION.md`, which **may not exist** (created by `/specpro-implement` up-front or with the first technical document). Include the section only when the file is present.
+- **NEVER append machine-maintained sections** — "Active Technologies" / "Recent Changes" style incremental logs are forbidden. The agent context file stays a thin, human-owned pointer.

specpro_cli/assets/templates/assumptions-template.md

@@ -0,0 +1,248 @@
+# Critical Assumptions
+
+**Feature**: [FEATURE_NAME]
+**Created**: [DATE]
+**Status**: [In Progress | Resolved]
+
+---
+
+## Purpose
+
+These are **CRITICAL assumptions** that MUST be clarified **BEFORE** the specification can be generated.
+
+Unlike clarifications (which improve spec quality), these assumptions affect the **fundamental architecture and direction** of the feature. The spec generation **CANNOT proceed** until these are resolved.
+
+**Key Characteristics**:
+- 🔑 **Critical**: Without these answers, we cannot generate a reasonable specification
+- 🚧 **Blocking**: Spec generation is blocked until all assumptions are resolved
+- 🌳 **Dynamic**: New assumptions may emerge based on previous answers
+- 📊 **Decision Path**: Answers guide the architectural direction
+
+---
+
+## Format
+
+Each assumption entry follows this format:
+
+```markdown
+### [ID] - [Critical Decision]
+
+**Status**: [ ] Pending | [x] Resolved
+
+**Context**: [What led to this question - previous decisions or user input]
+
+**Impact**: [What this affects - architecture, scope, user experience, platform]
+
+**Question**:
+[Clear, specific question that must be answered to continue spec generation]
+
+**Options** (if applicable):
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | [First option] | [What this means for the feature] |
+| B | [Second option] | [What this means for the feature] |
+| C | [Third option] | [What this means for the feature] |
+
+**Recommended**: [Option X] - [Brief reasoning based on context]
+
+**Answer**:
+[User's answer that resolves the assumption]
+
+**Resolution**:
+- How this answer guides spec generation
+- Related architectural decisions
+- Follow-up assumptions that may emerge
+```
+
+---
+
+## Quality Gate
+
+**CRITICAL**: Spec generation **CANNOT proceed** until ALL assumptions have status `[x]` (Resolved).
+
+---
+
+## Decision Path
+
+*This section will be dynamically populated as assumptions are resolved*
+
+### Decision History
+
+*Resolved assumptions will appear here, showing the complete decision path*
+
+---
+
+## Current Assumptions
+
+*Pending assumptions will appear here*
+
+---
+
+## Skipped Decisions (Optional)
+
+*Assumptions that were considered but deemed not applicable based on previous answers*
+
+Format:
+```markdown
+### ~~[ID] - [Skipped Decision]~~
+
+**Status**: [⊘] Skipped (not applicable)
+
+**Reason**: [Explanation of why this is not applicable based on previous answers]
+
+**Dependency**: [Which assumption made this irrelevant]
+```
+
+---
+
+## Summary
+
+**Total Assumptions**: N
+- Resolved: X/N
+- Pending: Y/N
+- Skipped: Z
+
+**Completion Criteria**:
+- ALL current assumptions MUST be resolved (status `[x]`)
+- No pending assumptions remain
+- Ready for spec generation ✓
+
+---
+
+## Examples
+
+### Example 1: Initial Critical Decision
+
+### A001 - Application Type
+
+**Status**: [x] Resolved
+
+**Context**: User input: "Build me a notepad app"
+
+**Impact**: Architecture, Data Model, Deployment, Platform
+
+**Question**: Should this be a local application or web-based application?
+
+**Options**:
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | Local application | Offline-first, local storage, desktop/mobile apps |
+| B | Web-based | Online-first, cloud sync, backend API required |
+
+**Recommended**: Option A - Local application aligns with typical "notepad" use cases for offline note-taking
+
+**Answer**: Option A (Local application)
+
+**Resolution**:
+- Spec will focus on offline-first architecture
+- Local data storage required
+- Desktop and/or mobile platforms
+- No backend/infrastructure needed
+
+---
+
+### Example 2: Emergent Assumption (Depends on A001)
+
+### A002 - Target Platform
+
+**Status**: [x] Resolved
+
+**Context**: Previous decision: A001=Local application
+
+**Impact**: Framework choice, UI architecture, deployment strategy
+
+**Question**: Which platform(s) should be supported?
+
+**Options**:
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | Desktop only | Windows, macOS, Linux native apps |
+| B | Mobile only | iOS, Android native apps |
+| C | Cross-platform | Shared codebase with platform-specific UIs |
+
+**Recommended**: Option C - Cross-platform maximizes reach with a shared-codebase toolkit
+
+**Answer**: Option C (Cross-platform)
+
+**Resolution**:
+- Use a cross-platform shared-logic framework
+- A cross-platform UI toolkit on top of it
+- Maximum code reuse across platforms
+- Native performance on each platform
+
+---
+
+### Example 3: Further Granularity
+
+### A003 - Local Storage Format
+
+**Status**: [x] Resolved
+
+**Context**: Previous decisions: A001=Local, A002=Cross-platform
+
+**Impact**: Data schema, query capabilities, migration strategy
+
+**Question**: What local storage format should be used?
+
+**Options**:
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | SQLite | Structured queries, relational data, type-safe |
+| B | File-based (JSON/Text) | Simple format, human-readable, limited querying |
+| C | Platform-specific (Core Data/Room) | Native performance, less code sharing |
+
+**Recommended**: Option A - SQLite with a type-safe query layer enables cross-platform schema sharing
+
+**Answer**: Option A (SQLite)
+
+**Resolution**:
+- A type-safe query layer over SQLite
+- Shared schema across all platforms
+- Migration strategy needed for schema changes
+
+---
+
+### Example 4: Skipped Decision
+
+### ~~A004 - Backend Technology~~
+
+**Status**: [⊘] Skipped (not applicable)
+
+**Reason**: Backend technology is only needed for web-based applications
+
+**Dependency**: A001=Local application (not web-based)
+
+**Original Options** (if it were applicable):
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | REST API | Standard HTTP API, stateless |
+| B | GraphQL | Flexible queries, single endpoint |
+| C | gRPC | High-performance, protocol buffers |
+
+---
+
+## Final Decision Path Example
+
+**Feature**: Notepad
+**Status**: ✅ All Resolved (3 assumptions)
+
+### Decision Path:
+1. ✅ A001: Local application
+2. ✅ A002: Cross-platform
+3. ✅ A003: SQLite storage
+
+### Architectural Direction:
+- **Architecture**: Offline-first, local SQLite database
+- **Platform**: Cross-platform shared codebase (Desktop + Mobile)
+- **Storage**: Type-safe query layer over SQLite, shared schema
+- **Key FRs**: Local storage, cross-platform UI, data export
+
+### Skipped Decisions:
+- ~~A004~~: Backend technology (not needed - local app)
+- ~~A005~~: Real-time sync (not needed - local app)
+- ~~A006~~: Web framework (not needed - not web)
+
+---
+
+**Last Updated**: [TIMESTAMP]
+**Ready for Spec Generation**: [YES | NO]

specpro_cli/assets/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/specpro-checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /specpro-checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

specpro_cli/assets/templates/clarifications-template.md

@@ -0,0 +1,155 @@
+# Clarifications
+
+**Feature**: [FEATURE_NAME]
+**Created**: [DATE]
+**Status**: [In Progress | Completed]
+**Spec Version**: [VERSION]
+
+---
+
+## Overview
+
+This file tracks all questions identified during specification that require clarification, inference, or user confirmation. It ensures quality gates before proceeding to planning and implementation.
+
+**Purpose**:
+- **Quality Gate**: Plan stage cannot proceed until all [Must Clarify] items are resolved
+- **Traceability**: Each question links to specific sections in spec.md
+- **Automation**: AI can auto-infer [Can Infer] and some [Suggested Clarify] items
+
+---
+
+## Clarification Categories
+
+- **[Must Clarify]**: Critical questions that MUST be answered by the user before implementation. Plan stage is BLOCKED until these are resolved.
+- **[Suggested Clarify]**: Important questions with reasonable defaults. User can choose to answer manually OR request AI auto-inference.
+- **[Can Infer]**: Questions that AI can answer using context, industry standards, or logical inference. AI will auto-resolve these.
+
+---
+
+## Format
+
+Each clarification entry follows this format:
+
+```markdown
+### [Tag] - [ID] - [Question Summary]
+
+**Status**: [ ] Unanswered | [x] Answered | [inferred] Auto-inferred
+
+**Related Section**: [spec.md section reference, e.g., "FR-xxx", "US2"]
+
+**Question**:
+[Clear, specific question about requirements]
+
+**Options** (if applicable):
+| Option | Description | Implications |
+|--------|-------------|--------------|
+| A | [First option] | [What this means] |
+| B | [Second option] | [What this means] |
+| Auto | Let AI infer from context | [What AI will do] |
+
+**Answer** (when answered or inferred):
+[Concise answer that resolves the question]
+
+**Resolution** (when answered or inferred):
+- Updated spec.md section: [section name]
+- New/updated FR: [FR-XXX] (if applicable)
+- Details: [how the answer was integrated]
+
+---
+
+## Clarification Items
+
+### [Must Clarify] Items
+
+*Status: All items in this category must be resolved before Plan stage*
+
+- **[Must Clarify] - Q001** - [Example: Target deployment network bandwidth]
+  **Status**: [ ]
+  **Related Section**: FR-xxx, Performance Constraints
+  **Question**: What is the expected network bandwidth (Mbps) for typical classroom deployment? This affects performance targets and encoding strategy.
+  **Options**:
+  | Option | Bandwidth | Implications |
+  |--------|-----------|--------------|
+  | A | <100 Mbps | Requires aggressive compression, may affect video quality |
+  | B | 100-1000 Mbps | Standard classroom network, supports HD video |
+  | C | >1 Gbps | High-performance network, supports 4K video |
+  **Answer**: (waiting for user input)
+
+---
+
+### [Suggested Clarify] Items
+
+*Status: User can choose to answer manually OR request AI auto-inference. Plan stage NOT blocked by these.*
+
+- **[Suggested Clarify] - Q002** - [Example: Plugin hot-reload frequency]
+  **Status**: [ ]
+  **Related Section**: FR-xxx, Plugin Framework
+  **Question**: How frequently should plugins be checked for hot-reload (every 5s, 10s, 30s)?
+  **Options**:
+  | Option | Frequency | Implications |
+  |--------|-----------|--------------|
+  | A | 5 seconds | Fast detection but higher CPU usage |
+  | B | 10 seconds | Balanced approach |
+  | C | 30 seconds | Lower CPU usage but slower detection |
+  | Auto | Let AI infer based on performance targets | AI will analyze FR-xxx (500ms update latency) to determine appropriate frequency |
+  **Answer**: (waiting for user input or auto-inference)
+
+---
+
+### [Can Infer] Items
+
+*Status: AI will auto-resolve these using context, industry standards, or logical inference*
+
+- **[Can Infer] - Q003** - [Example: Error logging format]
+  **Status**: [ ] → will become [inferred]
+  **Related Section**: FR-XXX, Error Handling
+  **Question**: What format should error logs use?
+  **Auto-Inference**: JSON with structured fields (timestamp, level, message, context), following industry-standard logging practices.
+  **Resolution**: (when inferred)
+  - New FR: System MUST log errors in JSON format with timestamp, level, message, and context fields
+  - Details: AI will add this FR to Error Handling section
+
+---
+
+## Quality Gates
+
+### Plan Stage Requirements
+
+**CRITICAL**: Plan stage CANNOT proceed if ANY [Must Clarify] item has status `[ ]` (Unanswered).
+
+**WARNING**: Plan stage can proceed if [Suggested Clarify] or [Can Infer] items are unresolved, but user will be prompted to resolve them.
+
+### Resolution Workflow
+
+1. **User answers manually**:
+   - User runs `/specpro-clarify` (interactive mode)
+   - AI presents questions one by one
+   - User provides answers
+   - AI integrates answers into spec.md
+   - Marks items as [x]
+
+2. **User requests auto-inference**:
+   - After completing all [Must Clarify] items
+   - AI prompts: "All [Must Clarify] items resolved. Process [Suggested Clarify] and [Can Infer] items?"
+   - User chooses: "Auto-infer" → AI processes all remaining items
+   - AI infers answers and integrates into spec.md
+   - Marks items as [inferred]
+
+3. **AI auto-inference** (Plan stage optional):
+   - Plan stage can optionally run auto-inference for [Suggested Clarify] and [Can Infer] items
+   - User can review and reject auto-inferred results
+
+---
+
+## Progress Tracking
+
+**Total Items**: N
+- [Must Clarify]: M (X unresolved, M-X resolved)
+- Suggested-clarify items: S (Y unresolved, S-Y resolved)
+- [Can Infer]: C (Z unresolved, C-Z resolved)
+
+**Completion Criteria**:
+- All [Must Clarify] items MUST be resolved (status [x] or [inferred])
+- Plan stage CANNOT proceed if M-X > 0
+
+**Last Updated**: [TIMESTAMP]

specpro_cli/assets/templates/constitution-template.md

@@ -0,0 +1,50 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

specpro_cli/assets/templates/feature-spec-template.md

@@ -0,0 +1,66 @@
+# Module Specification: [MODULE NAME]
+
+**Feature id**: fNNN-简称
+**Registry row**: `specs/features.md`(创建时由 `/specpro-feature` 写入一行元信息——母规格零写入)
+**Created**: [YYYY-MM-DD]
+
+---
+
+## Feature Inheritance *(mandatory — 填写前先读)*
+
+*Purpose · Consumers*: 声明本 feature**从母规格继承**什么。`/specpro-plan`（feature 目录内运行时）读它定位母产物;继承冲突的裁定依据也在这里。
+
+feature 是**与母规格并列的第二级规格**（FR-009）——「并列」指需求住址独立,**不指**与母项目脱钩；且 feature 与母规格的 US/FR **零关联**（它是新增的独立功能,不继承、不增补、不修改母需求——FR-014 v0.23）。以下三项以**活引用**继承——每次 feature 作用域内命令执行时读取**当前版**,MUST NOT 复制成快照（快照即第二来源,必然漂移）：
+
+| 继承项 | 来源（真源,不在本 feature） | 对本 feature 的语义 |
+|--------|------------------------|----------------|
+| **项目宪章** | `specs/constitution.md` | 全部原则与 MUST 条款**同等生效**;本 feature 的宪法约束写在下节,只写**feature 特有**的 |
+| **技术栈基线** | 母 `specs/plan.md` → Technical Context | 默认栈;引入母栈**未覆盖**的选型 MUST 声明为「增量非替代」（FR-014） |
+| **共享基础设施** | 母 `plan.md` 的共享层/目录布局 | feature **消费**,不复制、不改写、不重新声明边界 |
+
+**冲突规则**（FR-014）：本 feature 的设计与基线约束冲突 ⇒ **报错阻止推进**,不是覆盖、不是例外。**母 plan 更新 ⇒ 本 feature 的 Lifecycle 标 `update`**（同构传播,不跟踪母 spec）。feature 作用域内发现的母侧缺口 ⇒ **登记台账路由**（`[specify]`/`[plan]`）,MUST NOT 在 feature 内直接修改母产物。feature 间依赖**声明可、实现耦合不可**。
+
+**本 feature 引入的新技术选型**（无则删去本行）：
+- [选型]: 增量非替代——母栈未覆盖 [能力],本选型补充之;不替代母栈的任何既有选型
+
+---
+
+## Change Summary *(auto-generated on update)*
+
+| 版本 | 日期 | 变更 |
+|------|------|------|
+| 0.1 | [YYYY-MM-DD] | 初始 feature 规格 |
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### US1 - [feature 内首个用户故事] (Priority: P1)
+
+**Why this priority**: [一句话]
+
+**Independent Test**: [feature 内可独立验收的判据——feature 自己的验收,不依赖其他 feature 的产物]
+
+**Acceptance Scenarios**:
+
+1. **Given** [初始状态] **When** [动作] **Then** [可观察结果]
+
+---
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+> feature 的 FR 编号是**feature 内独立命名空间**（从 FR-001 起）——feature 与母规格并列（FR-009）,跨 feature 引用写「`fNNN-简称` 的 FR-x」,不与母规格的 FR 编号混用。
+
+  - **FR-001**: [feature 功能需求]
+    **Lifecycle**: [specify:create][plan: ][tasks: ]
+    System MUST [需求正文]
+
+---
+
+## Constitution Constraints *(if applicable)*
+
+feature **特有**的宪法约束写这里（全部继承项见顶部 `## Feature Inheritance`,不在此重复）。
+
+- [feature 特有的约束或「无」]