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

specify_cli/missions/research/templates/task-prompt-template.md

@@ -0,0 +1,148 @@
+---
+work_package_id: "WPxx"
+subtasks:
+  - "Txxx"
+title: "Replace with work package title"
+phase: "Phase N - Replace with phase name"
+lane: "planned"  # DO NOT EDIT - 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"
+---
+
+# Research Work Package: {{work_package_id}} – {{title}}
+
+## Review Feedback Status
+
+**Read this first if you are working on this research 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 research 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 research needs revision. Each item must be addressed 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.]*
+
+---
+
+## Markdown Formatting
+Wrap HTML/XML tags in backticks: `` `<div>` ``, `` `<script>` ``
+Use language identifiers in code blocks: ````python`, ````bash`
+
+---
+
+## Research Objectives & Success Criteria
+
+- Summarize the exact outcomes that mark this research work package complete.
+- Call out key acceptance criteria or quality metrics (e.g., minimum sources, confidence thresholds).
+
+## Context & Methodology
+
+- Reference prerequisite work and related documents.
+- Link to supporting specs: `.kittify/memory/constitution.md`, `kitty-specs/.../plan.md` (methodology), `kitty-specs/.../spec.md` (research question), `research.md`, `data-model.md`.
+- Highlight methodological constraints or quality requirements.
+
+## Evidence Tracking Requirements
+
+- **Source Register**: All sources MUST be recorded in `research/source-register.csv`
+- **Evidence Log**: All findings MUST be recorded in `research/evidence-log.csv`
+- **Citations**: Every claim must link to evidence rows
+
+## Subtasks & Detailed Guidance
+
+### Subtask TXXX – Replace with summary
+- **Purpose**: Explain why this research subtask exists.
+- **Steps**: Detailed, actionable instructions for conducting research.
+- **Sources**: Types of sources to search (academic, industry, gray literature).
+- **Output**: What artifact to update (source-register.csv, evidence-log.csv, findings.md).
+- **Parallel?**: Note if this can run alongside others (e.g., different databases).
+- **Quality Criteria**: Minimum requirements for this subtask.
+
+### Subtask TYYY – Replace with summary
+- Repeat the structure above for every included `Txxx` entry.
+
+## Quality & Validation
+
+- Specify minimum source requirements.
+- Define confidence level thresholds.
+- Document methodology adherence checkpoints.
+
+## Risks & Mitigations
+
+- List known pitfalls (bias, incomplete coverage, contradictory findings).
+- Provide mitigation strategies.
+
+## Review Guidance
+
+- Key acceptance checkpoints for `/spec-kitty.review`.
+- Methodology adherence verification points.
+- Any context reviewers should consider.
+
+## 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 literature search
+- 2026-01-12T11:00:00Z – claude – lane=for_review – Research complete, ready for review
+- 2026-01-12T11:30:00Z – codex – lane=done – Review passed, findings validated  <- 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 (at the end)
+2. **Use CLI**: `spec-kitty agent tasks move-task <WPID> --to <lane> --note "message"` (recommended)
+
+The CLI command updates both frontmatter and activity log automatically.
+
+**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/missions/research/templates/tasks-template.md

@@ -0,0 +1,114 @@
+---
+description: "Work package task list template for research methodology execution"
+---
+
+# Work Packages: [RESEARCH QUESTION]
+
+**Inputs**: Research documents from `/kitty-specs/[###-research]/`  
+**Prerequisites**: plan.md (methodology), spec.md (research question), research.md (background), data-model.md, quickstart.md
+
+**Evidence Tracking**: All sources MUST be recorded in `research/source-register.csv` and findings in `research/evidence-log.csv`.
+
+**Organization**: Research work packages organized by methodology phase. Each work package must be independently deliverable and testable (e.g., literature search complete before analysis).
+
+## Subtask Format: `[Txxx] [P?] Description`
+- **[P]** indicates the subtask can proceed in parallel (different sources/analysts).
+- Always reference the file or artifact impacted (e.g., `research/evidence-log.csv`).
+- Use research terminology: phases, findings, synthesis, methodology.
+
+## Path Conventions
+- **Workspace**: `research/`
+- **Data**: `data/`
+- **Deliverables**: `findings/`
+- Adjust additional paths to match mission.yaml definitions.
+
+---
+
+## Work Package WP01: Literature Search & Source Collection (Priority: P1) 🎯 Foundation
+
+**Goal**: Identify and collect all relevant sources for the research question.  
+**Independent Test**: `research/source-register.csv` contains the minimum required high-quality sources with relevance ratings.  
+**Prompt**: `/tasks/WP01-literature-search.md`
+
+### Included Subtasks
+- [ ] T001 Define search keywords and inclusion/exclusion criteria
+- [ ] T002 [P] Search academic database 1 (IEEE, PubMed, arXiv, etc.)
+- [ ] T003 [P] Search academic database 2
+- [ ] T004 [P] Search gray literature and industry sources
+- [ ] T005 Screen collected sources for relevance
+- [ ] T006 Populate source-register.csv with all candidate sources
+- [ ] T007 Prioritize sources by relevance rating and status
+
+### Implementation Notes
+- Document search queries and filters.
+- Capture DOIs/URLs and access dates in the source register.
+
+---
+
+## Work Package WP02: Source Review & Evidence Extraction (Priority: P1)
+
+**Goal**: Review prioritized sources and extract key findings.  
+**Independent Test**: `research/evidence-log.csv` contains findings from all high-relevance sources with confidence levels.  
+**Prompt**: `/tasks/WP02-source-review.md`
+
+### Included Subtasks
+- [ ] T008 [P] Review high-relevance sources (parallelizable by researcher/source)
+- [ ] T009 Extract key findings into evidence-log.csv
+- [ ] T010 Assign confidence levels to findings
+- [ ] T011 Document limitations and caveats in notes column
+- [ ] T012 Identify patterns/themes emerging from evidence
+
+### Implementation Notes
+- Reference source IDs from source-register.csv within each evidence row.
+- Flag contradictory findings for deeper analysis.
+
+---
+
+## Work Package WP03: Analysis & Synthesis (Priority: P1)
+
+**Goal**: Synthesize findings and answer the research question.  
+**Independent Test**: findings.md contains synthesized conclusions backed by citations.  
+**Prompt**: `/tasks/WP03-analysis-synthesis.md`
+
+### Included Subtasks
+- [ ] T013 Code findings by theme/category
+- [ ] T014 Identify patterns across sources and confidence levels
+- [ ] T015 Assess strength of evidence supporting each claim
+- [ ] T016 Draw conclusions mapped to sub-questions
+- [ ] T017 Document limitations and threats to validity
+- [ ] T018 Write findings.md with synthesis and bibliography references
+
+### Implementation Notes
+- Link every conclusion to evidence rows.
+- Summarize methodology adherence and outstanding questions.
+
+---
+
+## Additional Work Packages (Add as needed)
+
+- **WP0X – Methodology Refinement**: Update plan.md, adjust phases, incorporate new data collection methods.
+- **WP0Y – Publication Prep**: Create findings/report deliverables, prepare presentation, finalize bibliography.
+- **WP0Z – Empirical Study Support**: For empirical work, capture experiment setup, data collection logs, statistical analysis.
+
+---
+
+## Dependency & Execution Summary
+
+- **Sequence**: WP01 (literature search) → WP02 (evidence extraction) → WP03 (analysis & synthesis) → WP0X (publication/polish).
+- **Parallelization**: Database searches, source reviews, and evidence extraction subtasks can run concurrently when using clear ownership per source.
+- **Quality Gates**: Do not advance phases until acceptance criteria for the current work package are satisfied.
+
+---
+
+## Subtask Index (Reference)
+
+| Subtask ID | Summary | Work Package | Priority | Parallel? |
+|------------|---------|--------------|----------|-----------|
+| T001       | Define search parameters | WP01 | P1 | No |
+| T002       | Search academic database 1 | WP01 | P1 | Yes |
+| T008       | Review high-relevance sources | WP02 | P1 | Yes |
+| T013       | Code findings by theme | WP03 | P1 | No |
+
+---
+
+> Replace placeholder text with research-specific content. Keep this structure so downstream automation can parse work packages and maintain rigorous research workflows.

specify_cli/missions/software-dev/command-templates/accept.md

@@ -0,0 +1,75 @@
+---
+description: Validate feature readiness and guide final acceptance steps.
+---
+
+# /spec-kitty.accept - Validate Feature Readiness
+
+**Version**: 0.11.0+
+**Purpose**: Validate all work packages are complete and feature is ready to merge.
+
+## 📍 WORKING DIRECTORY: Run from MAIN repository
+
+**IMPORTANT**: Accept runs from the main repository root, NOT from a WP worktree.
+
+```bash
+# If you're in a worktree, return to main first:
+cd $(git rev-parse --show-toplevel)
+
+# Then run accept:
+spec-kitty accept
+```
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Discovery (mandatory)
+
+Before running the acceptance workflow, gather the following:
+
+1. **Feature slug** (e.g., `005-awesome-thing`). If omitted, detect automatically.
+2. **Acceptance mode**:
+   - `pr` when the feature will merge via hosted pull request.
+   - `local` when the feature will merge locally without a PR.
+   - `checklist` to run the readiness checklist without committing or producing merge instructions.
+3. **Validation commands executed** (tests/builds). Collect each command verbatim; omit if none.
+4. **Acceptance actor** (optional, defaults to the current agent name).
+
+Ask one focused question per item and confirm the summary before continuing. End the discovery turn with `WAITING_FOR_ACCEPTANCE_INPUT` until all answers are provided.
+
+## Execution Plan
+
+1. Compile the acceptance options into an argument list:
+   - Always include `--actor "__AGENT__"`.
+   - Append `--feature "<slug>"` when the user supplied a slug.
+   - Append `--mode <mode>` (`pr`, `local`, or `checklist`).
+   - Append `--test "<command>"` for each validation command provided.
+2. Run `{SCRIPT}` (the CLI wrapper) with the assembled arguments **and** `--json`.
+3. Parse the JSON response. It contains:
+   - `summary.ok` (boolean) and other readiness details.
+   - `summary.outstanding` categories when issues remain.
+   - `instructions` (merge steps) and `cleanup_instructions`.
+   - `notes` (e.g., acceptance commit hash).
+4. Present the outcome:
+   - If `summary.ok` is `false`, list each outstanding category with bullet points and advise the user to resolve them before retrying acceptance.
+   - If `summary.ok` is `true`, display:
+     - Acceptance timestamp, actor, and (if present) acceptance commit hash.
+     - Merge instructions and cleanup instructions as ordered steps.
+     - Validation commands executed (if any).
+5. When the mode is `checklist`, make it clear no commits or merge instructions were produced.
+
+## Output Requirements
+
+- Summaries must be in plain text (no tables). Use short bullet lists for instructions.
+- Surface outstanding issues before any congratulations or success messages.
+- If the JSON payload includes warnings, surface them under an explicit **Warnings** section.
+- Never fabricate results; only report what the JSON contains.
+
+## Error Handling
+
+- If the command fails or returns invalid JSON, report the failure and request user guidance (do not retry automatically).
+- When outstanding issues exist, do **not** attempt to force acceptance—return the checklist and prompt the user to fix the blockers.

specify_cli/missions/software-dev/command-templates/analyze.md

@@ -0,0 +1,183 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `{SCRIPT}` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /spec-kitty.specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+{ARGS}