init-workspace-documentation - SKILL.md Agent Skill

name: init-workspace-documentation description: "Generate workspace docs." license: Apache-2.0 model: claude-opus-4-8, gpt-5.5-high, gemini-3.1-pro-preview tags: ["init", "workspace", "documentation", "context", "architecture"] baseSchema: docs/schemas/skill.md

Senior technical writer — recovers intent from code, not transcribes implementation. Workspaces lack structured documentation, forcing every session to re-discover facts and repeat mistakes. This skill creates five foundational docs from source code analysis. Proof: all five docs exist, are non-empty, complementary, and track unknowns.

All Rosetta prep steps MUST be FULLY completed, load-context skill loaded and fully executed
ACQUIRE reverse-engineering/SKILL.md FROM KB and EXECUTE for domain extraction
Existing project documentation is likely stale and incomplete: source code is the true source of truth
Documentation phase is based on discovery phase to perform deep analysis, but avoid reading entire codebase.
Select which files to read, group organize by modules/batches/groups and must assign to subagents to execute.

Dual-mode based on state.mode:
- Scan for each target doc file
- Compare existing content against codebase findings
- install = create all; upgrade = update gaps only
- Never overwrite human-added content; merge alongside
- Report created/updated/skipped files
Analyze project structure and key source files
Create TODO task per document with business context angle
Track unknowns in ASSUMPTIONS.md with forward references
Create or update documents:

CONTEXT.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Bulleted business context, purpose, domain — stakeholder perspective
No technical details

ARCHITECTURE.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Architecture, modules, workspace structure, testing, styling, building blocks
No business context — reference CONTEXT.md
Reference CODEMAP.md for file structure

IMPLEMENTATION.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Baseline state VERY BRIEFLY (first part, use word "Baseline" in header, not word "current" - misleading later on)
High-level change log, each change separate header with date and description (second part)
DRY — reference other docs
The only implementation change log
If nothing to add - add template

ASSUMPTIONS.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Each entry: assumption, confidence level, target file when resolved
Revalidate all assumptions after other documents complete
If nothing to add - add template

TODO.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Each entry comes with header containing "priority when what where" and body with details
If nothing to add - add template

AGENT MEMORY.md:

What this doc is for and what it should contain, self-defining style
Self-defines purpose, content type, style
Must follow the template exactly - it will be updated during use
Keep template entries so that AI knows how to fill them in later on
It is for agent operational notes, not a duplicate of CONTEXT.md/ARCHITECTURE.md

README.md:

Create in workspace and in each repository root README.md files if missing

Special cases:
- Speckit: if memory/constitution.md and specs folder exist, add "MUST ACQUIRE speckit-integration-policy.md FROM KB and execute it" to CONTEXT.md
- Composite (state.composite = true): create top-level docs as registries with workspace-relative paths to sub-repo docs
- If large project add "MUST USE SKILL large-workspace-handling" to CONTEXT.md

- Each document contains self-definition of purpose and style - Documents complement without repeating each other - ASSUMPTIONS.md entries have forward references to target documents - Upgrade mode: human content preserved, only gaps filled - Files can be grepped by headers for useful information and ToC

AGENT MEMORY.md

# AGENT MEMORY

Generalized reusable lessons from agent sessions.
Root causes converted into preventive rules, not incident-specific notes.
Entries are h3 headers with [ACTIVE|RETIRED] status.
Content: brief, grep-friendly, MECE across sections. 
Style: one-liner per entry, optional sub-bullets for context.
Keep template entries so that AI knows how to fill them in later on.

## Preventive Rules

### <Generalized Preventive Rule> [ACTIVE|RETIRED]
[Root cause, Reasons, Problems]

## What Worked

### <Generalized What Worked> [ACTIVE|RETIRED]
[Root cause, Reasons, Problems]

## What Failed

### <Generalized What Failed> [ACTIVE|RETIRED]
[Hypothesis, Root cause, Reasons, Problems]

## Discoveries

### <Generalized Discovery> [ACTIVE|RETIRED]
[Usage, Reasons, Problems]