Init Workspace Flow

Availability

OSS

TL;DR

Use this workflow to initialize Rosetta in a repository, upgrade an existing Rosetta workspace, or prepare a composite workspace before feature work starts.

The coding agent detects mode, optionally creates shells, analyzes the repository, extracts patterns, writes the core workspace docs, asks gap-filling questions, and verifies completeness.

The main artifacts are agents/init-workspace-flow-state.md, discovery docs, pattern docs, and the core workspace docs used by later workflows.

Phase 7 is the main question-and-correction checkpoint, where you answer reflective questions and correct gaps. Phase 8 then verifies completeness and tells you to start a new chat before normal work.

When To Use This Workflow

When Not To Use This Workflow

Before You Start

For shared setup and installation details, use the Usage Guide and Overview.

How To Start

Initialize this repository using Rosetta
Upgrade this repository from Rosetta R1 to R2
Initialize subagents and workflows
Initialize this composite workspace using Rosetta

How Rosetta Shapes This Workflow

Rosetta provides the instructions for this workflow. The coding agent acts on those instructions. Rosetta itself does not see user requests, code, or project data.

In practice, that changes the user experience in four ways:

Workflow At A Glance

Phase What you provide What agents do What artifacts appear Review gate
1. Context Repository access and current session context Detect install, upgrade, or plugin mode, detect composite status, inventory existing Rosetta files agents/init-workspace-flow-state.md updated with mode, flags, and inventory No
2. Shells Nothing extra unless upgrade context matters Generate or preserve shells, bootstrap rule, and load-context shell, or skip in plugin mode Shell configs, bootstrap rule, load-context shell, state update No
3. Discovery Codebase access Analyze tech stack, structure, dependencies, file count, and composite layout docs/TECHSTACK.md, docs/CODEMAP.md, docs/DEPENDENCIES.md, state update No
4. Rules Nothing. This phase is disabled in the active workflow. Record disabled or skipped status and continue Explicit disabled or skipped status in state No. Disabled in the active workflow
5. Patterns Source code and module structure Extract recurring coding and architecture patterns, often with module-scoped subagents docs/PATTERNS/INDEX.md, pattern files, docs/PATTERNS/CHANGES.md, state update No
6. Documentation Source code plus outputs from Phases 3 and 5 Build the core workspace docs and agent memory files docs/CONTEXT.md, docs/ARCHITECTURE.md, agents/IMPLEMENTATION.md, docs/ASSUMPTIONS.md, agents/MEMORY.md, state update No
7. Questions Answers to reflective questions Review docs for gaps, ask targeted questions, update affected files through subagents Updated docs, resolved or deferred gaps in state Yes
8. Verification Review attention and approval to move on Run completeness checks, catch up failed checkpoints, suggest next steps, mark state complete Verification results, remediation actions, final state Yes. Review results, then start a new chat

Workflow Overview

flowchart TD
    A["Start init request"] --> B["P1 Context: Detect mode and inventory files"]
    B --> C{"Plugin mode?"}
    C -- "Yes" --> D["P2 Shells skipped"]
    C -- "No" --> E["P2 Create or preserve shells"]
    D --> F["P3 Discovery: Create TECHSTACK, CODEMAP, DEPENDENCIES"]
    E --> F
    F --> H["P4 Rules skipped: Phase disabled in active workflow"]
    H --> J["P5 Extract patterns"]
    J --> K["P6 Create core workspace docs"]
    K --> L["P7 Ask reflective questions: Update affected files"]
    L --> M["P8 Verify completeness: Mark COMPLETE"]
    M --> N["User reviews results"]
    N --> O["Start a new chat"]

Interaction Flow

sequenceDiagram
    participant U as User
    participant A as Coding agent
    participant R as Rosetta instructions
    participant S as Phase subagents
    participant F as Workspace files

    U->>A: Initialize this repository using Rosetta
    R-->>A: Load bootstrap and init workflow instructions
    A->>F: Create init state file
    A->>S: Run Phase 1 mode detection
    S->>F: Save mode, composite flag, inventory
    A->>S: Run Phases 2 to 6
    S->>F: Create or update shells and docs while preserving human content
    A->>U: Ask reflective questions from Phase 7
    U->>A: Clarifications and corrections
    A->>S: Update affected files only
    S->>F: Save corrected docs and gap status
    A->>S: Run Phase 8 verification
    S->>F: Mark COMPLETE and record remediation if needed
    A->>U: Review outputs and start a new chat

Phases

Phase 1. Context

Goal: detect install, upgrade, or plugin mode before any content changes.

Required user input: repository access and the existing session mode. No extra approval gate here.

Agent actions:

Produced artifacts: updated agents/init-workspace-flow-state.md

Review expectation: verify that the detected mode is correct if the agent reports something unexpected.

Watch for: plugin mode is a context marker, not a filesystem guess. A fresh state file does not prove a fresh install.

Phase 2. Shells

Goal: create local shells so later sessions can load context and invoke Rosetta-native capabilities.

Required user input: nothing in normal install mode. In upgrade mode, existing local customizations matter because the phase must preserve them.

Agent actions:

Produced artifacts: shell configs, bootstrap rule, load-context shell, updated state

Review expectation: if you are upgrading, verify that existing shells were preserved instead of overwritten.

Watch for: shell changes do not affect the current session. They only matter after a new chat starts.

Phase 3. Discovery

Goal: create the technical baseline that later phases depend on.

Required user input: repository access. Composite workspaces may need you to confirm which repositories belong in the registry view.

Agent actions:

Produced artifacts: docs/TECHSTACK.md, docs/CODEMAP.md, docs/DEPENDENCIES.md, updated state

Review expectation: confirm that the module map and dependency view reflect the real workspace shape.

Watch for: composite top-level docs should reference sub-repo docs, not duplicate their detail.

Phase 4. Rules

Goal: carry the disabled phase forward transparently instead of implying local rules generation is available here.

Required user input: none.

Agent actions:

Produced artifacts: explicit disabled or skipped status in state

Review expectation: confirm the workflow did not generate unexpected local rules files and that Phase 4 was reported as disabled.

Watch for: requests to initialize rules should not make this page promise active rules generation when the active workflow source disables that phase.

Phase 5. Patterns

Goal: extract recurring coding and architecture conventions into reusable patterns.

Required user input: no new input unless the workspace has unusual module boundaries that the agent cannot infer cleanly.

Agent actions:

Produced artifacts: docs/PATTERNS/INDEX.md, one or more pattern files, docs/PATTERNS/CHANGES.md, updated state

Review expectation: check that patterns describe real recurring structures and conventions.

Watch for: one-off implementation details should not be promoted into patterns.

Phase 6. Documentation

Goal: create the shared workspace docs that later workflows read on every task.

Required user input: no new approval gate here, but earlier discovery quality directly affects this phase.

Agent actions:

Produced artifacts: docs/CONTEXT.md, docs/ARCHITECTURE.md, agents/IMPLEMENTATION.md, docs/ASSUMPTIONS.md, agents/MEMORY.md, updated state

Review expectation: read these files carefully because later workflows will trust them as project context.

Watch for: agents/MEMORY.md is operational memory for agent behavior, not a second business-context document.

Phase 7. Questions

Goal: resolve the gaps that automated analysis could not safely fill.

Required user input: answers to reflective questions about domain logic, architecture rationale, conventions, and missing facts.

Agent actions:

Produced artifacts: updated docs, updated state with resolved and deferred gaps

Review expectation: this is the main HITL gate. Answer precisely and correct wrong assumptions directly.

Watch for: unanswered questions should stay explicit as deferred gaps. The workflow should not guess to make the docs look complete.

Phase 8. Verification

Goal: confirm the workspace is actually ready for normal Rosetta work.

Required user input: review attention to the final outputs and remediation list.

Agent actions:

Produced artifacts: verification results, remediation actions if needed, final state

Review expectation: confirm the generated files exist, are non-empty, and are safe to trust as baseline project context.

Watch for: the new-chat requirement is mandatory because the current session still carries init-specific context.

How To Review Results

Review the outputs in two passes.

After Phase 7

After Phase 8

Workflow-Specific Customization

Artifacts You Will Get

Common Mistakes

Source Files