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

specify_cli/templates/command-templates/specify.md

@@ -0,0 +1,321 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+# /spec-kitty.specify - Create Feature Specification
+
+**Version**: 0.11.0+
+
+## 📍 WORKING DIRECTORY: Stay in MAIN repository
+
+**IMPORTANT**: Specify works in the main repository. NO worktrees are created.
+
+```bash
+# Run from project root:
+cd /path/to/project/root  # Your main repository
+
+# All planning artifacts are created in main and committed:
+# - kitty-specs/###-feature/spec.md → Created in main
+# - Committed to main branch
+# - NO worktrees created
+```
+
+**Worktrees are created later** during `/spec-kitty.implement`, not during planning.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Discovery Gate (mandatory)
+
+Before running any scripts or writing to disk you **must** conduct a structured discovery interview.
+
+- **Scope proportionality (CRITICAL)**: FIRST, gauge the inherent complexity of the request:
+  - **Trivial/Test Features** (hello world, simple pages, proof-of-concept): Ask 1-2 questions maximum, then proceed. Examples: "a simple hello world page", "tic-tac-toe game", "basic contact form"
+  - **Simple Features** (small UI additions, minor enhancements): Ask 2-3 questions covering purpose and basic constraints
+  - **Complex Features** (new subsystems, integrations): Ask 3-5 questions covering goals, users, constraints, risks
+  - **Platform/Critical Features** (authentication, payments, infrastructure): Full discovery with 5+ questions
+
+- **User signals to reduce questioning**: If the user says "just testing", "quick prototype", "skip to next phase", "stop asking questions" - recognize this as a signal to minimize discovery and proceed with reasonable defaults.
+
+- **First response rule**:
+  - For TRIVIAL features (hello world, simple test): Ask ONE clarifying question, then if the answer confirms it's simple, proceed directly to spec generation
+  - For other features: Ask a single focused discovery question and end with `WAITING_FOR_DISCOVERY_INPUT`
+
+- If the user provides no initial description (empty command), stay in **Interactive Interview Mode**: keep probing with one question at a time.
+
+- **Conversational cadence**: After each user reply, decide if you have ENOUGH context for this feature's complexity level. For trivial features, 1-2 questions is sufficient. Only continue asking if truly necessary for the scope.
+
+Discovery requirements (scale to feature complexity):
+
+1. Maintain a **Discovery Questions** table internally covering questions appropriate to the feature's complexity (1-2 for trivial, up to 5+ for complex). Track columns `#`, `Question`, `Why it matters`, and `Current insight`. Do **not** render this table to the user.
+2. For trivial features, reasonable defaults are acceptable. Only probe if truly ambiguous.
+3. When you have sufficient context for the feature's scope, paraphrase into an **Intent Summary** and confirm. For trivial features, this can be very brief.
+4. If user explicitly asks to skip questions or says "just testing", acknowledge and proceed with minimal discovery.
+
+## Mission Selection
+
+After completing discovery and confirming the Intent Summary, determine the appropriate mission for this feature.
+
+### Available Missions
+
+- **software-dev**: For building software features, APIs, CLI tools, applications
+  - Phases: research → design → implement → test → review
+  - Best for: code changes, new features, bug fixes, refactoring
+
+- **research**: For investigations, literature reviews, technical analysis
+  - Phases: question → methodology → gather → analyze → synthesize → publish
+  - Best for: feasibility studies, market research, technology evaluation
+
+### Mission Inference
+
+1. **Analyze the feature description** to identify the primary goal:
+   - Building, coding, implementing, creating software → **software-dev**
+   - Researching, investigating, analyzing, evaluating → **research**
+
+2. **Check for explicit mission requests** in the user's description:
+   - If user mentions "research project", "investigation", "analysis" → use research
+   - If user mentions "build", "implement", "create feature" → use software-dev
+
+3. **Confirm with user** (unless explicit):
+   > "Based on your description, this sounds like a **[software-dev/research]** project.
+   > I'll use the **[mission name]** mission. Does that work for you?"
+
+4. **Handle user response**:
+   - If confirmed: proceed with selected mission
+   - If user wants different mission: use their choice
+
+5. **Handle --mission flag**: If the user provides `--mission <key>` in their command, skip inference and use the specified mission directly.
+
+Store the final mission selection in your notes and include it in the spec output. Do not pass a `--mission` flag to feature creation.
+
+## Workflow (0.11.0+)
+
+**Planning happens in main repository - NO worktree created!**
+
+1. Creates `kitty-specs/###-feature/spec.md` directly in main repo
+2. Automatically commits to main branch
+3. No worktree created during specify
+
+**Worktrees created later**: Use `spec-kitty implement WP##` to create a workspace for each work package. Worktrees are created later during implement (e.g., `.worktrees/###-feature-WP##`).
+
+## Location
+
+- Work in: **Main repository** (not a worktree)
+- Creates: `kitty-specs/###-feature/spec.md`
+- Commits to: `main` branch
+
+## Outline
+
+### 0. Generate a Friendly Feature Title
+
+- Summarize the agreed intent into a short, descriptive title (aim for ≤7 words; avoid filler like "feature" or "thing").
+- Read that title back during the Intent Summary and revise it if the user requests changes.
+- Use the confirmed title to derive the kebab-case feature slug for the create-feature command.
+
+The text the user typed after `/spec-kitty.specify` in the triggering message **is** the initial feature description. Capture it verbatim, but treat it only as a starting point for discovery—not the final truth. Your job is to interrogate the request, surface gaps, and co-create a complete specification with the user.
+
+Given that feature description, do this:
+
+- **Generation Mode (arguments provided)**: Use the provided text as a starting point, validate it through discovery, and fill gaps with explicit questions or clearly documented assumptions (limit `[NEEDS CLARIFICATION: …]` to at most three critical decisions the user has postponed).
+- **Interactive Interview Mode (no arguments)**: Use the discovery interview to elicit all necessary context, synthesize the working feature description, and confirm it with the user before you generate any specification artifacts.
+
+1. **Check discovery status**:
+   - If this is your first message or discovery questions remain unanswered, stay in the one-question loop, capture the user's response, update your internal table, and end with `WAITING_FOR_DISCOVERY_INPUT`. Do **not** surface the table; keep it internal. Do **not** call the creation command yet.
+   - Only proceed once every discovery question has an explicit answer and the user has acknowledged the Intent Summary.
+   - Empty invocation rule: stay in interview mode until you can restate the agreed-upon feature description. Do **not** call the creation command while the description is missing or provisional.
+
+2. When discovery is complete and the intent summary, **title**, and **mission** are confirmed, run the feature creation command from repo root:
+
+   ```bash
+   spec-kitty agent feature create-feature "<slug>" --json
+   ```
+
+   Where `<slug>` is a kebab-case version of the friendly title (e.g., "Checkout Upsell Flow" → "checkout-upsell-flow").
+
+   The command returns JSON with:
+   - `result`: "success" or error message
+   - `feature`: Feature number and slug (e.g., "014-checkout-upsell-flow")
+   - `feature_dir`: Absolute path to the feature directory inside the main repo
+
+   Parse these values for use in subsequent steps. All file paths are absolute.
+
+   **IMPORTANT**: You must only ever run this command once. The JSON is provided in the terminal output - always refer to it to get the actual paths you're looking for.
+3. **Stay in the main repository**: No worktree is created during specify.
+
+4. Load the spec template from `.kittify/templates/spec-template.md` (or `templates/spec-template.md`) to understand required sections.
+
+5. Create meta.json in the feature directory with:
+   ```json
+   {
+     "feature_number": "<number>",
+     "slug": "<full-slug>",
+     "friendly_name": "<Friendly Title>",
+     "mission": "<selected-mission>",
+     "source_description": "$ARGUMENTS",
+     "created_at": "<ISO timestamp>"
+   }
+   ```
+
+6. Generate the specification content by following this flow:
+    - Use the discovery answers as your authoritative source of truth (do **not** rely on raw `$ARGUMENTS`)
+    - For empty invocations, treat the synthesized interview summary as the canonical feature description
+    - Identify: actors, actions, data, constraints, motivations, success metrics
+    - For any remaining ambiguity:
+      * Ask the user a focused follow-up question immediately and halt work until they answer
+      * Only use `[NEEDS CLARIFICATION: …]` when the user explicitly defers the decision
+      * Record any interim assumption in the Assumptions section
+      * Prioritize clarifications by impact: scope > outcomes > risks/security > user experience > technical details
+    - Fill User Scenarios & Testing section (ERROR if no clear user flow can be determined)
+    - Generate Functional Requirements (each requirement must be testable)
+    - Define Success Criteria (measurable, technology-agnostic outcomes)
+    - Identify Key Entities (if data involved)
+
+7. Write the specification to `<feature_dir>/spec.md` using the template structure, replacing placeholders with concrete details derived from the feature description while preserving section order and headings.
+
+8. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+   
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/spec-kitty.clarify` or `/spec-kitty.plan`
+      ```
+   
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+   
+   c. **Handle Validation Results**:
+      
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+      
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+      
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. Re-confirm with the user whether each outstanding decision truly needs to stay unresolved. Do not assume away critical gaps.
+        3. For each clarification the user has explicitly deferred, present options using plain text—no tables:
+        
+           ```
+           Question [N]: [Topic]
+           Context: [Quote relevant spec section]
+           Need: [Specific question from NEEDS CLARIFICATION marker]
+           Options: (A) [First answer — implications] · (B) [Second answer — implications] · (C) [Third answer — implications] · (D) Custom (describe your own answer)
+           Reply with a letter or a custom answer.
+           ```
+        
+        4. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        5. Present all questions together before waiting for responses
+        6. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        7. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+   
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+9. Report completion with feature directory, spec file path, checklist results, and readiness for the next phase (`/spec-kitty.clarify` or `/spec-kitty.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+   
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)

specify_cli/templates/command-templates/status.md

@@ -0,0 +1,92 @@
+---
+description: Display kanban board status showing work package progress across lanes (planned/doing/for_review/done).
+---
+
+## Status Board
+
+Show the current status of all work packages in the active feature. This displays:
+- Kanban board with WPs organized by lane
+- Progress bar showing completion percentage
+- Parallelization opportunities (which WPs can run concurrently)
+- Next steps recommendations
+
+## When to Use
+
+- Before starting work (see what's ready to implement)
+- During implementation (track overall progress)
+- After completing a WP (see what's next)
+- When planning parallelization (identify independent WPs)
+
+## Implementation
+
+Run the CLI command to display the status board:
+
+```bash
+spec-kitty agent tasks status
+```
+
+To specify a feature explicitly:
+
+```bash
+spec-kitty agent tasks status --feature 012-documentation-mission
+```
+
+The command displays a rich kanban board with:
+- Progress bar showing completion percentage
+- Work packages organized by lane (planned/doing/for_review/done)
+- Summary metrics
+
+## Alternative: Python API
+
+For programmatic access (e.g., in Jupyter notebooks or scripts), use the Python function:
+
+```python
+from specify_cli.agent_utils.status import show_kanban_status
+
+# Auto-detect feature from current directory/branch
+result = show_kanban_status()
+
+# Or specify feature explicitly:
+# result = show_kanban_status("012-documentation-mission")
+```
+
+Returns structured data:
+
+```python
+{
+    'feature_slug': '012-documentation-mission',
+    'progress_percentage': 80.0,
+    'done_count': 8,
+    'total_wps': 10,
+    'by_lane': {
+        'planned': ['WP09'],
+        'doing': ['WP10'],
+        'for_review': [],
+        'done': ['WP01', 'WP02', ...]
+    },
+    'parallelization': {
+        'ready_wps': [...],
+        'can_parallelize': True/False,
+        'parallel_groups': [...]
+    }
+}
+
+## Output Example
+
+```
+╭─────────────────────────────────────────────────────────────────────╮
+│                    012-documentation-mission                        │
+│                     Progress: 80% [████████░░]                      │
+╰─────────────────────────────────────────────────────────────────────╯
+
+┌─────────────┬─────────────┬─────────────┬─────────────┐
+│   PLANNED   │    DOING    │ FOR_REVIEW  │    DONE     │
+├─────────────┼─────────────┼─────────────┼─────────────┤
+│ WP09        │ WP10        │             │ WP01        │
+│             │             │             │ WP02        │
+│             │             │             │ WP03        │
+│             │             │             │ ...         │
+└─────────────┴─────────────┴─────────────┴─────────────┘
+
+🔀 Parallelization: WP09 can start (no dependencies)
+```

specify_cli/templates/command-templates/tasks.md

@@ -0,0 +1,199 @@
+---
+description: Generate grouped work packages with actionable subtasks and matching prompt files for the feature in one pass.
+---
+
+# /spec-kitty.tasks - Generate Work Packages
+
+**Version**: 0.11.0+
+
+## 📍 WORKING DIRECTORY: Stay in MAIN repository
+
+**IMPORTANT**: Tasks works in the main repository. NO worktrees created.
+
+```bash
+# Run from project root (same directory as /spec-kitty.plan):
+# You should already be here if you just ran /spec-kitty.plan
+
+# Creates:
+# - kitty-specs/###-feature/tasks/WP01-*.md → In main repository
+# - kitty-specs/###-feature/tasks/WP02-*.md → In main repository
+# - Commits ALL to main branch
+# - NO worktrees created
+```
+
+**Do NOT cd anywhere**. Stay in the main repository root.
+
+**Worktrees created later**: After tasks are generated, use `spec-kitty implement WP##` to create workspace for each WP.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Location Check (0.11.0+)
+
+Before proceeding, verify you are in the main repository:
+
+**Check your current branch:**
+```bash
+git branch --show-current
+```
+
+**Expected output:** `main` (or `master`)
+**If you see a feature branch:** You're in the wrong place. Return to main:
+```bash
+cd $(git rev-parse --show-toplevel)
+git checkout main
+```
+
+Work packages are generated directly in `kitty-specs/###-feature/` and committed to main. Worktrees are created later when implementing each work package.
+
+## Outline
+
+1. **Setup**: Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks` from the repository root and capture `FEATURE_DIR` plus `AVAILABLE_DOCS`. All paths must be absolute.
+
+   **CRITICAL**: The command returns JSON with `FEATURE_DIR` as an ABSOLUTE path (e.g., `/Users/robert/Code/new_specify/kitty-specs/001-feature-name`).
+
+   **YOU MUST USE THIS PATH** for ALL subsequent file operations. Example:
+   ```
+   FEATURE_DIR = "/Users/robert/Code/new_specify/kitty-specs/001-a-simple-hello"
+   tasks.md location: FEATURE_DIR + "/tasks.md"
+   prompt location: FEATURE_DIR + "/tasks/WP01-slug.md"
+   ```
+
+   **DO NOT CREATE** paths like:
+   - ❌ `tasks/WP01-slug.md` (missing FEATURE_DIR prefix)
+   - ❌ `/tasks/WP01-slug.md` (wrong root)
+   - ❌ `FEATURE_DIR/tasks/planned/WP01-slug.md` (WRONG - no subdirectories!)
+   - ❌ `WP01-slug.md` (wrong directory)
+
+2. **Load design documents** from `FEATURE_DIR` (only those present):
+   - **Required**: plan.md (tech architecture, stack), spec.md (user stories & priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API schemas), research.md (decisions), quickstart.md (validation scenarios)
+   - Scale your effort to the feature: simple UI tweaks deserve lighter coverage, multi-system releases require deeper decomposition.
+
+3. **Derive fine-grained subtasks** (IDs `T001`, `T002`, ...):
+   - Parse plan/spec to enumerate concrete implementation steps, tests (only if explicitly requested), migrations, and operational work.
+   - Capture prerequisites, dependencies, and parallelizability markers (`[P]` means safe to parallelize per file/concern).
+   - Maintain the subtask list internally; it feeds the work-package roll-up and the prompts.
+
+4. **Roll subtasks into work packages** (IDs `WP01`, `WP02`, ...):
+   - Target 4–10 work packages. Each should be independently implementable, rooted in a single user story or cohesive subsystem.
+   - Ensure every subtask appears in exactly one work package.
+   - Name each work package with a succinct goal (e.g., “User Story 1 – Real-time chat happy path”).
+   - Record per-package metadata: priority, success criteria, risks, dependencies, and list of included subtasks.
+
+5. **Write `tasks.md`** using `.kittify/templates/tasks-template.md`:
+   - **Location**: Write to `FEATURE_DIR/tasks.md` (use the absolute FEATURE_DIR path from step 1)
+   - Populate the Work Package sections (setup, foundational, per-story, polish) with the `WPxx` entries
+   - Under each work package include:
+     - Summary (goal, priority, independent test)
+     - Included subtasks (checkbox list referencing `Txxx`)
+     - Implementation sketch (high-level sequence)
+     - Parallel opportunities, dependencies, and risks
+   - Preserve the checklist style so implementers can mark progress
+
+6. **Generate prompt files (one per work package)**:
+   - **CRITICAL PATH RULE**: All work package files MUST be created in a FLAT `FEATURE_DIR/tasks/` directory, NOT in subdirectories!
+   - Correct structure: `FEATURE_DIR/tasks/WPxx-slug.md` (flat, no subdirectories)
+   - WRONG (do not create): `FEATURE_DIR/tasks/planned/`, `FEATURE_DIR/tasks/doing/`, or ANY lane subdirectories
+   - WRONG (do not create): `/tasks/`, `tasks/`, or any path not under FEATURE_DIR
+   - Ensure `FEATURE_DIR/tasks/` exists (create as flat directory, NO subdirectories)
+   - For each work package:
+     - Derive a kebab-case slug from the title; filename: `WPxx-slug.md`
+     - Full path example: `FEATURE_DIR/tasks/WP01-create-html-page.md` (use ABSOLUTE path from FEATURE_DIR variable)
+     - Use `.kittify/templates/task-prompt-template.md` to capture:
+     - Frontmatter with `work_package_id`, `subtasks` array, `lane: "planned"`, `dependencies`, history entry
+       - Objective, context, detailed guidance per subtask
+       - Test strategy (only if requested)
+       - Definition of Done, risks, reviewer guidance
+     - Update `tasks.md` to reference the prompt filename
+   - Keep prompts exhaustive enough that a new agent can complete the work package unaided
+
+   **IMPORTANT**: All WP files live in flat `tasks/` directory. Lane status is tracked ONLY in the `lane:` frontmatter field, NOT by directory location. Agents can change lanes by editing the `lane:` field directly or using `spec-kitty agent tasks move-task`.
+
+7. **Finalize tasks with dependency parsing and commit**:
+   After generating all WP prompt files, run the finalization command to:
+   - Parse dependencies from tasks.md
+   - Update WP frontmatter with dependencies field
+   - Validate dependencies (check for cycles, invalid references)
+   - Commit all tasks to main branch
+
+   **CRITICAL**: Run this command from repo root:
+   ```bash
+   spec-kitty agent feature finalize-tasks --json
+   ```
+
+   This step is MANDATORY for workspace-per-WP features. Without it:
+   - Dependencies won't be in frontmatter
+   - Agents won't know which --base flag to use
+   - Tasks won't be committed to main
+
+8. **Report**: Provide a concise outcome summary:
+   - Path to `tasks.md`
+   - Work package count and per-package subtask tallies
+   - Parallelization highlights
+   - MVP scope recommendation (usually Work Package 1)
+   - Prompt generation stats (files written, directory structure, any skipped items with rationale)
+   - Finalization status (dependencies parsed, X WP files updated, committed to main)
+   - Next suggested command (e.g., `/spec-kitty.analyze` or `/spec-kitty.implement`)
+
+Context for work-package planning: {ARGS}
+
+The combination of `tasks.md` and the bundled prompt files must enable a new engineer to pick up any work package and deliver it end-to-end without further specification spelunking.
+
+## Dependency Detection (0.11.0+)
+
+**Parse dependencies from tasks.md structure**:
+
+The LLM should analyze tasks.md for dependency relationships:
+- Explicit phrases: "Depends on WP##", "Dependencies: WP##"
+- Phase grouping: Phase 2 WPs typically depend on Phase 1
+- Default to empty if unclear
+
+**Generate dependencies in WP frontmatter**:
+
+Each WP prompt file MUST include a `dependencies` field:
+```yaml
+---
+work_package_id: "WP02"
+title: "Build API"
+lane: "planned"
+dependencies: ["WP01"]  # Generated from tasks.md
+subtasks: ["T001", "T002"]
+---
+```
+
+**Include the correct implementation command**:
+- No dependencies: `spec-kitty implement WP01`
+- With dependencies: `spec-kitty implement WP02 --base WP01`
+
+The WP prompt must show the correct command so agents don't branch from the wrong base.
+
+## Task Generation Rules
+
+**Tests remain optional**. Only include testing tasks/steps if the feature spec or user explicitly demands them.
+
+1. **Subtask derivation**:
+   - Assign IDs `Txxx` sequentially in execution order.
+   - Use `[P]` for parallel-safe items (different files/components).
+   - Include migrations, data seeding, observability, and operational chores.
+
+2. **Work package grouping**:
+   - Map subtasks to user stories or infrastructure themes.
+   - Keep each work package laser-focused on a single goal; avoid mixing unrelated stories.
+   - Do not exceed 10 work packages. Merge low-effort items into broader bundles when necessary.
+
+3. **Prioritisation & dependencies**:
+   - Sequence work packages: setup → foundational → story phases (priority order) → polish.
+   - Call out inter-package dependencies explicitly in both `tasks.md` and the prompts.
+
+4. **Prompt composition**:
+   - Mirror subtask order inside the prompt.
+   - Provide actionable implementation and test guidance per subtask—short for trivial work, exhaustive for complex flows.
+   - Surface risks, integration points, and acceptance gates clearly so reviewers know what to verify.
+
+5. **Think like a tester**: Any vague requirement should be tightened until a reviewer can objectively mark it done or not done.

specify_cli/templates/git-hooks/pre-commit

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Main pre-commit hook that orchestrates all pre-commit checks
+#
+# This hook runs all individual check scripts in the git-hooks directory.
+# Individual checks can be bypassed with --no-verify, but this should be
+# used sparingly and only when you're certain the commit is safe.
+
+set -e
+
+HOOKS_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Run encoding check if it exists
+if [ -x "$HOOKS_DIR/pre-commit-encoding-check" ]; then
+    "$HOOKS_DIR/pre-commit-encoding-check" || exit 1
+fi
+
+# Run agent directory check if it exists
+if [ -x "$HOOKS_DIR/pre-commit-agent-check" ]; then
+    "$HOOKS_DIR/pre-commit-agent-check" || exit 1
+fi
+
+exit 0

specify_cli/templates/git-hooks/pre-commit-agent-check

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Pre-commit hook to prevent committing agent directories
+#
+# Agent directories (.claude/, .codex/, etc.) may contain:
+# - Authentication tokens and API keys
+# - User-specific credentials (auth.json)
+# - Session data and conversation history
+#
+# These should NEVER be committed to version control.
+
+AGENT_DIRS=(".claude" ".codex" ".gemini" ".cursor" ".qwen" ".opencode"
+            ".windsurf" ".kilocode" ".augment" ".roo" ".amazonq" ".github/copilot")
+
+STAGED_AGENT_FILES=$(git diff --cached --name-only --diff-filter=ACM |
+                      grep -E "^\.(claude|codex|gemini|cursor|qwen|opencode|windsurf|kilocode|augment|roo|amazonq)/|^\.github/copilot/" || true)
+
+if [ -n "$STAGED_AGENT_FILES" ]; then
+    echo "❌ COMMIT BLOCKED: Agent directory files detected"
+    echo ""
+    echo "The following agent directory files are staged:"
+    echo "$STAGED_AGENT_FILES" | sed 's/^/  /'
+    echo ""
+    echo "These directories should NEVER be committed:"
+    for dir in "${AGENT_DIRS[@]}"; do
+        echo "  - $dir/ (may contain auth tokens and credentials)"
+    done
+    echo ""
+    echo "To fix:"
+    echo "  1. Unstage these files: git reset HEAD <file>"
+    echo "  2. Ensure .gitignore includes all agent directories"
+    echo "  3. Run: git status to verify"
+    echo ""
+    echo "To bypass this check (NOT recommended): git commit --no-verify"
+    exit 1
+fi
+
+exit 0