init-workspace-flow-documentation

<init_workspace_flow_documentation>

<description_and_purpose> Agents without workspace documentation re-discover facts, repeat mistakes, and make incorrect assumptions every session. This phase creates the shared understanding layer all subsequent agent work depends on. Proof: five doc files exist and every prepped-workspace skill reads them. Use top tier model, as this documentation will be loaded every signle time in every single user session with AI. </description_and_purpose>

<workflow_context>

• Phase 7 of 9 in init-workspace-flow
• Input: TECHSTACK, CODEMAP, DEPENDENCIES, source code, PATTERNS, state.file_count, state.mode, state.composite
• Output: CONTEXT.md, ARCHITECTURE.md, IMPLEMENTATION.md, ASSUMPTIONS.md, AGENT MEMORY.md
• Prerequisite: Phases 3 and 5 complete </workflow_context>

<phase_steps>

1. Read state and prerequisites
2. Execute documentation creation
3. Update state, log gaps </phase_steps>

<read_state step="7.1">

1. Read agents/init-workspace-flow-state.md
2. Confirm Phase 3 complete (TECHSTACK, CODEMAP, DEPENDENCIES exist)
3. Read state.mode, state.composite, state.file_count </read_state>

<execute_documentation step="7.2" subagent="built-in" role="Senior technical writer synthesizing workspace documentation" subagent_recommended_model="claude-opus-5,gpt-5.6-sol-high,gemini-3.7-flash-high">

Act as a 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 creates five foundational docs from source code analysis. Proof: all five docs exist, are non-empty, complementary, and track unknowns.

1. Look around for any additional documentation and verify findings
2. Execute documentation creation with state.mode, state.composite, state.file_count as inputs, following the content below

<core_concepts>

• All Rosetta prep steps MUST be FULLY completed, load-project-context skill loaded and fully executed
• USE SKILL reverse-engineering 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.
• All docs MUST BE COMPRESSED, TERSE, CONCISE as those are ALWAYS loaded in LLM context.

</core_concepts>

<documentation_process>

1. 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
2. Analyze project structure and key source files
3. Create TODO task per document with business context angle
4. Track unknowns in ASSUMPTIONS.md with forward references
5. 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
• Limit to 100 lines, if there is MORE => keep CONTEXT.md with core CONTEXT plus index to per-feature -CONTEXT.md files with a set of terms what it contains.

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
• Limit to 150 lines, if there is MORE => keep ARCHITECTURE.md with core ARCHITECTURE plus index to per-area -ARCHITECTURE.md files with a set of terms what it contains.

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