Designed to be called:

Standalone: /init-project-docs
After /init-project: as the final doc generation step
With --update: refresh existing docs with latest Linear/roadmap state

README.md — The project's front door. Contains:

Project name and description
Tech stack table (auto-detected from package.json)
Prerequisites and setup (onboarding)
Available commands (from package.json scripts)
Git workflow and branching strategy
AI tools & integrations (MCPs, skills, GSD)
Project status (roadmap, Linear issues, design resources)
Changelog link
Deployment info
Team table with git/Linear handles

CHANGELOG.md — Keep a Changelog format, initialized with [Unreleased] section.

Both files follow a consistent structure across all Khaeli projects.

1. Detect Project Context

Gather all available context without asking the user:

# Package info
cat package.json 2>/dev/null

# Git remote
git remote -v 2>/dev/null

# Git user
git config user.name 2>/dev/null
git config user.email 2>/dev/null

# Team members (from git remote — GitLab or GitHub)
# GitLab:
glab api "projects/$(git remote get-url origin 2>/dev/null | sed 's|.*:|/|;s|\.git$||;s|/|%2F|g')/members/all" 2>/dev/null

# Planning docs
ls .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md 2>/dev/null

# CLAUDE.md
cat CLAUDE.md 2>/dev/null | head -5

# Existing README
cat README.md 2>/dev/null

# Linear project (if .linear-project exists or CLAUDE.md references one)
cat .linear-project 2>/dev/null

2. Detect Tech Stack

Parse package.json to build the tech stack table:

For each dependency and devDependency:
  - next → Next.js (with version)
  - react → React (with version)
  - tailwindcss → Tailwind CSS (with version)
  - typescript → TypeScript (with version)
  - @biomejs/biome → Biome (with version)
  - eslint → ESLint (with version)
  - prettier → Prettier (with version)
  - vite → Vite (with version)
  - nuxt → Nuxt (with version)
  - vue → Vue (with version)
  - svelte → Svelte (with version)
  - astro → Astro (with version)

Detect package manager from lockfile:
  - bun.lock → bun
  - pnpm-lock.yaml → pnpm
  - yarn.lock → yarn
  - package-lock.json → npm

3. Detect Available Commands

Parse package.json scripts to list available commands:

For each script in package.json.scripts:
  Map to purpose:
  - dev → Start dev server
  - build → Production build
  - start → Start production server
  - lint → Lint code
  - format → Format code
  - test → Run tests
  - type-check / typecheck → Type checking

4. Detect Git Platform & Team

From git remote URL, determine platform:

gitlab.com → GitLab (use glab for team members)
github.com → GitHub (use gh for team members)

Fetch team members with appropriate CLI. Build team table with:

Name
Role (infer from access level: 50=Maintainer/Lead, 40=Developer, 30=Developer, 20=Reporter)
Platform handle
Linear handle (if CLAUDE.md has known engineers section)

5. Detect Linear Integration

If Linear MCP is available, fetch:

Project name, description, status, milestones
Active issues with assignees and status

If .linear-project or CLAUDE.md references a Linear project, use that.

6. Detect Roadmap

If .planning/ROADMAP.md exists, parse it for:

Phase list with goals, status, and requirements
Current phase

7. Detect Design Resources

Check for references to design tools in:

Linear project resources (links)
CLAUDE.md
.planning/PROJECT.md

Common patterns: Figma URLs, Canva links, Notion links.

8. Ask Clarifying Questions (if needed)

Only ask if critical info is missing and can't be inferred:

AskUserQuestion([
  {
    header: "Description",
    question: "One-line project description?",
    multiSelect: false,
    options: [
      { label: "{inferred from package.json or Linear}", description: "Auto-detected" },
      { label: "Custom", description: "I'll type my own" }
    ]
  },
  {
    header: "Deployment",
    question: "Where is this deployed?",
    multiSelect: false,
    options: [
      { label: "Vercel", description: "Preview deploys per PR" },
      { label: "Netlify", description: "Preview deploys per PR" },
      { label: "Self-hosted", description: "Custom deployment" },
      { label: "Not yet", description: "Skip deployment section" }
    ]
  }
])

Skip questions where context is already clear.

9. Generate README.md

Use this template structure, filling in detected values. Omit sections where data is unavailable.

# {Project Name}

{One-line description from Linear project or package.json}

## Tech Stack

| Tool | Version | Purpose |
|------|---------|---------|
{For each detected dependency, sorted by importance}

## Getting Started

### Prerequisites

| Tool | Install | Verify |
|------|---------|--------|
| [{pkg_manager}]({url}) | `{install_cmd}` | `{pkg_manager} --version` |
| [Node.js](https://nodejs.org) 20+ | via {pkg_manager} or nvm | `node --version` |
{If GitLab: | [glab](https://gitlab.com/gitlab-org/cli) | `brew install glab` | `glab auth status` |}
{If GitHub: | [gh](https://cli.github.com) | `brew install gh` | `gh auth status` |}
| [Claude Code](https://claude.com/claude-code) | `npm i -g @anthropic-ai/claude-code` | `claude --version` |

### Setup

```bash
# 1. Clone the repo
git clone {remote_url}
cd {dir_name}

# 2. Install dependencies
{pkg_manager} install

# 3. Verify your git identity (required for Claude Code engineer detection)
git config user.name
git config user.email

# 4. Start dev server
{pkg_manager} run dev

{If dev URL detectable: Open http://localhost:3000 to view.}

Available Commands

{For each detected script: {pkg_manager} run {name}  # {purpose}}

Claude Code Setup

{Standard Claude Code onboarding paragraph pointing to CLAUDE.md}

Project Structure

{Detect top-level directories and key files, describe each}

Git Workflow

{If CLAUDE.md has git workflow section, use that. Otherwise generate standard trunk-based workflow.}

AI Tools & Integrations

{If CLAUDE.md has MCP/skills sections, extract and present.}

Project Status

Roadmap

{If ROADMAP.md exists, render phase table.}

Linear Issues

{If Linear MCP available, render active issues table.}

Design Resources

{If design links found, list them.}

Changelog

See CHANGELOG.md for a detailed history of changes.

Deployment

{Based on detected platform or user answer.}

Team

Name	Role	{Platform}	Linear
{For each team member detected}


## 10. Generate CHANGELOG.md

```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Project scaffolded with {framework} {version}{, other key deps}
{If linter: - {linter} {version} for linting and formatting}
{If planning: - GSD planning framework initialized}
{If CLAUDE.md: - Project documentation and collaboration guidelines}
- README.md with onboarding, project status, and team info
- CHANGELOG.md initialized

11. Handle --update Flag

If --update is passed in arguments and README.md already exists:

Re-detect all context (steps 1-7)
Read existing README.md
Update ONLY these sections (preserve everything else):
- Tech Stack table (re-detect from package.json)
- Project Status > Roadmap (re-read ROADMAP.md)
- Project Status > Linear Issues (re-fetch from Linear)
- Team table (re-fetch from git platform)
Do NOT regenerate Getting Started, Git Workflow, etc. unless they don't exist
Append new CHANGELOG entries under [Unreleased] if changes detected

12. Commit

git add README.md CHANGELOG.md
git commit -m "docs: {initialize|update} README and CHANGELOG"

<success_criteria>

init-project-docs