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

specify_cli/missions/research/command-templates/merge.md

@@ -0,0 +1,388 @@
+---
+description: Merge a completed feature into the main branch and clean up worktree
+---
+
+# Merge Feature Branch
+
+This command merges a completed feature branch into the main/target branch and handles cleanup of worktrees and branches.
+
+## 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. ✅ You must be on the feature branch (or in its worktree)
+
+## ⛔ 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!**
+
+**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>
+```
+
+---
+
+## 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`
+- 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
+
+**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.
+
+## Final Research Integrity Check
+
+Before merging research to main, perform final validation:
+
+```bash
+# Quick citation validation
+python -c "
+from pathlib import Path
+from specify_cli.validators.research import validate_citations, validate_source_register
+
+feature_dir = Path('kitty-specs/$FEATURE_SLUG')
+evidence = feature_dir / 'research' / 'evidence-log.csv'
+sources = feature_dir / 'research' / 'source-register.csv'
+
+if evidence.exists():
+    result = validate_citations(evidence)
+    if result.has_errors:
+        print('ERROR: Evidence log has citation errors')
+        exit(1)
+
+if sources.exists():
+    result = validate_source_register(sources)
+    if result.has_errors:
+        print('ERROR: Source register has errors')
+        exit(1)
+
+print('✓ Citations validated')
+"
+```
+
+## 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`)
+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
+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. **Fast-forward only pull** - Won't proceed if main has diverged
+3. **Graceful failure** - If merge fails, you can fix manually
+4. **Optional operations** - Push, branch delete, and worktree removal are configurable
+5. **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/missions/research/command-templates/plan.md

@@ -0,0 +1,125 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Location Pre-flight Check (CRITICAL for AI Agents)
+
+Before proceeding with planning, verify you are in the correct working directory by running the shared pre-flight validation:
+
+```python
+```
+
+**What this validates**:
+- Current branch follows the feature pattern like `001-feature-name`
+- 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
+
+**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 `{SCRIPT}` yet.
+   - Once every planning question has a concrete answer and the alignment summary is confirmed by the user, continue.
+
+2. **Setup**: Run `{SCRIPT}` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
+
+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**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated 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

specify_cli/missions/research/command-templates/review.md

@@ -0,0 +1,144 @@
+---
+description: Perform structured research review with citation validation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Location Pre-flight Check (CRITICAL for AI Agents)
+
+Before proceeding with review, verify you are in the correct working directory by running the shared pre-flight validation:
+
+```python
+```
+
+**What this validates**:
+- Current branch follows the feature pattern like `001-feature-name`
+- 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
+
+**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.
+
+## Citation Validation (Research Mission Specific)
+
+Before reviewing research tasks, validate all citations and sources:
+
+```python
+from pathlib import Path
+from specify_cli.validators.research import validate_citations, validate_source_register
+
+# Validate evidence log
+evidence_log = FEATURE_DIR / "research" / "evidence-log.csv"
+if evidence_log.exists():
+    result = validate_citations(evidence_log)
+    if result.has_errors:
+        print(result.format_report())
+        print("\nERROR: Citation validation failed. Fix errors before proceeding.")
+        exit(1)
+    elif result.warning_count > 0:
+        print(result.format_report())
+        print("\nWarnings found - consider addressing for better citation quality.")
+
+# Validate source register
+source_register = FEATURE_DIR / "research" / "source-register.csv"
+if source_register.exists():
+    result = validate_source_register(source_register)
+    if result.has_errors:
+        print(result.format_report())
+        print("\nERROR: Source register validation failed.")
+        exit(1)
+```
+
+**Validation Requirements**:
+- All sources must be documented with unique `source_id` entries.
+- Citations must be present in both CSVs (format warnings are advisory).
+- Confidence levels should be filled for evidence entries.
+- Research review cannot proceed if validation reports blocking errors.
+
+## Outline
+
+1. Run `{SCRIPT}` from repo root; capture `FEATURE_DIR`, `AVAILABLE_DOCS`, and `tasks.md` path.
+
+2. Determine the review target:
+   - If user input specifies a filename, validate it exists under `tasks/` (flat structure, check `lane: "for_review"` in frontmatter).
+   - Otherwise, select the oldest file in `tasks/` (lexical order is sufficient because filenames retain task ordering).
+   - Abort with instructional message if no files are waiting for review.
+
+3. Load context for the selected task:
+   - Read the prompt file frontmatter (lane MUST be `for_review`); note `task_id`, `phase`, `agent`, `shell_pid`.
+   - Read the body sections (Objective, Context, Implementation Guidance, etc.).
+   - Consult supporting documents as referenced: constitution, plan, spec, data-model, research, quickstart, code changes.
+   - Review the associated code in the repository (diffs, tests, docs) to validate the implementation.
+
+4. Conduct the review:
+   - Verify implementation against the prompt’s Definition of Done and Review Guidance.
+   - Run required tests or commands; capture results.
+   - Document findings explicitly: bugs, regressions, missing tests, risks, or validation notes.
+
+5. Decide outcome:
+  - **Needs changes**:
+     * Append a new entry in the prompt’s **Activity Log** detailing feedback (include timestamp, reviewer agent, shell PID).
+     * Update frontmatter `lane` back to `planned`, clear `assignee` if necessary, keep history entry.
+     * Add/revise a `## Review Feedback` section (create if missing) summarizing action items.
+     * Run `spec-kitty agent tasks move-task <FEATURE> <TASK_ID> planned --note "Returned for changes"` (use the PowerShell equivalent on Windows) so the move and history update are staged consistently.
+  - **Approved**:
+     * Append Activity Log entry capturing approval details (capture shell PID via `echo $$` or helper script).
+     * Update frontmatter: set `lane=done`, set reviewer metadata (`agent`, `shell_pid`), optional `assignee` for approver.
+     * Use helper script to mark the task complete in `tasks.md` (see Step 6).
+     * Run `spec-kitty agent tasks move-task <FEATURE> <TASK_ID> done --note "Approved for release"` (PowerShell variant available) to transition the prompt into `tasks/`.
+
+6. Update `tasks.md` automatically:
+   - Run `spec-kitty agent tasks mark-status --task-id <TASK_ID> --status done` (POSIX) or `spec-kitty agent tasks mark-status --task-id <TASK_ID> --status done` (PowerShell) from repo root.
+   - Confirm the task entry now shows `[X]` and includes a reference to the prompt file in its notes.
+
+7. Produce a review report summarizing:
+   - Task ID and filename reviewed.
+  - Approval status and key findings.
+   - Tests executed and their results.
+   - Follow-up actions (if any) for other team members.
+   - Reminder to push changes or notify teammates as per project conventions.
+
+Context for review: {ARGS}
+
+All review feedback must live inside the prompt file, ensuring future implementers understand historical decisions before revisiting the task.
+
+## Citation Validation (Research Mission Specific)
+
+Before reviewing research tasks, validate all citations and sources:
+
+```python
+from pathlib import Path
+from specify_cli.validators.research import validate_citations, validate_source_register
+
+# Validate evidence log
+evidence_log = FEATURE_DIR / "research" / "evidence-log.csv"
+if evidence_log.exists():
+    result = validate_citations(evidence_log)
+    if result.has_errors:
+        print(result.format_report())
+        print("\nERROR: Citation validation failed. Fix errors before proceeding.")
+        exit(1)
+    elif result.warning_count > 0:
+        print(result.format_report())
+        print("\nWarnings found - consider addressing for better citation quality.")
+
+# Validate source register
+source_register = FEATURE_DIR / "research" / "source-register.csv"
+if source_register.exists():
+    result = validate_source_register(source_register)
+    if result.has_errors:
+        print(result.format_report())
+        print("\nERROR: Source register validation failed.")
+        exit(1)
+```
+
+**Validation Requirements**:
+- All sources must be documented with unique `source_id` entries.
+- Citations must be present in both CSVs (format warnings are advisory).
+- Confidence levels should be filled for evidence entries.
+- Research review cannot proceed if validation reports blocking errors.