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

specify_cli/templates/AGENTS.md

@@ -0,0 +1,190 @@
+# 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/WP01.md`
+- `/Users/robert/Code/myproject/kitty-specs/001-feature/spec.md`
+- `tasks/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)
+❌ **Plus-minus sign**: ± (0xB1 in Windows-1252)
+❌ **Degree symbol**: ° (0xB0 in Windows-1252)
+❌ **Copy/paste from Microsoft Office** without cleaning
+
+**Real examples that crashed the dashboard:**
+- "User's favorite feature" → "User's favorite feature" (smart quote)
+- "Price: $100 ± $10" → "Price: $100 +/- $10"
+- "Temperature: 72°F" → "Temperature: 72 degrees F"
+- "3 × 4 matrix" → "3 x 4 matrix"
+
+### What to Use Instead
+
+✅ Standard ASCII quotes: `"`, `'`
+✅ Hyphen-minus: `-` instead of en/em dash
+✅ ASCII arrow: `->` instead of →
+✅ Lowercase `x` for multiplication
+✅ `+/-` for plus-minus
+✅ ` degrees` for temperature
+✅ 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 `spec-kitty validate-encoding --feature <feature-id>` to check
+5. Run `spec-kitty validate-encoding --feature <feature-id> --fix` to auto-repair
+
+**Failure to follow this rule causes the dashboard to render blank pages.**
+
+### Auto-Fix Available
+
+If you accidentally introduce problematic characters:
+```bash
+# Check for encoding issues
+spec-kitty validate-encoding --feature 001-my-feature
+
+# Automatically fix all issues (creates .bak backups)
+spec-kitty validate-encoding --feature 001-my-feature --fix
+
+# Check all features at once
+spec-kitty validate-encoding --all --fix
+```
+
+---
+
+## 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.
+
+---
+
+## 6. Git Best Practices for Agent Directories
+
+**NEVER commit agent directories to git.**
+
+### Why Agent Directories Must Not Be Committed
+
+Agent directories like `.claude/`, `.codex/`, `.gemini/` contain:
+- Authentication tokens and API keys
+- User-specific credentials (auth.json)
+- Session data and conversation history
+- Temporary files and caches
+
+### What Should Be Committed
+
+✅ **DO commit:**
+- `.kittify/templates/` - Command templates (source)
+- `.kittify/missions/` - Mission definitions
+- `.kittify/memory/constitution.md` - Project constitution
+- `.gitignore` - With all agent directories excluded
+
+❌ **DO NOT commit:**
+- `.claude/`, `.codex/`, `.gemini/`, etc. - Agent runtime directories
+- `.kittify/templates/command-templates/` - These are templates, not final commands
+- Any `auth.json`, `credentials.json`, or similar files
+
+### Automatic Protection
+
+Spec Kitty automatically:
+1. Adds all agent directories to `.gitignore` during `spec-kitty init`
+2. Installs pre-commit hook to block accidental commits
+3. Creates `.claudeignore` to optimize AI scanning
+
+### Manual Verification
+
+```bash
+# Verify .gitignore protection
+cat .gitignore | grep -E '\.(claude|codex|gemini|cursor)/'
+
+# Check for accidentally staged agent files
+git status | grep -E '\.(claude|codex|gemini|cursor)/'
+
+# If you find staged agent files, unstage them:
+git reset HEAD .claude/
+```
+
+### Worktree Constitution Sharing
+
+In worktrees, `.kittify/memory/` is a symlink to the main repo's memory,
+ensuring all feature branches share the same constitution.
+
+```bash
+# In a worktree, this should show a symlink:
+ls -la .kittify/memory
+# lrwxr-xr-x ... .kittify/memory -> ../../../.kittify/memory
+```
+
+This is intentional and correct - it ensures a single source of truth for project principles.
+
+---
+
+### 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.

specify_cli/templates/POWERSHELL_SYNTAX.md

@@ -0,0 +1,229 @@
+# PowerShell Syntax Guide for AI Agents
+
+**⚠️ READ THIS if you are working in a PowerShell environment**
+
+This guide helps AI agents use correct PowerShell syntax when working with spec-kitty workflows.
+
+---
+
+## Quick Reference: Bash vs PowerShell
+
+| Task | ❌ Bash (WRONG) | ✅ PowerShell (CORRECT) |
+|------|-----------------|-------------------------|
+| **Command chaining** | `cmd1 && cmd2` | `cmd1; cmd2` |
+| **Parameter flags** | `--json --paths-only` | `-Json -PathsOnly` |
+| **Script path** | `./scripts/bash/script.sh` | `..\scripts\powershell\Script.ps1` |
+| **Environment variable** | `$VAR_NAME` | `$env:VAR_NAME` |
+| **Current directory** | `pwd` | `Get-Location` (or `pwd` alias) |
+| **List files** | `ls -la` | `Get-ChildItem` (or `ls` alias) |
+| **File exists check** | `[ -f file.txt ]` | `Test-Path file.txt` |
+| **Directory separator** | `/path/to/file` | `\path\to\file` |
+| **Home directory** | `~/projects` | `$HOME\projects` |
+
+---
+
+## Location Verification (PowerShell)
+
+**Check your current location:**
+```powershell
+Get-Location
+git branch --show-current
+```
+
+**Expected for feature worktrees:**
+- Location: `C:\Users\...\project\.worktrees\001-feature-name`
+- Branch: `001-feature-name` (NOT `main`)
+
+---
+
+## Running Spec-Kitty Commands (PowerShell)
+
+### Using the spec-kitty CLI
+
+Spec-kitty uses a Python CLI that works across all platforms:
+
+**Common commands:**
+- `spec-kitty agent feature create-feature <slug>` - Create a new feature
+- `spec-kitty verify-setup` - Check environment and paths
+- `spec-kitty agent workflow implement <WPID> --agent <name>` - Start implementing a work package
+- `spec-kitty agent workflow review <WPID> --agent <name>` - Start reviewing a work package
+- `spec-kitty agent tasks move-task <WPID> --to for_review` - Complete implementation (move to review)
+- `spec-kitty merge` - Merge completed feature
+
+### Parameter Naming Convention
+
+PowerShell uses **PascalCase** with leading dash:
+- `-Json` (not `--json`)
+- `-FeatureName` (not `--feature-name`)
+- `-IncludeTasks` (not `--include-tasks`)
+- `-RequireTasks` (not `--require-tasks`)
+
+### Examples
+
+**Create feature:**
+```powershell
+.\.kittify\scripts\powershell\Create-NewFeature.ps1 `
+  -FeatureName "User Authentication" `
+  -FeatureDescription "Add login and registration"
+```
+
+**Check prerequisites:**
+```powershell
+.\.kittify\scripts\powershell\check-prerequisites.ps1 -Json -IncludeTasks
+```
+
+**Move task to review (after implementation):**
+```powershell
+# Using the CLI (recommended):
+spec-kitty agent tasks move-task WP01 --to for_review --note "Ready for review"
+
+# Or using PowerShell script:
+.\.kittify\scripts\powershell\Move-TaskToLane.ps1 `
+  -Feature "001-auth" `
+  -TaskId "WP01" `
+  -Lane "for_review" `
+  -ShellPid $PID `
+  -Agent "claude"
+```
+
+---
+
+## Common Mistakes to Avoid
+
+### ❌ Don't Use Bash Operators
+
+```powershell
+# WRONG:
+cd worktrees && pwd
+
+# CORRECT:
+cd worktrees; Get-Location
+```
+
+### ❌ Don't Use Bash-Style Parameters
+
+```powershell
+# WRONG:
+.\check-prerequisites.ps1 --json --require-tasks
+
+# CORRECT:
+.\check-prerequisites.ps1 -Json -RequireTasks
+```
+
+### Path Separators in PowerShell
+
+PowerShell on Windows uses backslashes for native paths:
+
+```powershell
+# WRONG (Unix-style paths on Windows):
+cd ./.kittify/memory
+
+# CORRECT (Windows-style paths):
+cd .\.kittify\memory
+```
+
+Note: Git commands work with forward slashes, but native PowerShell file operations expect backslashes. The spec-kitty CLI handles this automatically.
+
+---
+
+## Environment Variables
+
+**Setting variables:**
+```powershell
+$env:SPEC_KITTY_TEMPLATE_ROOT = "C:\path\to\spec-kitty"
+```
+
+**Reading variables:**
+```powershell
+echo $env:SPEC_KITTY_TEMPLATE_ROOT
+```
+
+**Checking if set:**
+```powershell
+if ($env:SPEC_KITTY_TEMPLATE_ROOT) {
+    Write-Host "Variable is set"
+}
+```
+
+---
+
+## File Operations
+
+**Check if file exists:**
+```powershell
+if (Test-Path "spec.md") {
+    Write-Host "Spec exists"
+}
+```
+
+**Read file:**
+```powershell
+$content = Get-Content "spec.md" -Raw
+```
+
+**Create directory:**
+```powershell
+New-Item -ItemType Directory -Path "tasks\planned" -Force
+```
+
+---
+
+## Workflow Tips
+
+1. **Always use full parameter names** in scripts (not abbreviations)
+2. **Use semicolons** to chain commands, not `&&` or `||`
+3. **Backslashes** for local paths, forward slashes OK for git operations
+4. **$PID** contains current PowerShell process ID (use for --shell-pid)
+5. **Tab completion** works for parameter names in PowerShell
+
+---
+
+## When to Use What
+
+**Use PowerShell scripts when:**
+- User specified `--script ps` during init
+- You're in a Windows PowerShell terminal
+- Templates reference `.ps1` files in frontmatter
+
+**Use Bash scripts when:**
+- User specified `--script sh` during init
+- You're in bash/zsh/fish terminal
+- Templates reference `.sh` files in frontmatter
+
+**Using spec-kitty commands:**
+All spec-kitty commands work the same way on PowerShell and Bash:
+```powershell
+spec-kitty agent workflow implement WP01 --agent claude  # Auto-moves to doing
+spec-kitty agent tasks move-task WP01 --to for_review    # Completion step
+spec-kitty verify-setup
+spec-kitty dashboard
+```
+
+The CLI is cross-platform and handles path differences automatically.
+
+---
+
+## Debugging PowerShell Issues
+
+**Common errors and solutions:**
+
+1. **"Parameter cannot be found that matches parameter name"**
+   - You used bash-style parameters (`--json`)
+   - Fix: Use PowerShell style (`-Json`)
+
+2. **"The term '&&' is not recognized"**
+   - You used bash command chaining
+   - Fix: Use semicolon (`;`) instead
+
+3. **"Cannot find path"**
+   - You used forward slashes in PowerShell path
+   - Fix: Use backslashes (`\`) for local paths
+
+4. **"Unable to import mission module"**
+   - Python can't find specify_cli package
+   - Check: `pip show spec-kitty-cli`
+   - Fix: Reinstall or check virtual environment
+
+---
+
+**For full spec-kitty documentation, see the main templates and README.**

specify_cli/templates/agent-file-template.md

@@ -0,0 +1,35 @@
+# [PROJECT NAME] Development Guidelines
+*Path: [templates/agent-file-template.md](templates/agent-file-template.md)*
+
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+```
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+[IF SCRIPT_TYPE=powershell]
+## PowerShell Syntax
+**⚠️ IMPORTANT**: You are in a PowerShell environment. See [.kittify/templates/POWERSHELL_SYNTAX.md](.kittify/templates/POWERSHELL_SYNTAX.md) for correct syntax.
+
+Quick reminders:
+- Use `-Json` not `--json`
+- Use `;` not `&&` for command chaining
+- Use `.\.kittify\scripts\powershell\` not `./kittify/scripts/bash/`
+[ENDIF]
+
+## Code Style
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

specify_cli/templates/checklist-template.md

@@ -0,0 +1,42 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+*Path: [templates/checklist-template.md](templates/checklist-template.md)*
+
+
+**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 `/speckit.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /speckit.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

specify_cli/templates/claudeignore-template

@@ -0,0 +1,58 @@
+# Spec Kitty Configuration and Templates
+# These are internal directories that shouldn't be scanned by AI assistants
+
+# Template directories (not working code)
+.kittify/templates/
+.kittify/missions/
+.kittify/scripts/
+
+# Agent command directories (generated from templates, not source)
+.claude/
+.codex/
+.gemini/
+.cursor/
+.qwen/
+.opencode/
+.windsurf/
+.kilocode/
+.augment/
+.roo/
+.amazonq/
+.github/copilot/
+
+# Git metadata
+.git/
+
+# Build artifacts and caches
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.coverage
+htmlcov/
+node_modules/
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# OS-specific files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE directories
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs and databases
+*.log
+*.db
+*.sqlite

specify_cli/templates/command-templates/accept.md

@@ -0,0 +1,141 @@
+---
+description: Validate feature readiness and guide final acceptance steps.
+scripts:
+  sh: spec-kitty agent feature accept --json {ARGS}
+  ps: spec-kitty agent --json {ARGS}
+---
+**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/accept.md](templates/commands/accept.md)*
+
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Discovery (auto-detect with smart defaults)
+
+**Goal:** Minimize user interaction by auto-detecting information from the environment.
+
+### Auto-Detection Strategy
+
+1. **Feature slug**:
+   - Run `git branch --show-current` to get current branch name
+   - If branch matches pattern `\d{3}-[a-z0-9-]+` (e.g., `001-privacy-cli`), use it as feature slug
+   - Only ask user if branch name doesn't match or if on `main`/`master`
+
+2. **Acceptance mode**:
+   - **Default to `local`** (most common workflow)
+   - User can override by saying "use PR mode" or "checklist only"
+   - Only ask if user explicitly requests clarification
+
+3. **Validation commands**:
+   - Search recent git log for test/build commands:
+     ```bash
+     git log --oneline -20 | grep -iE "(test|build|check|cargo|npm|pytest|make)"
+     ```
+   - Look for common patterns in project:
+     - Rust: `cargo test`, `cargo build --release`, `cargo check`
+     - Python: `pytest`, `python -m pytest`, `make test`
+     - Node: `npm test`, `npm run build`, `yarn test`
+     - Go: `go test ./...`, `go build`
+   - Check for CI config files (`.github/workflows/`, `.gitlab-ci.yml`) and extract test commands
+   - If found, report them and say "proceeding with these validation commands"
+   - If none found, proceed without validation commands (user can add later)
+   - **Never block on missing validation commands**
+
+4. **Acceptance actor**:
+   - Always defaults to `__AGENT__` (current agent name)
+   - No need to ask or confirm
+
+### Execution Flow
+
+**Preferred flow (no user questions):**
+```
+1. Auto-detect feature slug from git branch
+2. Use mode=local by default
+3. Search for validation commands in git log/project
+4. Proceed directly with acceptance
+```
+
+**Only ask the user if:**
+- Feature slug cannot be auto-detected (e.g., on main branch)
+- User explicitly provides conflicting information in $ARGUMENTS
+- Auto-detection fails for technical reasons
+
+**Present auto-detected values clearly:**
+```
+Running acceptance with auto-detected values:
+- Feature: 001-privacy-compiler-cli (from git branch)
+- Mode: local (default)
+- Validation: cargo test --all, cargo build --release (from git log)
+```
+
+**Never use `WAITING_FOR_ACCEPTANCE_INPUT` unless:**
+- Feature slug detection fails AND user didn't provide one
+- User explicitly asks a question that needs an answer
+
+If user provides explicit values in $ARGUMENTS, those override auto-detected values.
+
+## Execution Plan
+
+1. **Auto-detect parameters** (run these commands silently):
+   ```bash
+   # Detect feature slug
+   git branch --show-current
+
+   # Search for validation commands in recent commits
+   git log --oneline -20 | grep -iE "(test|build|check|cargo|npm|pytest|make)"
+   ```
+
+2. **Determine final values** (using auto-detection + user overrides):
+   - Feature slug: From git branch (or user override from $ARGUMENTS)
+   - Mode: `local` (or user override: "pr"/"checklist")
+   - Validation commands: From git log search (or user-specified)
+   - Actor: `__AGENT__` (always)
+
+3. **Present detected values to user** (brief confirmation):
+   ```
+   Running acceptance for feature 001-privacy-cli (mode: local)
+   Validation: cargo test --all, cargo build --release
+   ```
+
+4. **Compile the acceptance options** into an argument list:
+   - Always include `--actor "__AGENT__"`.
+   - Append `--feature "<slug>"` (from detection or user input).
+   - Append `--mode <mode>` (default: `local`).
+   - Append `--test "<command>"` for each validation command found.
+
+5. Run `{SCRIPT}` (the CLI wrapper) with the assembled arguments **and** `--json`.
+
+6. 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).
+
+7. 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).
+
+8. 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.