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

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

@@ -0,0 +1,309 @@
+---
+description: Implement documentation work packages using Divio templates and generators.
+---
+
+# Command Template: /spec-kitty.implement (Documentation Mission)
+
+**Phase**: Generate
+**Purpose**: Create documentation from templates, invoke generators for reference docs, populate templates with content.
+
+## ⚠️ CRITICAL: Working Directory Requirement
+
+**After running `spec-kitty implement WP##`, you MUST:**
+
+1. **Run the cd command shown in the output** - e.g., `cd .worktrees/###-feature-WP##/`
+2. **ALL file operations happen in this directory** - Read, Write, Edit tools must target files in the workspace
+3. **NEVER write deliverable files to the main repository** - This is a critical workflow error
+
+**Why this matters:**
+- Each WP has an isolated worktree with its own branch
+- Changes in main repository will NOT be seen by reviewers looking at the WP worktree
+- Writing to main instead of the workspace causes review failures and merge conflicts
+
+**Verify you're in the right directory:**
+```bash
+pwd
+# Should show: /path/to/repo/.worktrees/###-feature-WP##/
+```
+
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Implementation Workflow
+
+Documentation implementation follows the standard workspace-per-WP model:
+- **Worktrees used** - Each WP has its own worktree with dedicated branch (same as code missions)
+- **Templates populated** - Use Divio templates as starting point
+- **Generators invoked** - Run JSDoc/Sphinx/rustdoc to create API reference
+- **Content authored** - Write tutorial/how-to/explanation content in worktree
+- **Quality validated** - Check accessibility, links, build before merging
+- **Release prepared (optional)** - Draft `release.md` when publish is in scope
+
+---
+
+## Per-Work-Package Implementation
+
+### For WP01: Structure & Generator Setup
+
+**Objective**: Create directory structure and configure doc generators.
+
+**Steps**:
+1. Create docs/ directory structure:
+   ```bash
+   mkdir -p docs/{tutorials,how-to,reference/api,explanation}
+   ```
+2. Create index.md landing page:
+   ```markdown
+   # {Project Name} Documentation
+
+   Welcome to the documentation for {Project Name}.
+
+   ## Getting Started
+
+   - [Tutorials](tutorials/) - Learn by doing
+   - [How-To Guides](how-to/) - Solve specific problems
+   - [Reference](reference/) - Technical specifications
+   - [Explanation](explanation/) - Understand concepts
+   ```
+3. Configure generators (per plan.md):
+   - For Sphinx: Create docs/conf.py from template
+   - For JSDoc: Create jsdoc.json from template
+   - For rustdoc: Update Cargo.toml with metadata
+4. Create build script:
+   ```bash
+   #!/bin/bash
+   # build-docs.sh
+
+   # Build Python docs with Sphinx
+   sphinx-build -b html docs/ docs/_build/html/
+
+   # Build JavaScript docs with JSDoc
+   npx jsdoc -c jsdoc.json
+
+   # Build Rust docs
+   cargo doc --no-deps
+
+   echo "Documentation built successfully!"
+   ```
+5. Test build: Run build script, verify no errors
+
+**Deliverables**:
+- docs/ directory structure
+- index.md landing page
+- Generator configs (conf.py, jsdoc.json, Cargo.toml)
+- build-docs.sh script
+- Successful test build
+
+---
+
+### For WP02-05: Content Creation (Tutorials, How-Tos, Reference, Explanation)
+
+**Objective**: Write documentation content using Divio templates.
+
+**Steps**:
+1. **Select appropriate Divio template**:
+   - Tutorial: Use `templates/divio/tutorial-template.md`
+   - How-To: Use `templates/divio/howto-template.md`
+   - Reference: Use `templates/divio/reference-template.md` (for manual reference)
+   - Explanation: Use `templates/divio/explanation-template.md`
+
+2. **Copy template to docs/**:
+   ```bash
+   # Example for tutorial
+   cp templates/divio/tutorial-template.md docs/tutorials/getting-started.md
+   ```
+
+3. **Fill in frontmatter**:
+   ```yaml
+   ---
+   type: tutorial
+   audience: "beginners"
+   purpose: "Learn how to get started with {Project}"
+   created: "2026-01-12"
+   estimated_time: "15 minutes"
+   prerequisites: "Python 3.11+, pip"
+   ---
+   ```
+
+4. **Replace placeholders with content**:
+   - {Title} → Actual title
+   - [Description] → Actual description
+   - [Step actions] → Actual step-by-step instructions
+   - [Examples] → Real code examples
+
+5. **Follow Divio principles for this type**:
+   - **Tutorial**: Learning-oriented, step-by-step, show results at each step
+   - **How-To**: Goal-oriented, assume experience, solve specific problem
+   - **Reference**: Information-oriented, complete, consistent format
+   - **Explanation**: Understanding-oriented, conceptual, discuss alternatives
+
+6. **Add real examples and content**:
+   - Use actual project APIs, not placeholders
+   - Test all code examples (they must work!)
+   - Add real screenshots (with alt text)
+   - Use diverse example names (not just "John")
+
+7. **Validate against checklists**:
+   - Divio compliance (correct type characteristics?)
+   - Accessibility (heading hierarchy, alt text, clear language?)
+   - Inclusivity (diverse examples, neutral language?)
+
+**For Reference Documentation**:
+
+**Auto-Generated Reference** (API docs):
+1. Ensure code has good doc comments:
+   - Python: Docstrings with Google/NumPy format
+   - JavaScript: JSDoc comments with @param, @returns
+   - Rust: /// doc comments
+2. Run generator:
+   ```bash
+   # Sphinx (Python)
+   sphinx-build -b html docs/ docs/_build/html/
+
+   # JSDoc (JavaScript)
+   npx jsdoc -c jsdoc.json
+
+   # rustdoc (Rust)
+   cargo doc --no-deps --document-private-items
+   ```
+3. Review generated output:
+   - Are all public APIs present?
+   - Are descriptions clear?
+   - Are examples included?
+   - Are links working?
+4. If generated docs have gaps:
+   - Add/improve doc comments in source code
+   - Regenerate
+   - Or supplement with manual reference
+
+**Manual Reference** (CLI, config, data formats):
+1. Use reference template
+2. Document every option, every command, every field
+3. Be consistent in format (use tables)
+4. Include examples for each item
+
+**Deliverables**:
+- Completed documentation files in docs/
+- All templates filled with real content
+- All code examples tested and working
+- All Divio type principles followed
+- All accessibility/inclusivity checklists satisfied
+
+---
+
+### For WP06: Quality Validation
+
+**Objective**: Validate documentation quality before considering complete.
+
+**Steps**:
+1. **Automated checks**:
+   ```bash
+   # Check heading hierarchy
+   find docs/ -name "*.md" -exec grep -E '^#+' {} + | head -50
+
+   # Check for broken links
+   markdown-link-check docs/**/*.md
+
+   # Check for missing alt text
+   grep -r '!\[.*\](' docs/ | grep -v '\[.*\]' || echo "✓ All images have alt text"
+
+   # Spell check
+   aspell check docs/**/*.md
+
+   # Build check
+   ./build-docs.sh 2>&1 | grep -i error || echo "✓ Build successful"
+   ```
+
+2. **Manual checks**:
+   - Read each doc as target audience
+   - Follow tutorials - do they work?
+   - Try how-tos - do they solve problems?
+   - Check reference - is it complete?
+   - Read explanations - do they clarify?
+
+3. **Divio compliance check**:
+   - Is each doc correctly classified?
+   - Does it follow principles for its type?
+   - Is it solving the right problem for that type?
+
+4. **Accessibility check**:
+   - Proper heading hierarchy?
+   - All images have alt text?
+   - Clear language (not jargon-heavy)?
+   - Links are descriptive?
+
+5. **Peer review**:
+   - Have someone from target audience review
+   - Gather feedback on clarity, completeness, usability
+   - Revise based on feedback
+
+6. **Final build and deploy** (if applicable):
+   ```bash
+   # Build final documentation
+   ./build-docs.sh
+
+   # Deploy to hosting (example for GitHub Pages)
+   # (Deployment steps depend on hosting platform)
+   ```
+
+**Deliverables**:
+- All automated checks passing
+- Manual review completed with feedback addressed
+- Divio compliance verified
+- Accessibility compliance verified
+- Final build successful
+- Documentation deployed (if applicable)
+
+---
+
+## Key Guidelines
+
+**For Agents**:
+- Use Divio templates as starting point, not empty files
+- Fill templates with real content, not more placeholders
+- Test all code examples before committing
+- Follow Divio principles strictly for each type
+- Run generators for reference docs (don't write API docs manually)
+- Validate quality at end (automated + manual checks)
+
+**For Users**:
+- Implementation creates actual documentation, not just structure
+- Templates provide guidance, you provide content
+- Generators handle API reference, you write the rest
+- Quality validation ensures documentation is actually useful
+- Peer review from target audience is valuable
+
+---
+
+## Common Pitfalls
+
+**DON'T**:
+- Mix Divio types (tutorial that explains concepts, how-to that teaches basics)
+- Skip testing code examples (broken examples break trust)
+- Use only Western male names in examples
+- Say "simply" or "just" or "obviously" (ableist language)
+- Skip alt text for images (accessibility barrier)
+- Write jargon-heavy prose (clarity issue)
+- Commit before validating (quality issue)
+
+**DO**:
+- Follow Divio principles for each type
+- Test every code example
+- Use diverse names in examples
+- Use welcoming, clear language
+- Add descriptive alt text
+- Define technical terms
+- Validate before considering complete
+
+---
+
+## Status Tracking Note
+
+If `/spec-kitty.status` shows your WP in "doing" after you moved it to "for_review", don't panic - a reviewer may have moved it back (changes requested), or there's a sync delay. Focus on your WP.

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

@@ -0,0 +1,275 @@
+---
+description: Produce a documentation mission plan with audit/design guidance and generator setup.
+---
+
+# Command Template: /spec-kitty.plan (Documentation Mission)
+
+**Phases**: Audit (if gap-filling), Design
+**Purpose**: Plan documentation structure, configure generators, prioritize gaps, design content outline.
+
+## 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). Planning happens in main for ALL missions.
+
+```bash
+git branch --show-current  # Should show "main"
+```
+
+**Note**: Planning in main is standard for all spec-kitty missions. Implementation happens in per-WP worktrees.
+
+---
+
+## Planning Interrogation
+
+For documentation missions, planning interrogation is lighter than software-dev:
+- **Simple projects** (single language, initial docs): 1-2 questions about structure preferences
+- **Complex projects** (multiple languages, existing docs): 2-3 questions about integration approach
+
+**Key Planning Questions**:
+
+**Q1: Documentation Framework**
+"Do you have a preferred documentation framework/generator?"
+- Sphinx (Python ecosystem standard)
+- MkDocs (Markdown-focused, simple)
+- Docusaurus (React-based, modern)
+- Jekyll (GitHub Pages native)
+- None (plain Markdown)
+
+**Why it matters**: Determines build system, theming options, hosting compatibility.
+
+**Q2: Generator Integration Approach** (if multiple languages detected)
+"How should API reference for different languages be organized?"
+- Unified (all APIs in one reference section)
+- Separated (language-specific reference sections)
+- Parallel (side-by-side comparison)
+
+**Why it matters**: Affects directory structure, navigation design.
+
+---
+
+## Outline
+
+1. **Setup**: Run `spec-kitty agent feature setup-plan --json` to initialize plan.md
+
+2. **Load context**: Read spec.md, meta.json (especially `documentation_state`)
+
+3. **Phase 0: Research** (if gap-filling mode)
+
+   ### Gap Analysis (gap-filling mode only)
+
+   **Objective**: Audit existing documentation and identify gaps.
+
+   **Steps**:
+   1. Scan existing `docs/` directory (or wherever docs live)
+   2. Detect documentation framework (Sphinx, MkDocs, Jekyll, etc.)
+   3. For each markdown file:
+      - Parse frontmatter for `type` field
+      - Apply content heuristics if no explicit type
+      - Classify as tutorial/how-to/reference/explanation or "unclassified"
+   4. Build coverage matrix:
+      - Rows: Project areas/features
+      - Columns: Divio types (tutorial, how-to, reference, explanation)
+      - Cells: Documentation files (or empty if missing)
+   5. Calculate coverage percentage
+   6. Prioritize gaps:
+      - **High**: Missing tutorials (blocks new users)
+      - **High**: Missing reference for public APIs
+      - **Medium**: Missing how-tos for common tasks
+      - **Low**: Missing explanations (nice-to-have)
+   7. Generate `gap-analysis.md` with:
+      - Current documentation inventory
+      - Coverage matrix (markdown table)
+      - Prioritized gap list
+      - Recommendations
+
+   **Output**: `gap-analysis.md` file in feature directory
+
+   ---
+
+   ### Generator Research (all modes)
+
+   **Objective**: Research generator configuration options for detected languages.
+
+   **For Each Detected Language**:
+
+   **JavaScript/TypeScript → JSDoc/TypeDoc**:
+   - Check if JSDoc installed: `npx jsdoc --version`
+   - Research config options: output format (HTML/Markdown), template (docdash, clean-jsdoc)
+   - Determine source directories to document
+   - Plan integration with manual docs
+
+   **Python → Sphinx**:
+   - Check if Sphinx installed: `sphinx-build --version`
+   - Research extensions: autodoc (API from docstrings), napoleon (Google/NumPy style), viewcode (source links)
+   - Research theme: sphinx_rtd_theme (Read the Docs), alabaster (default), pydata-sphinx-theme
+   - Plan autodoc configuration (which modules to document)
+   - Plan integration with manual docs
+
+   **Rust → rustdoc**:
+   - Check if Cargo installed: `cargo doc --help`
+   - Research rustdoc options: --no-deps, --document-private-items
+   - Plan Cargo.toml metadata configuration
+   - Plan integration with manual docs (rustdoc outputs HTML, may need linking)
+
+   **Output**: research.md with generator findings and decisions
+
+4. **Phase 1: Design**
+
+   ### Documentation Structure Design
+
+   **Directory Layout**:
+   Design docs/ structure following Divio organization:
+
+   ```
+   docs/
+   ├── index.md                    # Landing page
+   ├── tutorials/                  # Learning-oriented
+   │   ├── getting-started.md
+   │   └── advanced-usage.md
+   ├── how-to/                     # Problem-solving
+   │   ├── authentication.md
+   │   ├── deployment.md
+   │   └── troubleshooting.md
+   ├── reference/                  # Technical specs
+   │   ├── api/                    # Generated API docs
+   │   │   ├── python/             # Sphinx output
+   │   │   ├── javascript/         # JSDoc output
+   │   │   └── rust/               # rustdoc output
+   │   ├── cli.md                  # Manual CLI reference
+   │   └── configuration.md        # Manual config reference
+   └── explanation/                # Understanding
+       ├── architecture.md
+       ├── concepts.md
+       └── design-decisions.md
+   ```
+
+   **Adapt based on**:
+   - Selected Divio types (only create directories for selected types)
+   - Project size (small projects may flatten structure)
+   - Existing docs (extend existing structure if gap-filling)
+
+   ---
+
+   ### Generator Configuration Design
+
+   **For Each Generator**:
+
+   **Sphinx (Python)**:
+   ```python
+   # docs/conf.py
+   project = '{project_name}'
+   author = '{author}'
+   extensions = [
+       'sphinx.ext.autodoc',      # Generate from docstrings
+       'sphinx.ext.napoleon',     # Google/NumPy docstring support
+       'sphinx.ext.viewcode',     # Link to source
+       'sphinx.ext.intersphinx',  # Link to other projects
+   ]
+   html_theme = 'sphinx_rtd_theme'
+   autodoc_default_options = {
+       'members': True,
+       'undoc-members': False,
+       'show-inheritance': True,
+   }
+   ```
+
+   **JSDoc (JavaScript)**:
+   ```json
+   {
+     "source": {
+       "include": ["src/"],
+       "includePattern": ".+\\.js$"
+     },
+     "opts": {
+       "destination": "docs/reference/api/javascript",
+       "template": "node_modules/docdash",
+       "recurse": true
+     }
+   }
+   ```
+
+   **rustdoc (Rust)**:
+   ```toml
+   [package.metadata.docs.rs]
+   all-features = true
+   rustdoc-args = ["--document-private-items"]
+   ```
+
+   **Output**: Generator config snippets in plan.md, templates ready for implementation
+
+   ---
+
+   ### Data Model
+
+   Generate `data-model.md` with entities:
+   - **Documentation Mission**: Iteration state, selected types, configured generators
+   - **Divio Documentation Type**: Tutorial, How-To, Reference, Explanation with characteristics
+   - **Documentation Generator**: JSDoc, Sphinx, rustdoc configurations
+   - **Gap Analysis** (if applicable): Coverage matrix, prioritized gaps
+
+   ---
+
+   ### Work Breakdown
+
+   Outline high-level work packages (detailed in `/spec-kitty.tasks`):
+
+   **For Initial Mode**:
+   1. WP01: Structure Setup - Create docs/ dirs, configure generators
+   2. WP02: Tutorial Creation - Write selected tutorials
+   3. WP03: How-To Creation - Write selected how-tos
+   4. WP04: Reference Generation - Generate API docs, write manual reference
+   5. WP05: Explanation Creation - Write selected explanations
+   6. WP06: Quality Validation - Accessibility checks, link validation, build
+
+   **For Gap-Filling Mode**:
+   1. WP01: Gap Analysis Review - Review audit results with user
+   2. WP02: High-Priority Gaps - Fill critical missing docs
+   3. WP03: Medium-Priority Gaps - Fill important missing docs
+   4. WP04: Generator Updates - Regenerate outdated API docs
+   5. WP05: Quality Validation - Validate new and updated docs
+
+   **For Feature-Specific Mode**:
+   1. WP01: Feature Documentation - Document the specific feature across Divio types
+   2. WP02: Integration - Integrate with existing documentation
+   3. WP03: Quality Validation - Validate feature docs
+
+   ---
+
+   ### Quickstart
+
+   Generate `quickstart.md` with:
+   - How to build documentation locally
+   - How to add new documentation (which template to use)
+   - How to regenerate API reference
+   - How to validate documentation quality
+
+5. **Report completion**:
+   - Plan file path
+   - Artifacts generated (research.md, data-model.md, gap-analysis.md, quickstart.md, release.md when publish is in scope)
+   - Next command: `/spec-kitty.tasks`
+
+---
+
+## Key Guidelines
+
+**For Agents**:
+- Run gap analysis only for gap-filling mode
+- Auto-detect documentation framework from existing docs
+- Configure generators based on detected languages
+- Design structure following Divio principles
+- Prioritize gaps by user impact (tutorials/reference high, explanations low)
+- Plan includes both auto-generated and manual documentation
+
+**For Users**:
+- Planning designs documentation structure, doesn't write content yet
+- Generator configs enable automated API reference
+- Gap analysis (if iterating) shows what needs attention
+- Work breakdown will be detailed in `/spec-kitty.tasks`