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

specify_cli/templates/command-templates/merge.md

@@ -0,0 +1,374 @@
+---
+description: Merge a completed feature into the main branch and clean up worktree
+scripts:
+  sh: "spec-kitty agent feature merge"
+  ps: "spec-kitty agent"
+---
+**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/merge.md](templates/commands/merge.md)*
+
+
+# Merge Feature Branch
+
+This command merges a completed feature branch into the main/target branch and handles cleanup of worktrees and branches.
+
+## ⛔ Location Pre-flight Check (CRITICAL)
+
+**BEFORE PROCEEDING:** You MUST be in the feature worktree, NOT the main repository.
+
+Verify your current location:
+```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` or `release/*`)
+
+**If you see:**
+- Branch showing `main` or `release/`
+- OR pwd shows the main repository root
+
+⛔ **STOP - DANGER! You are in the wrong location!**
+
+This command merges your feature INTO main. Running from the wrong location can cause:
+- Loss of work
+- Merge conflicts
+- Repository corruption
+
+**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 merge command again
+
+**Exception (main branch):**
+If you are on `main` and need to merge a workspace-per-WP feature, run:
+```bash
+spec-kitty merge --feature <feature-slug>
+```
+
+---
+
+## Prerequisites
+
+Before running this command:
+
+1. ✅ Feature must pass `/spec-kitty.accept` checks
+2. ✅ All work packages must be in `tasks/`
+3. ✅ Working directory must be clean (no uncommitted changes)
+4. ✅ Run the command from the feature worktree (Spec Kitty will move the merge to the primary repo automatically)
+
+## Location Pre-flight Check (CRITICAL for AI Agents)
+
+Before merging, verify you are in the correct working directory by running this validation:
+
+```bash
+python3 -c "
+from specify_cli.guards import validate_worktree_location
+result = validate_worktree_location()
+if not result.is_valid:
+    print(result.format_error())
+    print('\nThis command MUST run from a feature worktree, not the main repository.')
+    print('\nFor workspace-per-WP features, run from ANY WP worktree:')
+    print('  cd /path/to/project/.worktrees/<feature>-WP01')
+    print('  # or any other WP worktree for this feature')
+    raise SystemExit(1)
+else:
+    print('✓ Location verified:', result.branch_name)
+"
+```
+
+**What this validates**:
+- Current branch follows the feature pattern like `001-feature-name` or `001-feature-name-WP01`
+- You're not attempting to run from `main` or any release branch
+- The validator prints clear navigation instructions if you're outside the feature worktree
+
+**For workspace-per-WP features (0.11.0+)**:
+- Run merge from ANY WP worktree (e.g., `.worktrees/014-feature-WP09/`)
+- The merge command automatically detects all WP branches and merges them sequentially
+- You do NOT need to run merge from each WP worktree individually
+
+## What This Command Does
+
+1. **Detects** your current feature branch and worktree status
+2. **Runs** pre-flight validation across all worktrees and the target branch
+3. **Determines** merge order based on WP dependencies (workspace-per-WP)
+4. **Forecasts** conflicts during `--dry-run` and flags auto-resolvable status files
+5. **Verifies** working directory is clean (legacy single-worktree)
+6. **Switches** to the target branch (default: `main`) in the primary repository
+7. **Updates** the target branch (`git pull --ff-only`)
+8. **Merges** the feature using your chosen strategy
+9. **Auto-resolves** status file conflicts after each WP merge
+10. **Optionally pushes** to origin
+11. **Removes** the feature worktree (if in one)
+12. **Deletes** the feature branch
+
+## Usage
+
+### Basic merge (default: merge commit, cleanup everything)
+
+```bash
+spec-kitty merge
+```
+
+This will:
+- Create a merge commit
+- Remove the worktree
+- Delete the feature branch
+- Keep changes local (no push)
+
+### Merge with options
+
+```bash
+# Squash all commits into one
+spec-kitty merge --strategy squash
+
+# Push to origin after merging
+spec-kitty merge --push
+
+# Keep the feature branch
+spec-kitty merge --keep-branch
+
+# Keep the worktree
+spec-kitty merge --keep-worktree
+
+# Merge into a different branch
+spec-kitty merge --target develop
+
+# See what would happen without doing it
+spec-kitty merge --dry-run
+
+# Run merge from main for a workspace-per-WP feature
+spec-kitty merge --feature 017-feature-slug
+```
+
+### Common workflows
+
+```bash
+# Feature complete, squash and push
+spec-kitty merge --strategy squash --push
+
+# Keep branch for reference
+spec-kitty merge --keep-branch
+
+# Merge into develop instead of main
+spec-kitty merge --target develop --push
+```
+
+## Merge Strategies
+
+### `merge` (default)
+Creates a merge commit preserving all feature branch commits.
+```bash
+spec-kitty merge --strategy merge
+```
+✅ Preserves full commit history
+✅ Clear feature boundaries in git log
+❌ More commits in main branch
+
+### `squash`
+Squashes all feature commits into a single commit.
+```bash
+spec-kitty merge --strategy squash
+```
+✅ Clean, linear history on main
+✅ Single commit per feature
+❌ Loses individual commit details
+
+### `rebase`
+Requires manual rebase first (command will guide you).
+```bash
+spec-kitty merge --strategy rebase
+```
+✅ Linear history without merge commits
+❌ Requires manual intervention
+❌ Rewrites commit history
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--strategy` | Merge strategy: `merge`, `squash`, or `rebase` | `merge` |
+| `--delete-branch` / `--keep-branch` | Delete feature branch after merge | delete |
+| `--remove-worktree` / `--keep-worktree` | Remove feature worktree after merge | remove |
+| `--push` | Push to origin after merge | no push |
+| `--target` | Target branch to merge into | `main` |
+| `--dry-run` | Show what would be done without executing | off |
+| `--feature` | Feature slug when merging from main branch | none |
+| `--resume` | Resume an interrupted merge | off |
+
+## Worktree Strategy
+
+Spec Kitty uses an **opinionated worktree approach**:
+
+### Workspace-per-WP Model (0.11.0+)
+
+In the current model, each work package gets its own worktree:
+
+```
+my-project/                              # Main repo (main branch)
+├── .worktrees/
+│   ├── 001-auth-system-WP01/           # WP01 worktree
+│   ├── 001-auth-system-WP02/           # WP02 worktree
+│   ├── 001-auth-system-WP03/           # WP03 worktree
+│   └── 002-dashboard-WP01/             # Different feature
+├── .kittify/
+├── kitty-specs/
+└── ... (main branch files)
+```
+
+**Merge behavior for workspace-per-WP**:
+- Run `spec-kitty merge` from **any** WP worktree for the feature
+- The command automatically detects all WP branches (WP01, WP02, WP03, etc.)
+- Merges each WP branch into main in sequence
+- Cleans up all WP worktrees and branches
+
+### Legacy Pattern (0.10.x)
+```
+my-project/                    # Main repo (main branch)
+├── .worktrees/
+│   ├── 001-auth-system/      # Feature 1 worktree (single)
+│   ├── 002-dashboard/        # Feature 2 worktree (single)
+│   └── 003-notifications/    # Feature 3 worktree (single)
+├── .kittify/
+├── kitty-specs/
+└── ... (main branch files)
+```
+
+### The Rules
+1. **Main branch** stays in the primary repo root
+2. **Feature branches** live in `.worktrees/<feature-slug>/`
+3. **Work on features** happens in their worktrees (isolation)
+4. **Merge from worktrees** using this command – the CLI will hop to the primary repo for the Git merge
+5. **Cleanup is automatic** - worktrees removed after merge
+
+### Why Worktrees?
+- ✅ Work on multiple features simultaneously
+- ✅ Each feature has its own sandbox
+- ✅ No branch switching in main repo
+- ✅ Easy to compare features
+- ✅ Clean separation of concerns
+
+### The Flow
+```
+1. /spec-kitty.specify           → Creates branch + worktree
+2. cd .worktrees/<feature>/      → Enter worktree
+3. /spec-kitty.plan              → Work in isolation
+4. /spec-kitty.tasks
+5. /spec-kitty.implement
+6. /spec-kitty.review
+7. /spec-kitty.accept
+8. /spec-kitty.merge             → Merge + cleanup worktree
+9. Back in main repo!            → Ready for next feature
+```
+
+## Error Handling
+
+### "Already on main branch"
+You're not on a feature branch. Switch to your feature branch first:
+```bash
+cd .worktrees/<feature-slug>
+# or
+git checkout <feature-branch>
+```
+
+### "Working directory has uncommitted changes"
+Commit or stash your changes:
+```bash
+git add .
+git commit -m "Final changes"
+# or
+git stash
+```
+
+### "Could not fast-forward main"
+Your main branch is behind origin:
+```bash
+git checkout main
+git pull
+git checkout <feature-branch>
+spec-kitty merge
+```
+
+### "Merge failed - conflicts"
+Resolve conflicts manually:
+```bash
+# Fix conflicts in files
+git add <resolved-files>
+git commit
+# Then complete cleanup manually:
+git worktree remove .worktrees/<feature>
+git branch -d <feature-branch>
+```
+
+## Safety Features
+
+1. **Clean working directory check** - Won't merge with uncommitted changes
+2. **Primary repo hand-off** - Automatically runs Git operations from the main checkout when invoked in a worktree
+3. **Fast-forward only pull** - Won't proceed if main has diverged
+4. **Graceful failure** - If merge fails, you can fix manually
+5. **Optional operations** - Push, branch delete, and worktree removal are configurable
+6. **Dry run mode** - Preview exactly what will happen
+
+## Examples
+
+### Complete feature and push
+```bash
+cd .worktrees/001-auth-system
+/spec-kitty.accept
+/spec-kitty.merge --push
+```
+
+### Squash merge for cleaner history
+```bash
+spec-kitty merge --strategy squash --push
+```
+
+### Merge but keep branch for reference
+```bash
+spec-kitty merge --keep-branch --push
+```
+
+### Check what will happen first
+```bash
+spec-kitty merge --dry-run
+```
+
+## After Merging
+
+After a successful merge, you're back on the main branch with:
+- ✅ Feature code integrated
+- ✅ Worktree removed (if it existed)
+- ✅ Feature branch deleted (unless `--keep-branch`)
+- ✅ Ready to start your next feature!
+
+## Integration with Accept
+
+The typical flow is:
+
+```bash
+# 1. Run acceptance checks
+/spec-kitty.accept --mode local
+
+# 2. If checks pass, merge
+/spec-kitty.merge --push
+```
+
+Or combine conceptually:
+```bash
+# Accept verifies readiness
+/spec-kitty.accept --mode local
+
+# Merge performs integration
+/spec-kitty.merge --strategy squash --push
+```
+
+The `/spec-kitty.accept` command **verifies** your feature is complete.
+The `/spec-kitty.merge` command **integrates** your feature into main.
+
+Together they complete the workflow:
+```
+specify → plan → tasks → implement → review → accept → merge ✅
+```

specify_cli/templates/command-templates/plan.md

@@ -0,0 +1,171 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+# /spec-kitty.plan - Create Implementation Plan
+
+**Version**: 0.11.0+
+
+## 📍 WORKING DIRECTORY: Stay in MAIN repository
+
+**IMPORTANT**: Plan works in the main repository. NO worktrees created.
+
+```bash
+# Run from project root (same directory as /spec-kitty.specify):
+# You should already be here if you just ran /spec-kitty.specify
+
+# Creates:
+# - kitty-specs/###-feature/plan.md → In main repository
+# - Commits to main branch
+# - NO worktrees created
+```
+
+**Do NOT cd anywhere**. Stay in the main repository root.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Location Check (0.11.0+)
+
+This command runs in the **main repository**, not in a worktree.
+
+- Verify you're on `main` (or `master`) before scaffolding plan.md
+- Planning artifacts live in `kitty-specs/###-feature/`
+- The plan template is committed to the main branch after generation
+
+**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.
+
+## Planning Interrogation (mandatory)
+
+Before executing any scripts or generating artifacts you must interrogate the specification and stakeholders.
+
+- **Scope proportionality (CRITICAL)**: FIRST, assess the feature's complexity from the spec:
+  - **Trivial/Test Features** (hello world, simple static pages, basic demos): Ask 1-2 questions maximum about tech stack preference, then proceed with sensible defaults
+  - **Simple Features** (small components, minor API additions): Ask 2-3 questions about tech choices and constraints
+  - **Complex Features** (new subsystems, multi-component features): Ask 3-5 questions covering architecture, NFRs, integrations
+  - **Platform/Critical Features** (core infrastructure, security, payments): Full interrogation with 5+ questions
+
+- **User signals to reduce questioning**: If the user says "use defaults", "just make it simple", "skip to implementation", "vanilla HTML/CSS/JS" - recognize these as signals to minimize planning questions and use standard approaches.
+
+- **First response rule**:
+  - For TRIVIAL features: Ask ONE tech stack question, then if answer is simple (e.g., "vanilla HTML"), proceed directly to plan generation
+  - For other features: Ask a single architecture question and end with `WAITING_FOR_PLANNING_INPUT`
+
+- If the user has not provided plan context, keep interrogating with one question at a time.
+
+- **Conversational cadence**: After each reply, assess if you have SUFFICIENT context for this feature's scope. For trivial features, knowing the basic stack is enough. Only continue if critical unknowns remain.
+
+Planning requirements (scale to complexity):
+
+1. Maintain a **Planning Questions** table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for platform-level). Track columns `#`, `Question`, `Why it matters`, and `Current insight`. Do **not** render this table to the user.
+2. For trivial features, standard practices are acceptable (vanilla HTML, simple file structure, no build tools). Only probe if the user's request suggests otherwise.
+3. When you have sufficient context for the scope, summarize into an **Engineering Alignment** note and confirm.
+4. If user explicitly asks to skip questions or use defaults, acknowledge and proceed with best practices for that feature type.
+
+## Outline
+
+1. **Check planning discovery status**:
+   - If any planning questions remain unanswered or the user has not confirmed the **Engineering Alignment** summary, stay in the one-question cadence, capture the user's response, update your internal table, and end with `WAITING_FOR_PLANNING_INPUT`. Do **not** surface the table. Do **not** run the setup command yet.
+   - Once every planning question has a concrete answer and the alignment summary is confirmed by the user, continue.
+
+2. **Setup**: Run `spec-kitty agent feature setup-plan --json` from the repository root and parse JSON for:
+   - `result`: "success" or error message
+   - `plan_file`: Absolute path to the created plan.md
+   - `feature_dir`: Absolute path to the feature directory
+
+3. **Load context**: Read FEATURE_SPEC and `.kittify/memory/constitution.md` if it exists. If the constitution file is missing, skip Constitution Check and note that it is absent. Load IMPL_PLAN template (already copied).
+
+4. **Execute plan workflow**: Follow the structure in IMPL_PLAN template, using the validated planning answers as ground truth:
+   - Update Technical Context with explicit statements from the user or discovery research; mark `[NEEDS CLARIFICATION: …]` only when the user deliberately postpones a decision
+   - If a constitution exists, fill Constitution Check section from it and challenge any conflicts directly with the user. If no constitution exists, mark the section as skipped.
+   - Evaluate gates (ERROR if violations unjustified or questions remain unanswered)
+   - Phase 0: Generate research.md (commission research to resolve every outstanding clarification)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md based on confirmed intent
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design, asking the user to resolve new gaps before proceeding
+
+5. **STOP and report**: This command ends after Phase 1 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+   **⚠️ CRITICAL: DO NOT proceed to task generation!** The user must explicitly run `/spec-kitty.tasks` to generate work packages. Your job is COMPLETE after reporting the planning artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+   ```
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Agent context update**:
+   - Run `{AGENT_SCRIPT}`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+
+---
+
+## ⛔ MANDATORY STOP POINT
+
+**This command is COMPLETE after generating planning artifacts.**
+
+After reporting:
+- `plan.md` path
+- `research.md` path (if generated)
+- `data-model.md` path (if generated)
+- `contracts/` contents (if generated)
+- Agent context file updated
+
+**YOU MUST STOP HERE.**
+
+Do NOT:
+- ❌ Generate `tasks.md`
+- ❌ Create work package (WP) files
+- ❌ Create `tasks/` subdirectories
+- ❌ Proceed to implementation
+
+The user will run `/spec-kitty.tasks` when they are ready to generate work packages.
+
+**Next suggested command**: `/spec-kitty.tasks` (user must invoke this explicitly)

specify_cli/templates/command-templates/research.md

@@ -0,0 +1,88 @@
+---
+description: Run the Phase 0 research workflow to scaffold research artifacts before task planning.
+scripts:
+  sh: spec-kitty research
+  ps: spec-kitty research
+---
+**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/research.md](templates/commands/research.md)*
+
+
+## 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 creates research artifacts in your feature directory. You must be in the feature worktree.
+
+**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 research command again
+
+---
+
+## What This Command Creates
+
+When you run `{SCRIPT}`, the following files are generated in your feature directory:
+
+**Generated files**:
+- **research.md** – Decisions, rationale, and supporting evidence
+- **data-model.md** – Entities, attributes, and relationships
+- **research/evidence-log.csv** – Sources and findings audit trail
+- **research/source-register.csv** – Reference tracking for all sources
+
+**Location**: All files go in `kitty-specs/001-feature-name/`
+
+---
+
+## Workflow Context
+
+**Before this**: `/spec-kitty.plan` calls this as "Phase 0" research phase
+
+**This command**:
+- Scaffolds research artifacts
+- Creates templates for capturing decisions and evidence
+- Establishes audit trail for traceability
+
+**After this**:
+- Fill in research.md, data-model.md, and CSV logs with actual findings
+- Continue with `/spec-kitty.plan` which uses your research to drive technical design
+
+---
+
+## Goal
+
+Create `research.md`, `data-model.md`, and supporting CSV stubs based on the active mission so implementation planning can reference concrete decisions and evidence.
+
+## What to do
+
+1. You should already be in the correct feature worktree (verified above with pre-flight check).
+2. Run `{SCRIPT}` to generate the mission-specific research artifacts. (Add `--force` only when it is acceptable to overwrite existing drafts.)
+3. Open the generated files and fill in the required content:
+   - `research.md` – capture decisions, rationale, and supporting evidence.
+   - `data-model.md` – document entities, attributes, and relationships discovered during research.
+   - `research/evidence-log.csv` & `research/source-register.csv` – log all sources and findings so downstream reviewers can audit the trail.
+4. If your research generates additional templates (spreadsheets, notebooks, etc.), store them under `research/` and reference them inside `research.md`.
+5. Summarize open questions or risks at the bottom of `research.md`. These should feed directly into `/spec-kitty.tasks` and future implementation prompts.
+
+## Success Criteria
+
+- `kitty-specs/<feature>/research.md` explains every major decision with references to evidence.
+- `kitty-specs/<feature>/data-model.md` lists the entities and relationships needed for implementation.
+- CSV logs exist (even if partially filled) so evidence gathering is traceable.
+- Outstanding questions from the research phase are tracked and ready for follow-up during planning or execution.