Project documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects — bootstrapping essential docs, naming and folder conventions, freshness, and cleanup of AI-generated junk and stale files. Use when starting a new project, setting up docs/ structure, auditing markdown files, cleanin

Project Documentation End to end documentation lifecycle for PHP/Laravel and Node/TypeScript/React projects. Contains 25 rules across 6 categories covering folder structure, naming conventions, essential files, content quality (including AI slop detection), cleanup of accumulated junk, and lifecycle. Supports bootstrap mode (set up docs in a new project), audit mode (find what's missing, stale, bloated, or junk), and reference mode (conventions lookup). Metadata Version: 1.0.0 Scope: PHP / Laravel + Node / TypeScript / React projects Rule Count: 25 rules across 6 categories License: MIT How to Use This Skill — Three Modes Mode 1: Bootstrap (new project / missing docs) When the user asks "set up docs", "what docs does this project need", or starts a new project — walk through the bootstrap steps: 1. Detect project type (Laravel? React? Both?) — composer.json , package.json , artisan binary 2. Inventory existing docs — list every .md file with its location and last modified date 3. Identify gaps — compare against the Essential Files checklist; report what's missing 4. Propose folder structure — docs/ with sub folders ( architecture/ , adr/ , guides/ , runbooks/ , archive/ ) based on project size 5. Offer to scaffold templates — README, CHANGELOG, LICENSE, CONTRIBUTING, SECURITY, ADR 0001 — generate with user approval, do not auto create 6. Suggest CI gates — markdown lint, broken link checker (lychee), CHANGELOG on PR enforcement Mode 2: Audit (existing project cleanup) When the user asks "audit docs", "clean up markdown", or "what should I delete" — produce a classified ledger. For each .md file in the repo: KEEP — file is essential and current UPDATE — file is essential but stale (e.g., README contradicts current setup) ARCHIVE — superseded but historically useful — move to docs/archive/<year / DELETE — AI generated plan files, empty stubs, duplicates, orphaned drafts MOVE — wrong location or wrong name (e.g., MyArchitectureNotes.md at root → docs/architecture/overview.md ) Output format: Never auto delete. Always surface for user approval first. Mode 3: Reference (conventions lookup) When the user asks "how should I name this", "where should this go", or references the skill in a code review context — look up the relevant rule(s) in rules/ . When to Apply Reference this skill when: Starting a new Laravel or Node/React project and need a docs baseline Onboarding a project with messy or AI cluttered markdown files Setting up docs/ folder structure Naming a new doc file Deciding whether to delete a PLAN.md / TODO.md / IMPLEMENTATION SUMMARY.md Adding CI checks for markdown quality Reviewing a PR that adds or modifies documentation Quarterly "docs hygiene" sweep Step 1: Detect Project Type Always check the project stack before recommending specifics. Bootstrap and naming guidance differ slightly per stack. Signal Project Type Notes composer.json + artisan Laravel (PHP) README should cover composer install , php artisan migrate , .env.example package.json (only) Node / TypeScript / React README should cover npm install , .nvmrc , build scripts Both present Laravel + Inertia + React README covers both PHP and Node setup paths The rules themselves are mostly stack agnostic — README format, ADR structure, naming conventions apply to any project. Rule Categories by Priority Priority Category Impact Prefix 1 Structure CRITICAL structure 2 Naming CRITICAL naming 3 Essential Files HIGH essential 4 Quality HIGH quality 5 Cleanup HIGH cleanup 6 Lifecycle MEDIUM lifecycle Quick Reference 1. Structure (CRITICAL) structure root files — Which files belong at the repo root (README, CHANGELOG, LICENSE, etc.) structure docs folder — docs/ as the home for everything beyond root files structure subfolders — Recommended docs/ layout: architecture/, adr/, guides/, runbooks/, archive/ 2. Naming (CRITICAL) naming root files — UPPERCASE.md for conventional root files naming docs files — kebab case.md for files under docs/ naming adr files — Numbered prefix: 0001 record architecture decisions.md naming anti patterns — No dates, no MyNotes.md , no tmp/draft/final markers 3. Essential Files (HIGH) essential readme — Every project needs a README with purpose, install, usage, license essential changelog — Keep a Changelog format; one entry per release essential license — LICENSE file (or LICENSE.md ) at repo root essential contributing — CONTRIBUTING.md when accepting external contributors essential security — SECURITY.md with vulnerability reporting policy 4. Quality (HIGH) quality conciseness — Cut bloat; length is a cost, not a virtue quality ai slop — Detect AI generated content patterns (filler, sign offs, generic praise) quality headings — One H1, no skipped levels, descriptive heading text quality code blocks — Language tags, copy pasteable commands, no untagged blocks quality links — Descriptive link text (not "click here"), relative paths, no broken links 5. Cleanup (HIGH) cleanup ai junk — Detect and remove AI generated plan/summary files cleanup duplicates — Same content in multiple files; consolidate or delete copies cleanup orphans — .md files not linked from anywhere; archive or delete cleanup empty stubs — Files with TBD / TODO / placeholder content only 6. Lifecycle (MEDIUM) lifecycle freshness — "Last verified" dates on architecture docs lifecycle archive — Superseded docs go to docs/archive/<year / lifecycle adr process — ADR creation triggers and lifecycle (proposed → accepted → superseded) lifecycle changelog discipline — Add a CHANGELOG entry in the same PR as the change Essential Patterns Standard folder layout File naming at a glance CI: keep markdown honest How to Use Read individual rule files for detailed conventions and examples: Each rule file contains: YAML frontmatter with metadata (title, impact, tags) Brief explanation of why it matters Incorrect example (anti pattern) Correct example (the convention) Detection / enforcement guidance where applicable References [Keep a Changelog](https://keepachangelog.com/) [Semantic Versioning](https://semver.org/) [Architecture Decision Records (ADR)](https://adr.github.io/) [Diátaxis — documentation framework](https://diataxis.fr/) [Choose a License](https://choosealicense.com/) [Markdownlint](https://github.com/DavidAnson/markdownlint) [Lychee — link checker](https://github.com/lycheeverse/lychee) Full Compiled Document For the complete guide with all rules expanded: AGENTS.md

project-docs