project-docs

name: project-docs metadata: compatible_agents: [claude-code] tags: [documentation, sdlc, laravel, php, markdown, badges, release-notes] description: > Full SDLC documentation toolchain for software projects — pre-development through post-release. Scaffolds numbered folder structures, generates Product Specs via interview, creates versioned roadmaps (Markdown table + Mermaid Gantt + GitHub Milestones + phase-based), builds support clusters (FAQ, triage workflow, SLA, post-mortem, deprecation), validates documentation, generates health reports with SDLC coverage scoring, and creates release notes from git logs. Use this skill whenever the user asks to create, scaffold, validate, or health-check project documentation — including: "set up docs for my Laravel package", "write a product spec", "generate a roadmap", "create an FAQ", "write a post-mortem", "generate a release note", "check my docs health", "add badges", "scaffold a support runbook", or "deprecate my package". Compatible with the nasrulhazim/claude-docs Claude Code slash command.

Claude Docs — Full SDLC Documentation Toolchain

Covers the complete software development lifecycle: Pre → During → Post. All outputs use the numbered folder structure compatible with /docs Claude Code slash command.

Command Reference

SDLC Folder Structure

docs/
├── README.md                         ← Master index
├── 00-product/                       ← Pre: spec, PRD, roadmap
│   ├── README.md
│   ├── 01-product-spec.md
│   ├── 02-requirements.md
│   ├── 03-roadmap.md
│   ├── 04-srs.md
│   └── 05-user-stories.md
├── 01-architecture/                  ← Pre/During: design, ADRs
│   ├── README.md
│   ├── 01-overview.md
│   ├── 02-patterns.md
│   ├── 03-data-layer.md
│   └── adr/
│       └── 0001-record-architecture-decisions.md
├── 02-development/                   ← During: setup, workflows, testing
│   ├── README.md
│   ├── 01-getting-started.md
│   ├── 02-workflows.md
│   ├── 03-testing.md
│   └── 04-livewire-components.md
├── 03-deployment/                    ← Post: deploy, ops runbook
│   ├── README.md
│   ├── 01-overview.md
│   ├── 02-runbook.md
│   └── 03-ci-cd.md
├── 04-api/                           ← During/Post: contracts
│   ├── README.md
│   └── 01-endpoints.md
└── 05-support/                       ← Post: FAQ, triage, SLA, post-mortem
    ├── README.md
    ├── 01-faq.md
    ├── 02-support-workflow.md
    ├── 03-sla.md
    ├── 04-post-mortem-template.md
    └── 05-deprecation.md

Phase Filtering for Scaffold

1. Scaffold New Documentation

Step 1: Auto-Detect Project Type

If ambiguous, ask: "What type of project is this?"

Step 2: Read Reference Files

• references/scaffolds.md — file contents per project type (during-phase dev docs)
• references/sdlc-templates.md — pre and post phase document templates

Livewire projects: For laravel-livewire type projects, also scaffold Livewire component documentation in 02-development/:

• 04-livewire-components.md — Component inventory, props, events, patterns

Step 3: Generate Files

Apply Linting Rules to every file. Present grouped by phase. Always include root README.md with mandatory badges — see references/badges.md.

2. /docs spec — Product Specification (Interview Mode)

Interview Phase

Ask questions in three blocks, one at a time:

Block 1 — Core Identity

• What is the product/feature name?
• What problem does it solve? (one sentence)
• Who is the target user? (be specific)

Block 2 — Scope

• What are the 3–5 key features in scope for this version?
• What is explicitly out of scope?
• What are the hard constraints? (tech stack, deadline, budget, compliance)

Block 3 — Success

• How will you know it's working? (metrics, KPIs)
• What does the minimum viable version look like?
• Are there any existing systems this must integrate with?

After Block 3, confirm: "Here's what I've captured — shall I generate the spec?"

Generate

Read references/sdlc-templates.md → Product Specification section. Populate every field from interview answers. Mark genuinely unknown fields as > ⚠️ TBD — needs decision rather than leaving blank.

Output: docs/00-product/01-product-spec.md

Requirement Design Phase Integration

For full Software Requirements Specification (SRS) and user story generation, this skill delegates to the project-requirements skill:

• /docs srs — Invokes project-requirements to generate a complete SRS document. Output: docs/00-product/04-srs.md
• /docs stories — Invokes project-requirements to generate user stories with acceptance criteria. Output: docs/00-product/05-user-stories.md

If the project-requirements skill is not available, prompt the user to install it or provide requirements manually for inclusion in the product spec.

3. /docs roadmap — Versioned Roadmap

Ask the user for: version targets, milestone names, dates or quarters, features per version. If no dates given, use "Q1 2026", "Q2 2026" etc.

Generate all four formats in docs/00-product/03-roadmap.md. Read references/sdlc-templates.md → Roadmap section for the full template.

Format 1 — Markdown Version Table

Format 2 — Mermaid Gantt

gantt
  title Product Roadmap
  dateFormat YYYY-MM-DD
  section Alpha
    Core features :2026-01-01, 2026-02-28

Format 3 — GitHub Milestones JSON

Fenced block the user can paste into a GitHub Milestones import script:

[{ "title": "v0.1 Alpha", "description": "...", "due_on": "2026-02-28T00:00:00Z" }]

Format 4 — Phase Summary

Alpha (v0.1)  → Core features, internal testing
Beta (v0.2)   → External testing, feedback loop
GA (v1.0)     → Production-ready, full docs, SLA active

4. Reorganize, Validate, Update TOC

Reorganize

Map current files → numbered SDLC structure. Show mapping first, get confirmation, then generate.

Validate

Update TOC

Scan each folder's .md files in numbered order. Replace between <!-- TOC --> / <!-- /TOC --> markers, or insert after first ## heading.

5. /docs health — Health Report

Quality Score (60 pts)

SDLC Coverage Score (40 pts)

Output Format

Documentation Health Report — [Project Name]
============================================
Generated: [date]  |  Project Type: [type]

📊 Overall Score: 72/100

Quality (48/60)
  Folder Structure    ████████████░░   12/15
  Badge Compliance    ███████░░░        7/10
  Code Blocks         ██████████       10/10
  TOC                 ████████░░        8/10
  Line Length         █████████░        9/10
  Single H1           █████             5/5

SDLC Coverage (24/40)
  Pre-Dev / Product   ████████░░░░░░░   8/15  ← missing roadmap
  During / Dev        ██████████       10/10
  Post / Support      ██████░░░░░░░░░   6/15  ← missing SLA + post-mortem

Issues Found:
  ❌ [HIGH]  05-support/ missing — run /docs support
  ⚠️  [MED]   00-product/03-roadmap.md missing — run /docs roadmap
  ⚠️  [MED]   No license badge in root README.md
  ℹ️  [LOW]   4 files exceed 120-char line limit

Recommendations:
  1. /docs support    → scaffold full support cluster
  2. /docs roadmap    → generate versioned roadmap
  3. Add badge: [![License](https://img.shields.io/github/license/ORG/REPO?style=flat-square)](LICENSE)

6. /docs support — Support Cluster

Generates five files under docs/05-support/. Read references/sdlc-templates.md → Support section for each template. Ask for project name and context before generating.

7. /docs runbook — Ops Runbook

Ask: project type, hosting environment, deployment method (manual / CI-CD / Docker / k8s). Read references/sdlc-templates.md → Runbook section. Output: docs/03-deployment/02-runbook.md

Sections generated: pre-deploy checklist, deploy steps (numbered, atomic), post-deploy verification, rollback procedure, emergency contacts.

8. Release Notes

User provides git log output (git log --oneline --since="X").

Full: version header, summary table, categorised commits, contributor list. --tldr: version, date, one-line per section, total count.

Linting Rules

Badge Standards

Mandatory on every root README.md:

[![Latest Version](https://img.shields.io/github/v/release/ORG/REPO?style=flat-square)](...)
[![License](https://img.shields.io/github/license/ORG/REPO?style=flat-square)](LICENSE)

Full templates and project type badge matrix → references/badges.md.

Reference Files