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

specify_cli/missions/documentation/command-templates/tasks.md

@@ -0,0 +1,189 @@
+---
+description: Generate documentation work packages and subtasks aligned to Divio types.
+---
+
+# Command Template: /spec-kitty.tasks (Documentation Mission)
+
+**Phase**: Design (finalizing work breakdown)
+**Purpose**: Break documentation work into independently implementable work packages with subtasks.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Location Pre-flight Check
+
+Verify you are in the main repository (not a worktree). Task generation happens in main for ALL missions.
+
+```bash
+git branch --show-current  # Should show "main"
+```
+
+**Note**: Task generation in main is standard for all spec-kitty missions. Implementation happens in per-WP worktrees.
+
+---
+
+## Outline
+
+1. **Setup**: Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks`
+
+2. **Load design documents**:
+   - spec.md (documentation goals, selected Divio types)
+   - plan.md (structure design, generator configs)
+   - gap-analysis.md (if gap-filling mode)
+   - meta.json (iteration_mode, generators_configured)
+
+3. **Derive fine-grained subtasks**:
+
+   ### Subtask Patterns for Documentation
+
+   **Structure Setup** (all modes):
+   - T001: Create `docs/` directory structure
+   - T002: Create index.md landing page
+   - T003: [P] Configure Sphinx (if Python detected)
+   - T004: [P] Configure JSDoc (if JavaScript detected)
+   - T005: [P] Configure rustdoc (if Rust detected)
+   - T006: Set up build script (Makefile or build.sh)
+
+   **Tutorial Creation** (if tutorial selected):
+   - T010: Write "Getting Started" tutorial
+   - T011: Write "Basic Usage" tutorial
+   - T012: [P] Write "Advanced Topics" tutorial
+   - T013: Add screenshots/examples to tutorials
+   - T014: Test tutorials with fresh user
+
+   **How-To Creation** (if how-to selected):
+   - T020: Write "How to Deploy" guide
+   - T021: Write "How to Configure" guide
+   - T022: Write "How to Troubleshoot" guide
+   - T023: [P] Write additional task-specific guides
+
+   **Reference Generation** (if reference selected):
+   - T030: Generate Python API reference (Sphinx autodoc)
+   - T031: Generate JavaScript API reference (JSDoc)
+   - T032: Generate Rust API reference (cargo doc)
+   - T033: Write CLI reference (manual)
+   - T034: Write configuration reference (manual)
+   - T035: Integrate generated + manual reference
+   - T036: Validate all public APIs documented
+
+   **Explanation Creation** (if explanation selected):
+   - T040: Write "Architecture Overview" explanation
+   - T041: Write "Core Concepts" explanation
+   - T042: Write "Design Decisions" explanation
+   - T043: [P] Add diagrams illustrating concepts
+
+   **Quality Validation** (all modes):
+   - T050: Validate heading hierarchy
+   - T051: Validate all images have alt text
+   - T052: Check for broken internal links
+   - T053: Check for broken external links
+   - T054: Verify code examples work
+   - T055: Check bias-free language
+   - T056: Build documentation site
+   - T057: Deploy to hosting (if applicable)
+
+4. **Roll subtasks into work packages**:
+
+   ### Work Package Patterns
+
+   **For Initial Mode**:
+   - WP01: Structure & Generator Setup (T001-T006)
+   - WP02: Tutorial Documentation (T010-T014) - If tutorials selected
+   - WP03: How-To Documentation (T020-T023) - If how-tos selected
+   - WP04: Reference Documentation (T030-T036) - If reference selected
+   - WP05: Explanation Documentation (T040-T043) - If explanation selected
+   - WP06: Quality Validation (T050-T057)
+
+   **For Gap-Filling Mode**:
+   - WP01: High-Priority Gaps (tasks for critical missing docs from gap analysis)
+   - WP02: Medium-Priority Gaps (tasks for important missing docs)
+   - WP03: Generator Updates (regenerate outdated API docs)
+   - WP04: Quality Validation (validate all docs, old and new)
+
+   **For Feature-Specific Mode**:
+   - WP01: Feature Documentation (tasks for documenting the feature across selected Divio types)
+   - WP02: Integration (tasks for integrating feature docs with existing docs)
+   - WP03: Quality Validation (validate feature-specific docs)
+
+   ### Prioritization
+
+   - **P0 (foundation)**: Structure setup, generator configuration
+   - **P1 (critical)**: Tutorials (if new users), Reference (if API docs missing)
+   - **P2 (important)**: How-Tos (solve known problems), Explanation (understanding)
+   - **P3 (polish)**: Quality validation, accessibility improvements
+
+5. **Write `tasks.md`**:
+   - Use `templates/tasks-template.md` from documentation mission
+   - Include work packages with subtasks
+   - Mark parallel opportunities (`[P]`)
+   - Define dependencies (WP01 must complete before others)
+   - Identify MVP scope (typically WP01 + Reference generation)
+
+6. **Generate prompt files**:
+   - Create flat `FEATURE_DIR/tasks/` directory (no subdirectories!)
+   - For each work package:
+     - Generate `WPxx-slug.md` using `templates/task-prompt-template.md`
+     - Include objectives, context, subtask guidance
+     - Add quality validation strategy (documentation-specific)
+     - Include Divio compliance checks
+     - Add accessibility/inclusivity checklists
+     - Set `lane: "planned"` in frontmatter
+
+7. **Report**:
+   - Path to tasks.md
+   - Work package count and subtask tallies
+   - Parallelization opportunities
+   - MVP recommendation
+   - Next command: `/spec-kitty.implement WP01` (or review tasks.md first)
+
+---
+
+## Documentation-Specific Task Generation Rules
+
+**Generator Subtasks**:
+- Mark generators as `[P]` (parallel) - different languages can generate simultaneously
+- Include tool check subtasks (verify sphinx-build, npx, cargo available)
+- Include config generation subtasks (create conf.py, jsdoc.json)
+- Include actual generation subtasks (run the generator)
+- Include integration subtasks (link generated docs into manual structure)
+
+**Content Authoring Subtasks**:
+- One subtask per document (don't bundle "write all tutorials" into one task)
+- Mark independent docs as `[P]` (parallel) - different docs can be written simultaneously
+- Include validation subtasks (test tutorials, verify how-tos solve problems)
+
+**Quality Validation Subtasks**:
+- Mark validation checks as `[P]` (parallel) - different checks can run simultaneously
+- Include automated checks (link checker, spell check, build)
+- Include manual checks (accessibility review, Divio compliance)
+
+**Work Package Scope**:
+- Each Divio type typically gets its own work package (WP for tutorials, WP for how-tos, etc.)
+- Exception: Small projects may combine types if only 1-2 docs per type
+- Generator setup is always separate (WP01 foundation)
+- Quality validation is always separate (final WP)
+
+---
+
+## Key Guidelines
+
+**For Agents**:
+- Adapt work packages to iteration mode
+- For gap-filling, work packages target specific gaps from audit
+- Mark generator invocations as parallel (different languages)
+- Mark independent docs as parallel (different files)
+- Include Divio compliance in Definition of Done for each WP
+- Quality validation is final work package (depends on all others)
+- If publish is in scope, add a release WP to produce `release.md`
+
+**For Users**:
+- Tasks.md shows the full work breakdown
+- Work packages are independently implementable
+- MVP often just structure + reference (API docs)
+- Full documentation includes all Divio types
+- Parallel work packages can be implemented simultaneously

specify_cli/missions/documentation/mission.yaml

@@ -0,0 +1,113 @@
+name: "Documentation Kitty"
+description: "Create and maintain high-quality software documentation following Write the Docs and Divio principles"
+version: "1.0.0"
+domain: "other"
+
+# Workflow customization
+workflow:
+  phases:
+    - name: "discover"
+      description: "Identify documentation needs and target audience"
+    - name: "audit"
+      description: "Analyze existing documentation and identify gaps"
+    - name: "design"
+      description: "Plan documentation structure and Divio types"
+    - name: "generate"
+      description: "Create documentation from templates and generators"
+    - name: "validate"
+      description: "Check quality, accessibility, and completeness"
+    - name: "publish"
+      description: "Deploy documentation and notify stakeholders"
+
+# Expected artifacts
+artifacts:
+  required:
+    - spec.md
+    - plan.md
+    - tasks.md
+    - gap-analysis.md
+  optional:
+    - divio-templates/
+    - generator-configs/
+    - audit-report.md
+    - research.md
+    - data-model.md
+    - quickstart.md
+    - release.md
+
+# Path conventions for this mission
+paths:
+  workspace: "docs/"
+  deliverables: "docs/output/"
+  documentation: "docs/"
+
+# Validation rules
+validation:
+  checks:
+    - all_divio_types_valid
+    - no_conflicting_generators
+    - templates_populated
+    - gap_analysis_complete
+  custom_validators: false  # No custom validators.py initially
+
+# MCP tools recommended for this mission
+mcp_tools:
+  required:
+    - filesystem
+    - git
+  recommended:
+    - web-search
+    - code-search
+  optional:
+    - github
+    - gitlab
+
+# Agent personality/instructions
+agent_context: |
+  You are a documentation agent following Write the Docs best practices and the Divio documentation system.
+
+  Key Practices:
+  - Documentation as code: docs live in version control alongside source
+  - Divio 4-type system: tutorial, how-to, reference, explanation (distinct purposes)
+  - Accessibility: clear language, proper headings, alt text for images
+  - Bias-free language: inclusive examples and terminology
+  - Iterative improvement: support gap-filling and feature-specific documentation
+
+  Workflow Phases: discover → audit → design → generate → validate → publish
+
+  Generator Integration:
+  - JSDoc for JavaScript/TypeScript API reference
+  - Sphinx for Python API reference (autodoc + napoleon)
+  - rustdoc for Rust API reference
+
+  Gap Analysis:
+  - Audit existing docs to identify missing Divio types
+  - Build coverage matrix showing what exists vs what's needed
+  - Prioritize gaps by user impact
+
+# Task metadata fields
+task_metadata:
+  required:
+    - task_id
+    - lane
+    - phase
+    - agent
+  optional:
+    - shell_pid
+    - assignee
+    - estimated_hours
+
+# Command customization
+commands:
+  specify:
+    prompt: "Define documentation needs: iteration mode (initial/gap-filling/feature-specific), Divio types to include, target audience, and documentation goals"
+  plan:
+    prompt: "Design documentation structure, configure generators (JSDoc/Sphinx/rustdoc), plan gap-filling strategy if iterating"
+  tasks:
+    prompt: "Break documentation work into packages: template creation, generator setup, content authoring, quality validation"
+  implement:
+    prompt: "Generate documentation from templates, invoke generators for reference docs, populate templates with project-specific content"
+  review:
+    prompt: "Validate Divio type adherence, check accessibility guidelines, verify generator output quality, assess completeness"
+  accept:
+    prompt: "Validate documentation completeness, quality gates, and readiness for publication"

specify_cli/missions/documentation/templates/divio/explanation-template.md

@@ -0,0 +1,192 @@
+---
+type: explanation
+divio_category: understanding-oriented
+target_audience: curious-users
+purpose: conceptual-clarification
+outcome: user-understands-why-and-how
+---
+
+# Explanation: {CONCEPT_OR_TOPIC}
+
+> **Divio Type**: Explanation (Understanding-Oriented)
+> **Target Audience**: Users who want to understand concepts and context
+> **Purpose**: Clarify and illuminate to deepen understanding
+> **Outcome**: User understands why things are the way they are
+
+## Overview
+
+{Introduce the concept/topic and why understanding it matters}
+
+This explanation covers:
+- {Key aspect 1 that will be discussed}
+- {Key aspect 2 that will be discussed}
+- {Key aspect 3 that will be discussed}
+
+## Background and Context
+
+{Provide historical context or background that helps frame the discussion}
+
+**Why this matters**: {Explain relevance to users}
+
+{Add diagram if it helps explain the concept}
+
+![{Descriptive alt text}]({path-to-diagram})
+
+## Core Concepts
+
+### {Concept 1}
+
+{Explain the concept in depth}
+
+**Analogy**: {Use an analogy if it helps understanding}
+
+**Why it works this way**: {Explain the reasoning}
+
+**Implications**:
+- {What this means for users}
+- {How this affects behavior}
+- {What to keep in mind}
+
+### {Concept 2}
+
+{Explain the next concept}
+
+**Connection to {Concept 1}**: {How concepts relate}
+
+### {Concept 3}
+
+{Continue explaining key concepts}
+
+## How It Works
+
+{Explain the mechanism or process in detail}
+
+**Step-by-step explanation**:
+
+1. **{Phase 1}**: {What happens and why}
+2. **{Phase 2}**: {What happens next and why}
+3. **{Phase 3}**: {Continue the explanation}
+
+{Use diagrams, flowcharts, or illustrations to clarify}
+
+## Design Decisions
+
+### Why {Decision/Approach} Was Chosen
+
+**The problem**: {What needed to be solved}
+
+**Considered alternatives**:
+- **Option A**: {Description}
+  - Pros: {Benefits}
+  - Cons: {Drawbacks}
+- **Option B**: {Description}
+  - Pros: {Benefits}
+  - Cons: {Drawbacks}
+- **Chosen: Option C**: {Description}
+  - Why this was chosen: {Reasoning}
+  - Trade-offs accepted: {What was sacrificed for the benefits}
+
+## Common Misconceptions
+
+### Misconception: "{Common wrong belief}"
+
+**Reality**: {What's actually true}
+
+**Why the confusion**: {Why people think this}
+
+**Clarification**: {Detailed explanation of the truth}
+
+### Misconception: "{Another common wrong belief}"
+
+**Reality**: {What's actually true}
+
+**Example to illustrate**: {Concrete example that clarifies}
+
+## Relationships and Connections
+
+### Connection to {Related Concept}
+
+{Explain how this concept relates to another}
+
+**Differences**:
+- {Key difference 1}
+- {Key difference 2}
+
+**Similarities**:
+- {Key similarity 1}
+- {Key similarity 2}
+
+### Impact on {Related System/Feature}
+
+{Explain how this concept affects other parts of the system}
+
+## Trade-offs and Limitations
+
+**Benefits of this approach**:
+- {Benefit 1}
+- {Benefit 2}
+- {Benefit 3}
+
+**Limitations**:
+- {Limitation 1 and why it exists}
+- {Limitation 2 and why it exists}
+
+**When this might not be ideal**: {Scenarios where trade-offs are problematic}
+
+## Practical Implications
+
+### For {User Type 1}
+
+{What this concept means for this type of user}
+
+**Key takeaways**:
+- {Actionable insight 1}
+- {Actionable insight 2}
+
+### For {User Type 2}
+
+{What this concept means for this type of user}
+
+## Further Reading
+
+- **Tutorial**: Learn by doing with [Tutorial: {Topic}](../tutorials/{link})
+- **How-To**: Apply this in practice with [How-To: {Task}](../how-to/{link})
+- **Reference**: Technical details in [{Reference}](../reference/{link})
+- **External**: [Article/Book about {Topic}]({external-link})
+
+---
+
+## Write the Docs Best Practices (Remove this section before publishing)
+
+**Explanation Principles**:
+- ✅ Understanding-oriented: Clarify and illuminate
+- ✅ Discuss concepts, not tasks (not instructional)
+- ✅ Provide context and background
+- ✅ Explain "why" things are the way they are
+- ✅ Discuss alternatives and trade-offs
+- ✅ Make connections between ideas
+- ✅ Can be more free-form than other types
+- ✅ No imperative mood (not "do this")
+
+**Accessibility**:
+- ✅ Proper heading hierarchy
+- ✅ Alt text for diagrams (especially important for conceptual diagrams)
+- ✅ Clear language, define technical terms
+- ✅ Use diagrams to clarify complex concepts
+- ✅ Descriptive link text
+
+**Inclusivity**:
+- ✅ Diverse examples
+- ✅ Gender-neutral language
+- ✅ No cultural assumptions
+- ✅ Consider different learning styles (visual, verbal, etc.)
+
+**Explanation-Specific Guidelines**:
+- Start with "why" before "what"
+- Use analogies and metaphors to clarify
+- Diagrams are very valuable for explanations
+- Discuss design decisions and trade-offs
+- Address common misconceptions
+- Make connections to related concepts
+- Don't just describe - explain and clarify
+- Be conversational but accurate

specify_cli/missions/documentation/templates/divio/howto-template.md

@@ -0,0 +1,168 @@
+---
+type: how-to
+divio_category: goal-oriented
+target_audience: experienced-users
+purpose: problem-solving-guide
+outcome: user-solves-specific-problem
+---
+
+# How-To: {TASK_TO_ACCOMPLISH}
+
+> **Divio Type**: How-To Guide (Goal-Oriented)
+> **Target Audience**: Users with basic familiarity who need to solve a specific problem
+> **Purpose**: Provide practical steps to accomplish a specific goal
+> **Outcome**: User successfully completes the task
+
+## Goal
+
+This guide shows you how to {accomplish specific task}.
+
+**Use this guide when you need to**: {Describe the problem/goal this solves}
+
+## Prerequisites
+
+- {Required knowledge - assume user has basic familiarity}
+- {Required setup or configuration}
+- {Required tools or access}
+
+## Quick Summary
+
+If you're experienced, here's the short version:
+
+```bash
+# Step 1: {Brief description}
+{command}
+
+# Step 2: {Brief description}
+{command}
+
+# Step 3: {Brief description}
+{command}
+```
+
+## Detailed Steps
+
+### 1. {First Major Step}
+
+{Brief context for why this step is needed}
+
+```{language}
+{code-or-command}
+```
+
+**Options**:
+- `--option1`: {When to use this}
+- `--option2`: {When to use this}
+
+**Common variations**:
+- **If you need {variation}**: Use `{alternative command}`
+- **If you're using {different setup}**: Modify the command to `{modified version}`
+
+### 2. {Second Major Step}
+
+{Brief context}
+
+```{language}
+{code-or-command}
+```
+
+**Important**: {Critical thing to watch out for}
+
+### 3. {Third Major Step}
+
+{Brief context}
+
+```{language}
+{code-or-command}
+```
+
+### 4. {Continue as needed...}
+
+## Verification
+
+To confirm it worked:
+
+```bash
+{command-to-verify}
+```
+
+You should see:
+```
+{expected-output}
+```
+
+## Troubleshooting
+
+### Issue: {Common problem}
+
+**Symptoms**:
+- {What user sees}
+- {Error message or behavior}
+
+**Cause**: {Why this happens}
+
+**Solution**:
+```bash
+{fix-command}
+```
+
+### Issue: {Another common problem}
+
+**Symptoms**: {What user sees}
+
+**Solution**: {Steps to fix}
+
+## Alternative Approaches
+
+**Method 1** (described above): Best when {scenario}
+
+**Method 2**: If you need {different requirement}, use this instead:
+```bash
+{alternative-approach}
+```
+
+**Method 3**: For {specific use case}:
+```bash
+{another-approach}
+```
+
+## Related Resources
+
+- **Tutorial**: New to this? Start with [Tutorial: {Topic}](../tutorials/{link})
+- **Reference**: See [{API/CLI Reference}](../reference/{link}) for all options
+- **Explanation**: Understand why this works in [Explanation: {Topic}](../explanation/{link})
+
+---
+
+## Write the Docs Best Practices (Remove this section before publishing)
+
+**How-To Principles**:
+- ✅ Goal-oriented: Solve a specific problem
+- ✅ Assume reader has basic knowledge (not for beginners)
+- ✅ Focus on practical steps, minimal theory
+- ✅ Flexible: Reader can adapt to their situation
+- ✅ Provide options and alternatives for different scenarios
+- ✅ Include troubleshooting for common issues
+- ✅ Link to Reference for details, Explanation for "why"
+- ✅ Use imperative mood ("Do this", not "You might want to")
+
+**Accessibility**:
+- ✅ Proper heading hierarchy
+- ✅ Alt text for all images
+- ✅ Clear, plain language
+- ✅ Syntax highlighting for code blocks
+- ✅ Descriptive link text
+
+**Inclusivity**:
+- ✅ Diverse examples
+- ✅ Gender-neutral language
+- ✅ No cultural assumptions
+
+**How-To Specific Guidelines**:
+- Start with the goal (what will be accomplished)
+- Provide quick summary for experienced users
+- Offer options and variations (real-world scenarios vary)
+- Include verification step (how to know it worked)
+- Troubleshoot common problems
+- Don't explain concepts - link to Explanations
+- Assume familiarity - not a tutorial