Shipflow Docs

Context

• Current directory: !pwd
• Project CLAUDE.md: !head -80 CLAUDE.md 2>/dev/null || echo "no CLAUDE.md"
• Package.json: !cat package.json 2>/dev/null | head -40 || echo "no package.json"
• Existing README: !head -20 README.md 2>/dev/null || echo "no README.md"
• Project structure: !find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.astro" -o -name "*.vue" -o -name "*.py" \) 2>/dev/null | grep -v node_modules | grep -v .git | grep -v dist | sort | head -40

Mode detection

• $ARGUMENTS is a file path → FILE MODE: document that specific file.
• $ARGUMENTS is "readme" → README MODE: generate or update README.md.
• $ARGUMENTS is "api" → API MODE: document all API endpoints.
• $ARGUMENTS is "components" → COMPONENTS MODE: document all UI components.
• $ARGUMENTS is empty → AUTO MODE: detect gaps and suggest what to document.

FILE MODE

Document a specific file with inline documentation.

Flow

1. Read the target file and all its imports (1 level deep).
2. Analyze: exports, functions, types, classes, side effects.
3. Add documentation:
   • TypeScript/JavaScript: JSDoc/TSDoc comments for exports
   • Python: docstrings (Google style)
   • Astro/Vue: component description comment at top
4. Don't document obvious code. Focus on:
   • Why, not what
   • Non-obvious parameters and return values
   • Edge cases and gotchas
   • Usage examples for public APIs

README MODE

Generate or update README.md for the project.

Flow

1. Analyze the project: package.json, CLAUDE.md, directory structure, framework, features.
2. Generate sections:

# [Project Name]

[One-line description]

## Features
- [Auto-detected from code and package.json]

## Quick Start
[Install + run commands from package.json scripts]

## Project Structure
[Key directories and their purpose]

## Tech Stack
[Framework, UI, backend, auth — auto-detected]

## Environment Variables
[From .env.example or CLAUDE.md]

## Scripts
[All package.json scripts with descriptions]

## Contributing
[Standard section]

3. If README.md exists, use AskUserQuestion:
   • Question: "README.md already exists. How should I update it?"
   • Options:
     • Merge — "Add missing sections, keep existing content" (Recommended)
     • Replace — "Overwrite with fresh generation"
     • Skip — "Don't modify README.md"

API MODE

Document all API routes/endpoints.

Flow

1. Find all API route files:
   • Next.js: app/api/**/route.ts, pages/api/**/*.ts
   • Astro: src/pages/api/**/*.ts
   • Convex: convex/*.ts (queries, mutations, actions)
   • Python: FastAPI routes, Flask routes
2. For each endpoint, document:
   • Method: GET, POST, PUT, DELETE
   • Path: full URL path
   • Auth: required? what type?
   • Request body: schema/type
   • Response: schema/type + status codes
   • Example: curl or fetch example
3. Output to docs/API.md or inline in the route files (ask user preference).

COMPONENTS MODE

Document all UI components.

Flow

1. Find all component files in the project.
2. For each component, document:
   • Name: component name
   • Description: what it does (from code analysis)
   • Props/Slots: all accepted props with types and defaults
   • Usage example: how to use the component
   • Dependencies: what it imports/requires
3. Output to docs/COMPONENTS.md or as a component index.

AUTO MODE

Detect documentation gaps and suggest what to document.

Flow

1. Check for:
   • Missing README.md
   • Undocumented exports (no JSDoc/docstring)
   • API routes without documentation
   • Components without prop documentation
   • Missing .env.example
   • Missing CHANGELOG.md
2. Use AskUserQuestion:
   • Question: "I found these documentation gaps. What should I document?"
   • multiSelect: true
   • Options based on detected gaps

Important

• Read actual code — never invent functionality that doesn't exist.
• Match existing doc style — if the project uses a specific documentation format, follow it.
• French for French projects — GoCharbon, claiire, plaisirsurprise (FR content).
• Every code example must be syntactically correct and runnable.
• Don't over-document. Simple, self-explanatory code doesn't need comments.
• For component docs, include the actual prop types from the source code.
• Keep README concise — link to detailed docs instead of putting everything in one file.
• Accents français obligatoires. Lors de toute création ou modification de contenu en français, vérifier systématiquement que TOUS les accents sont présents et corrects (é, è, ê, à, â, ù, û, ô, î, ï, ç, œ, æ). Les accents manquants sont une faute d'orthographe. Relire chaque texte produit pour s'assurer qu'aucun accent n'a été oublié — c'est une erreur très fréquente à corriger impérativement.