Write Project Docs

Write Project Docs

Type: Engineer (light)

Overview

Generate three human-readable documents for team members, new developers, and stakeholders:

• README.md (project root)
• docs/onboarding.md
• docs/deployment.md

These are NOT AI-context documents — they are for humans. No mentions of Claude, CLAUDE.md, skills, or plugin internals.

This was a Heavy Engineer skill until v3.1.0 (inline in Opus). v4.2.0 fans the three independent doc generations out to parallel sonnet subagents — the Opus main session keeps pre-flight, the no-AI-mention gate, and the merge. See _shared/references/orchestration-conventions.md.

Process

Step 0: Pre-flight

1. Read CLAUDE.md from pwd. If missing → STOP: "No CLAUDE.md found — are you in the right project?" and extract the project name + primary stack + platform (web / iOS / Android / cross-platform / CLI / plugin / etc.).

1. Verify input files:

• Required: CLAUDE.md, docs/architecture/system.md
• Optional: docs/architecture/api.md, existing README.md (preserve any custom sections found there), deployment configs found in the tree

1. For each missing required file, ask the user:

> "Required input ` is missing. Options: (a) run /vladyslav:ingest` first to populate it / (b) create stub now / (c) abort"

• On (a) → exit cleanly. Suggest the user run ingest then come back.
• On (b) → create stub and continue (output will be skeletal).
• On (c) → exit cleanly.

1. Scan for deployment configs. Look at the project tree for Dockerfile, docker-compose.yml, .github/workflows/*.yml, vercel.json, fly.toml, railway.toml. Note any found — they shape the deployment guide.

Step 1: Read inputs

Read the FULL content of every available input file (do not truncate). The output must be accurate to the actual code state.

Steps 2–4: Generate the three docs (parallel fan-out)

The three documents are independent — none references another's output. Dispatch them as three Agent calls in a single message so they run concurrently, each model: "sonnet" (pure generation from decided inputs — see _shared/references/orchestration-conventions.md).

Give each subagent: the relevant input content from Step 1, its structure block below, the preservation rule (merge, don't clobber user-edited sections of an existing file), and the no-AI-mention rule. Each subagent writes its own file.

After all three return, the Opus main session runs the no-AI-mention gate (grep the three outputs for Claude / CLAUDE.md / .claude/ / "AI" and fix any leak) before rendering the summary. This gate stays in the main session — never delegated.

Step 2: Generate README.md (subagent → README.md)

Write README.md at the project root. If it exists, preserve any custom sections; merge the rest.

Structure:

# 

## Run locally

\`\`\`bash
# install dependencies
# start dev server / build app
\`\`\`

## Project structure

\`\`\`
/    # purpose
/    # purpose
\`\`\`

## API overview (if backend project)

- `GET /endpoint` — purpose
- `POST /endpoint` — purpose

## Deployment

See [docs/deployment.md](docs/deployment.md).

Do NOT include Claude, CLAUDE.md, .claude/, or "AI" anywhere in the README.

Step 3: Generate docs/onboarding.md (subagent → docs/onboarding.md)

Write docs/onboarding.md. Preserve user edits where reasonable.

Structure:

# Onboarding Guide

For new developers joining the project.

## Prerequisites

-  v — 
-  v — 

## Setup

1. Clone the repo
2. Copy `.env.example` → `.env` and fill values
3. Install dependencies (``)
4. Run locally (``)

## Architecture overview

## Key files to know

- `` — 

## Development workflow

- Branching strategy: 
- PR review: 
- Code style: 

## Running tests

\`\`\`bash

\`\`\`

## Who to ask

- `` for ``  ← placeholder if unknown

Step 4: Generate docs/deployment.md (subagent → docs/deployment.md)

Write docs/deployment.md. Preserve user edits.

Structure:

# Deployment Guide

## Environment requirements

- Runtime: 
- Infrastructure: 
- External dependencies: 

## Deploy steps

1. Step one
2. Step two
3. Step three

## Environment variables

| Variable | Purpose | Example value |
|----------|---------|---------------|
| `VAR_NAME` | What it does | `example_value` |

## Rollback procedure

## Monitoring / logging

- Logs: 
- Metrics dashboard: 
- Alerting: 

Derive concrete deploy steps from the deployment configs found in Step 0.4. For projects without any deployment config, fill the file with stub guidance ("no deployment configuration found — fill manually once chosen").

Step 5: Summary

Render:

✓ write-project-docs complete
  Files: README.md, docs/onboarding.md, docs/deployment.md
  Action per file: 
  Deployment configs detected: 
  Warnings: 
  Next: /vladyslav:pre-release-check  — verify before deploying

---

Why this is a Light Engineer skill (with parallel generation)

• Three independent generation passes. v3.1.0 dropped the old Heavy Engineer YAML-return + present-summary boilerplate (~50 lines of tax). v4.2.0 keeps that lean body but fans the three generations out to parallel sonnet subagents — wall-clock ~3× faster and cheaper than three sequential opus passes, with no contract boilerplate.
• The Opus main session stays the control plane — pre-flight, the no-AI-mention gate, and preservation sanity all run in main, not in subagents.
• No allowlist enforcement — exactly three output paths, all under-the-project-root, none surprising. Each subagent owns exactly one path.

Output

• README.md
• docs/onboarding.md
• docs/deployment.md

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VladislavSournine
• Source: VladislavSournine/vladyslav-skills
• License: MIT

Install and usage instructions live in the source repository linked above.