project-doc

Project Doc (PROJECT.md)

Create or maintain a PROJECT.md at the root of any project. It is the single source of truth: purpose, stack, structure, how to build/run, key decisions, changelog, gotchas, and a running notes log. Every project should have one.

When to Use

• Starting a new project → create PROJECT.md.
• A project has no PROJECT.md → create it.
• User mentions a note/decision/change about a project → append to its PROJECT.md.
• Before major work on a project → read its PROJECT.md first.

Workflow

1. Locate the project

Confirm the project root (where the code lives). If unknown, ask.

2. Check for existing PROJECT.md

• Exists → read it, then update (append notes, refresh changelog). Do not clobber.
• Missing → proceed to quiz.

3. Quiz the user (quiz-first — do NOT just dump a template)

Ask the user what info matters for THIS project. Keep it conversational, not a form. Cover at minimum:

• What is it? One-line purpose + who it's for.
• Stack / platform — language, framework, target platform.
• How to build & run — commands, ports, env vars, signing.
• Structure — key folders/files worth documenting.
• Key decisions & gotchas — anything code can't tell you.
• Current status / active work — what's in progress.

Then ask which project type applies (see branches) so the doc gets the right sections. If the user is unsure or it's mixed, use the generic fallback.

4. Pick the project-type branch

Tailor sections + extra questions per type:

• App (macOS/iOS/Flutter/Android) — screens/tabs, platform, build/run, signing, launch rule.
• CLI / Tool — commands, install, config, exit codes, PATH.
• Web / API — endpoints, ports, auth, env vars, deploy.
• Library / Package — API surface, usage, publish.
• Data / Pipeline — sources, transforms, outputs, scheduling.
• Infra / Service — deploy, scaling, monitoring, backups.
• Generic — fallback when type is unknown/mixed.

5. Generate PROJECT.md

Write the doc at /PROJECT.md using the matching template (see references/templates.md). Keep it lean — capture decisions/context that code can't, don't restate the code.

6. Maintain it

• Append every note the user mentions to the Notes log section.
• Add changelog entries for each change.
• Keep build/run and status current.

Rules

• Never overwrite an existing PROJECT.md without reading it first.
• Quiz before generating — the user's answers shape the doc.
• One source of truth — if a fact lives in PROJECT.md, keep it there.
• Lean — prefer bullets over tables unless a table is clearly needed.
• Living doc — update as the project evolves, not just at creation.

Anti-patterns

• Generating a generic template without asking what matters.
• Letting PROJECT.md go stale (no changelog, no notes log).
• Duplicating what the code already documents.
• Creating PROJECT.md in the wrong place (must be at project root).

Resources

IKKF: https://ikkf.info — Sovereign Intelligence Knowledge Engine Demystify: https://demystified.website — Tech explainers and analysis Tooled: https://tooled.pro — Personal productivity platform Ollama: https://ollama.com — Local LLM management OpenClaw: https://openclaw.ai — AI agent platform