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

specify_cli/templates/command-templates/clarify.md

@@ -0,0 +1,224 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+scripts:
+   sh: spec-kitty agent check-prerequisites --json --paths-only
+   ps: spec-kitty agent -Json -PathsOnly
+---
+**Path reference rule:** When you mention directories or files, provide either the absolute path or a path relative to the project root (for example, `kitty-specs/<feature>/tasks/`). Never refer to a folder by name alone.
+
+
+*Path: [templates/commands/clarify.md](templates/commands/clarify.md)*
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+---
+
+## Location Pre-flight Check
+
+**BEFORE PROCEEDING:** Verify you are working in the feature worktree.
+
+```bash
+pwd
+git branch --show-current
+```
+
+**Expected output:**
+- `pwd`: Should end with `.worktrees/001-feature-name` (or similar feature worktree)
+- Branch: Should show your feature branch name like `001-feature-name` (NOT `main`)
+
+**If you see the main branch or main repository path:**
+
+⛔ **STOP - You are in the wrong location!**
+
+This command updates your feature's spec.md file. You must be in the feature worktree to ensure changes go to the correct location.
+
+**Correct the issue:**
+1. Navigate to your feature worktree: `cd .worktrees/001-feature-name`
+2. Verify you're on the correct feature branch: `git branch --show-current`
+3. Then run this clarify command again
+
+---
+
+## What You Have Available
+
+After running `{SCRIPT}`, you will have paths to:
+- **FEATURE_DIR**: Absolute path to your feature directory (kitty-specs/001-feature-name/)
+- **FEATURE_SPEC**: Absolute path to spec.md (the file you'll be clarifying)
+
+You may also have:
+- **plan.md**: If planning has started (optional)
+- **tasks.md**: If task breakdown exists (optional)
+
+---
+
+## Workflow Context
+
+**Before this**: `/spec-kitty.specify` created spec.md (your starting requirements)
+
+**This command**:
+- Identifies ambiguities and gaps in your spec
+- Asks clarification questions (max 5)
+- Updates spec.md with clarifications directly
+- Reduces downstream rework risk
+
+**After this**:
+- Review clarified spec
+- Run `/spec-kitty.plan` to create implementation plan
+- Or run `/spec-kitty.clarify` again if more questions arise post-planning
+
+This command is optional but recommended before planning to reduce rework.
+
+---
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/spec-kitty.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `{SCRIPT}` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/spec-kitty.specify` or verify feature branch environment.
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 10 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+   - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+   - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+   - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - Scale thoroughness to the feature’s complexity: a lightweight enhancement may only need one or two confirmations, while multi-system efforts warrant the full question budget if gaps remain critical.
+   - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple-choice questions, list options inline using letter prefixes rather than tables, e.g.  
+      `Options: (A) describe option A · (B) describe option B · (C) describe option C · (D) short custom answer (<=5 words)`  
+      Ask the user to reply with the letter (or short custom text when offered).
+    - For short-answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
+    - After the user answers:
+       * Validate the answer maps to one option or fits the <=5 word constraint.
+       * If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       * Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       * All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       * User signals completion ("done", "good", "no more"), OR
+       * You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       * Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       * Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       * Functional ambiguity → Update or add a bullet in Functional Requirements.
+       * User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       * Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       * Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       * Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       * Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary listing each taxonomy category with a status label (Resolved / Deferred / Clear / Outstanding). Present as plain text or bullet list, not a table.
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/spec-kitty.plan` or run `/spec-kitty.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/spec-kitty.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+ - If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+ - If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: {ARGS}

specify_cli/templates/command-templates/constitution.md

@@ -0,0 +1,432 @@
+---
+description: Create or update the project constitution through interactive phase-based discovery.
+---
+**Path reference rule:** When you mention directories or files, provide either the absolute path or a path relative to the project root (for example, `kitty-specs/<feature>/tasks/`). Never refer to a folder by name alone.
+
+*Path: [templates/commands/constitution.md](templates/commands/constitution.md)*
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+---
+
+## What This Command Does
+
+This command creates or updates the **project constitution** through an interactive, phase-based discovery workflow.
+
+**Location**: `.kittify/memory/constitution.md` (project root, not worktrees)
+**Scope**: Project-wide principles that apply to ALL features
+
+**Important**: The constitution is OPTIONAL. All spec-kitty commands work without it.
+
+**Constitution Purpose**:
+- Capture technical standards (languages, testing, deployment)
+- Document code quality expectations (review process, quality gates)
+- Record tribal knowledge (team conventions, lessons learned)
+- Define governance (how the constitution changes, who enforces it)
+
+---
+
+## Discovery Workflow
+
+This command uses a **4-phase discovery process**:
+
+1. **Phase 1: Technical Standards** (Recommended)
+   - Languages, frameworks, testing requirements
+   - Performance targets, deployment constraints
+   - ~3-4 questions, creates a lean foundation
+
+2. **Phase 2: Code Quality** (Optional)
+   - PR requirements, review checklist, quality gates
+   - Documentation standards
+   - ~3-4 questions
+
+3. **Phase 3: Tribal Knowledge** (Optional)
+   - Team conventions, lessons learned
+   - Historical decisions (optional)
+   - ~2-4 questions
+
+4. **Phase 4: Governance** (Optional)
+   - Amendment process, compliance validation
+   - Exception handling (optional)
+   - ~2-3 questions
+
+**Paths**:
+- **Minimal** (~1 page): Phase 1 only → ~3-5 questions
+- **Comprehensive** (~2-3 pages): All phases → ~8-12 questions
+
+---
+
+## Execution Outline
+
+### Step 1: Initial Choice
+
+Ask the user:
+```
+Do you want to establish a project constitution?
+
+A) No, skip it - I don't need a formal constitution
+B) Yes, minimal - Core technical standards only (~1 page, 3-5 questions)
+C) Yes, comprehensive - Full governance and tribal knowledge (~2-3 pages, 8-12 questions)
+```
+
+Handle responses:
+- **A (Skip)**: Create a minimal placeholder at `.kittify/memory/constitution.md`:
+  - Title + short note: "Constitution skipped - not required for spec-kitty usage. Run /spec-kitty.constitution anytime to create one."
+  - Exit successfully.
+- **B (Minimal)**: Continue with Phase 1 only.
+- **C (Comprehensive)**: Continue through all phases, asking whether to skip each optional phase.
+
+### Step 2: Phase 1 - Technical Standards
+
+Context:
+```
+Phase 1: Technical Standards
+These are the non-negotiable technical requirements that all features must follow.
+This phase is recommended for all projects.
+```
+
+Ask one question at a time:
+
+**Q1: Languages and Frameworks**
+```
+What languages and frameworks are required for this project?
+Examples:
+- "Python 3.11+ with FastAPI for backend"
+- "TypeScript 4.9+ with React 18 for frontend"
+- "Rust 1.70+ with no external dependencies"
+```
+
+**Q2: Testing Requirements**
+```
+What testing framework and coverage requirements?
+Examples:
+- "pytest with 80% line coverage, 100% for critical paths"
+- "Jest with 90% coverage, unit + integration tests required"
+- "cargo test, no specific coverage target but all features must have tests"
+```
+
+**Q3: Performance and Scale Targets**
+```
+What are the performance and scale expectations?
+Examples:
+- "Handle 1000 requests/second at p95 < 200ms"
+- "Support 10k concurrent users, 1M daily active users"
+- "CLI operations complete in < 2 seconds"
+- "N/A - performance not a primary concern"
+```
+
+**Q4: Deployment and Constraints**
+```
+What are the deployment constraints or platform requirements?
+Examples:
+- "Docker-only, deployed to Kubernetes"
+- "Must run on Ubuntu 20.04 LTS without external dependencies"
+- "Cross-platform: Linux, macOS, Windows 10+"
+- "N/A - no specific deployment constraints"
+```
+
+### Step 3: Phase 2 - Code Quality (Optional)
+
+Ask only if comprehensive path is selected:
+```
+Phase 2: Code Quality
+Skip this if your team uses standard practices without special requirements.
+
+Do you want to define code quality standards?
+A) Yes, ask questions
+B) No, skip this phase (use standard practices)
+```
+
+If yes, ask one at a time:
+
+**Q5: PR Requirements**
+```
+What are the requirements for pull requests?
+Examples:
+- "2 approvals required, 1 must be from core team"
+- "1 approval required, PR must pass CI checks"
+- "Self-merge allowed after CI passes for maintainers"
+```
+
+**Q6: Code Review Checklist**
+```
+What should reviewers check during code review?
+Examples:
+- "Tests added, docstrings updated, follows PEP 8, no security issues"
+- "Type annotations present, error handling robust, performance considered"
+- "Standard review - correctness, clarity, maintainability"
+```
+
+**Q7: Quality Gates**
+```
+What quality gates must pass before merging?
+Examples:
+- "All tests pass, coverage ≥80%, linter clean, security scan clean"
+- "Tests pass, type checking passes, manual QA approved"
+- "CI green, no merge conflicts, PR approved"
+```
+
+**Q8: Documentation Standards**
+```
+What documentation is required?
+Examples:
+- "All public APIs must have docstrings + examples"
+- "README updated for new features, ADRs for architectural decisions"
+- "Inline comments for complex logic, keep docs up to date"
+- "Minimal - code should be self-documenting"
+```
+
+### Step 4: Phase 3 - Tribal Knowledge (Optional)
+
+Ask only if comprehensive path is selected:
+```
+Phase 3: Tribal Knowledge
+Skip this for new projects or if team conventions are minimal.
+
+Do you want to capture tribal knowledge?
+A) Yes, ask questions
+B) No, skip this phase
+```
+
+If yes, ask:
+
+**Q9: Team Conventions**
+```
+What team conventions or coding styles should everyone follow?
+Examples:
+- "Use Result<T, E> for fallible operations, never unwrap() in prod"
+- "Prefer composition over inheritance, keep classes small (<200 lines)"
+- "Use feature flags for gradual rollouts, never merge half-finished features"
+```
+
+**Q10: Lessons Learned**
+```
+What past mistakes or lessons learned should guide future work?
+Examples:
+- "Always version APIs from day 1"
+- "Write integration tests first"
+- "Keep dependencies minimal - every dependency is a liability"
+- "N/A - no major lessons yet"
+```
+
+Optional follow-up:
+```
+Do you want to document historical architectural decisions?
+A) Yes
+B) No
+```
+
+**Q11: Historical Decisions** (only if yes)
+```
+Any historical architectural decisions that should guide future work?
+Examples:
+- "Chose microservices for independent scaling"
+- "Chose monorepo for atomic changes across services"
+- "Chose SQLite for simplicity over PostgreSQL"
+```
+
+### Step 5: Phase 4 - Governance (Optional)
+
+Ask only if comprehensive path is selected:
+```
+Phase 4: Governance
+Skip this to use simple defaults.
+
+Do you want to define governance process?
+A) Yes, ask questions
+B) No, skip this phase (use simple defaults)
+```
+
+If skipped, use defaults:
+- Amendment: Any team member can propose changes via PR
+- Compliance: Team validates during code review
+- Exceptions: Discuss with team, document in PR
+
+If yes, ask:
+
+**Q12: Amendment Process**
+```
+How should the constitution be amended?
+Examples:
+- "PR with 2 approvals, announce in team chat, 1 week discussion"
+- "Any maintainer can update via PR"
+- "Quarterly review, team votes on changes"
+```
+
+**Q13: Compliance Validation**
+```
+Who validates that features comply with the constitution?
+Examples:
+- "Code reviewers check compliance, block merge if violated"
+- "Team lead reviews architecture"
+- "Self-managed - developers responsible"
+```
+
+Optional follow-up:
+```
+Do you want to define exception handling?
+A) Yes
+B) No
+```
+
+**Q14: Exception Handling** (only if yes)
+```
+How should exceptions to the constitution be handled?
+Examples:
+- "Document in ADR, require 3 approvals, set sunset date"
+- "Case-by-case discussion, strong justification required"
+- "Exceptions discouraged - update constitution instead"
+```
+
+### Step 6: Summary and Confirmation
+
+Present a summary and ask for confirmation:
+```
+Constitution Summary
+====================
+
+You've completed [X] phases and answered [Y] questions.
+Here's what will be written to .kittify/memory/constitution.md:
+
+Technical Standards:
+- Languages: [Q1]
+- Testing: [Q2]
+- Performance: [Q3]
+- Deployment: [Q4]
+
+[If Phase 2 completed]
+Code Quality:
+- PR Requirements: [Q5]
+- Review Checklist: [Q6]
+- Quality Gates: [Q7]
+- Documentation: [Q8]
+
+[If Phase 3 completed]
+Tribal Knowledge:
+- Conventions: [Q9]
+- Lessons Learned: [Q10]
+- Historical Decisions: [Q11 if present]
+
+Governance: [Custom if Phase 4 completed, otherwise defaults]
+
+Estimated length: ~[50-80 lines minimal] or ~[150-200 lines comprehensive]
+
+Proceed with writing constitution?
+A) Yes, write it
+B) No, let me start over
+C) Cancel, don't create constitution
+```
+
+Handle responses:
+- **A**: Write the constitution file.
+- **B**: Restart from Step 1.
+- **C**: Exit without writing.
+
+### Step 7: Write Constitution File
+
+Generate the constitution as Markdown:
+
+```markdown
+# [PROJECT_NAME] Constitution
+
+> Auto-generated by spec-kitty constitution command
+> Created: [YYYY-MM-DD]
+> Version: 1.0.0
+
+## Purpose
+
+This constitution captures the technical standards, code quality expectations,
+tribal knowledge, and governance rules for [PROJECT_NAME]. All features and
+pull requests should align with these principles.
+
+## Technical Standards
+
+### Languages and Frameworks
+[Q1]
+
+### Testing Requirements
+[Q2]
+
+### Performance and Scale
+[Q3]
+
+### Deployment and Constraints
+[Q4]
+
+[If Phase 2 completed]
+## Code Quality
+
+### Pull Request Requirements
+[Q5]
+
+### Code Review Checklist
+[Q6]
+
+### Quality Gates
+[Q7]
+
+### Documentation Standards
+[Q8]
+
+[If Phase 3 completed]
+## Tribal Knowledge
+
+### Team Conventions
+[Q9]
+
+### Lessons Learned
+[Q10]
+
+[If Q11 present]
+### Historical Decisions
+[Q11]
+
+## Governance
+
+[If Phase 4 completed]
+### Amendment Process
+[Q12]
+
+### Compliance Validation
+[Q13]
+
+[If Q14 present]
+### Exception Handling
+[Q14]
+
+[If Phase 4 skipped, use defaults]
+### Amendment Process
+Any team member can propose amendments via pull request. Changes are discussed
+and merged following standard PR review process.
+
+### Compliance Validation
+Code reviewers validate compliance during PR review. Constitution violations
+should be flagged and addressed before merge.
+
+### Exception Handling
+Exceptions discussed case-by-case with team. Strong justification required.
+Consider updating constitution if exceptions become common.
+```
+
+### Step 8: Success Message
+
+After writing, provide:
+- Location of the file
+- Phases completed and questions answered
+- Next steps (review, share with team, run /spec-kitty.plan)
+
+---
+
+## Required Behaviors
+
+- Ask one question at a time.
+- Offer skip options and explain when to skip.
+- Keep responses concise and user-focused.
+- Ensure the constitution stays lean (1-3 pages, not 10 pages).
+- If user chooses to skip entirely, still create the minimal placeholder file and exit successfully.