spec-kitty-cli 0.5.0__tar.gz

spec_kitty_cli-0.5.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+.uv-tools/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Project specific
+*.log
+.env
+.env.local
+.codex/
+*.lock
+.worktrees/
+
+# Spec Kit-specific files
+.genreleases/
+*.zip
+sdd-*/
+
+# Added by Spec Kitty CLI (auto-managed)
+.claude/
+.opencode/
+.windsurf/
+.gemini/
+.cursor/
+.qwen/
+.kilocode/
+.augment/
+.github/
+.roo/
+.amazonq/

spec_kitty_cli-0.5.0/.kittify/AGENTS.md

@@ -0,0 +1,105 @@
+# Agent Rules for Spec Kitty Projects
+
+**⚠️ CRITICAL**: All AI agents working in this project must follow these rules.
+
+These rules apply to **all commands** (specify, plan, research, tasks, implement, review, merge, etc.).
+
+---
+
+## 1. Path Reference Rule
+
+**When you mention directories or files, provide either the absolute path or a path relative to the project root.**
+
+✅ **CORRECT**:
+- `kitty-specs/001-feature/tasks/planned/WP01.md`
+- `/Users/robert/Code/myproject/kitty-specs/001-feature/spec.md`
+- `tasks/planned/WP01.md` (relative to feature directory)
+
+❌ **WRONG**:
+- "the tasks folder" (which one? where?)
+- "WP01.md" (in which lane? which feature?)
+- "the spec" (which feature's spec?)
+
+**Why**: Clarity and precision prevent errors. Never refer to a folder by name alone.
+
+---
+
+## 2. UTF-8 Encoding Rule
+
+**When writing ANY markdown, JSON, YAML, CSV, or code files, use ONLY UTF-8 compatible characters.**
+
+### What to Avoid (Will Break the Dashboard)
+
+❌ **Windows-1252 smart quotes**: “ ” ‘ ’ (from Word/Outlook/Office)  
+❌ **Em/en dashes and special punctuation**: — –  
+❌ **Copy-pasted arrows**: → (becomes illegal bytes)  
+❌ **Multiplication sign**: × (0xD7 in Windows-1252)  
+❌ **Copy/paste from Microsoft Office** without cleaning  
+
+### What to Use Instead
+
+✅ Standard ASCII quotes: `"`, `'`  
+✅ Hyphen-minus: `-` instead of en/em dash  
+✅ ASCII arrow: `->` instead of →  
+✅ Lowercase `x` for multiplication  
+✅ Plain punctuation  
+
+### Safe Characters
+
+✅ Emoji (proper UTF-8)  
+✅ Accented characters typed directly: café, naïve, Zürich  
+✅ Unicode math typed directly (√ ≈ ≠ ≤ ≥)  
+
+### Copy/Paste Guidance
+
+1. Paste into a plain-text buffer first (VS Code, TextEdit in plain mode)  
+2. Replace smart quotes and dashes  
+3. Verify no � replacement characters appear  
+4. Run `python scripts/validate_encoding.py <path>` when in doubt
+
+**Failure to follow this rule causes the dashboard to render blank pages.**
+
+---
+
+## 3. Context Management Rule
+
+**Build the context you need, then maintain it intelligently.**
+
+- Session start (0 tokens): You have zero context. Read plan.md, tasks.md, relevant artifacts.  
+- Mid-session (you already read them): Use your judgment—don’t re-read everything unless necessary.  
+- Never skip relevant information; do skip redundant re-reads to save tokens.  
+- Rely on the steps in the command you are executing.
+
+---
+
+## 4. Work Quality Rule
+
+**Produce secure, tested, documented work.**
+
+- Follow the plan and constitution requirements.  
+- Prefer existing patterns over invention.  
+- Treat security warnings as fatal—fix or escalate.  
+- Run all required tests before claiming work is complete.  
+- Be transparent: state what you did, what you didn’t, and why.
+
+---
+
+## 5. Git Discipline Rule
+
+**Keep commits clean and auditable.**
+
+- Commit only meaningful units of work.  
+- Write descriptive commit messages (imperative mood).  
+- Do not rewrite history of shared branches.  
+- Keep feature branches up to date with main via merge or rebase as appropriate.  
+- Never commit secrets, tokens, or credentials.
+
+---
+
+### Quick Reference
+
+- 📁 **Paths**: Always specify exact locations.  
+- 🔤 **Encoding**: UTF-8 only. Run the validator when unsure.  
+- 🧠 **Context**: Read what you need; don’t forget what you already learned.  
+- ✅ **Quality**: Follow secure, tested, documented practices.  
+- 📝 **Git**: Commit cleanly with clear messages.

spec_kitty_cli-0.5.0/.kittify/active-mission/commands/accept.md

@@ -0,0 +1,61 @@
+---
+description: Validate feature readiness and guide final acceptance steps.
+scripts:
+  sh: .kittify/scripts/bash/accept-feature.sh --json {ARGS}
+  ps: .kittify/scripts/powershell/accept-feature.ps1 --json {ARGS}
+---
+
+## 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.

spec_kitty_cli-0.5.0/.kittify/active-mission/commands/analyze.md

@@ -0,0 +1,186 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+scripts:
+  sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks
+  ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks
+---
+
+## 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}