feat: populate new flow arrange-workspace-flow

FAQ.md

@@ -120,7 +120,7 @@ Reusing one long session for many unrelated tasks bloats context and degrades re
 
 **How does Rosetta compare to other AI agent tools (superpowers, GSD, etc.)?**
 
-Most similar tools focus on one meta-flow — usually coding. Rosetta covers ~13 SDLC workflows: coding, security review, test generation, AQA, modernization, research, code analysis, requirements authoring, external library onboarding, workspace init, prompt authoring, and more. See [USAGE_GUIDE.md](USAGE_GUIDE.md) for the full list.
+Most similar tools focus on one meta-flow — usually coding. Rosetta covers ~17 SDLC workflows: coding, security review, test generation, AQA, modernization, research, code analysis, requirements authoring, external library onboarding, workspace init, prompt authoring, and more. See [USAGE_GUIDE.md](USAGE_GUIDE.md) for the full list.
 
 Rosetta also adds guardrails, HITL approval gates, sensitive-data handling, and risk assessment that apply across all workflows.
 

OVERVIEW.md

@@ -60,7 +60,7 @@ These terms are defined here and referenced everywhere else.
 
 Your IDE and coding agent ask Rosetta for instructions on each request.
 
-**Request types.** Thirteen workflow types cover the SDLC: coding, requirements documentation authoring, security review, automated QA, test generation, research, initialization, modernization, external library onboarding, code analysis, coding agents prompting, help, and ad-hoc. See the [Usage Guide — Workflows](USAGE_GUIDE.md#workflows) for details on each.
+**Request types.** Seventeen workflow types cover the SDLC: coding, requirements documentation authoring, security review, automated QA, test generation, research, initialization, arrangement, modernization, external library onboarding, code analysis, coding agents prompting, help, and ad-hoc. See the [Usage Guide — Workflows](USAGE_GUIDE.md#workflows) for details on each.
 
 **Standard pattern (P-RPA-V).** Every workflow follows Prepare (onboarding), Research (discovery), Plan (SDD), Act (implement), Validate (actually run or use an AI harness to verify the result works). Each phase can involve subagents, skills, and HITL approval gates.
 

USAGE_GUIDE.md

@@ -84,6 +84,31 @@ For composite workspaces, init each repository separately, then init at workspac
 
 </details>
 
+<details>
+<summary><b>Arrangement Workspace</b></summary>
+
+Arranges an already-initialized workspace: picks a layout for multi-repo work, onboards read-only reference code, closes business and technical context gaps, confirms modernization goals, and points to ecosystem tooling. Distinct from Init Workspace, which handles shells, discovery, and patterns — this flow assumes Rosetta setup is already done.
+
+**Use when:** deciding between a single-repo or composite workspace layout, bringing in reference codebases the agent cannot otherwise see, closing gaps in `docs/CONTEXT.md`/`docs/ARCHITECTURE.md`, confirming a modernization goal, or getting guidance on recommended MCPs/CLIs/plugins.
+
+**Phases:**
+1. Choose workspace layout — present Single Repo, Composite with Submodules, or Composite with gitignore options and guide the chosen layout's setup actions
+2. Reference source code — for Single Repo Workspace only, onboard read-only external codebases into `refsrc/` and keep `refsrc/INDEX.md` current
+3. Business context — gap-only interview to close `docs/CONTEXT.md` against required business topics
+4. Technical context — gap-only interview to close `docs/ARCHITECTURE.md` against required technical topics
+5. Modernization — only when the goal is modernization; capture goals, target pattern, and old-to-new mapping in `docs/PATTERNS/`
+6. Configure ecosystem — show MCP/CLI/plugin recommendations verbatim; guide installation only if you decide to
+
+**Expect:** executor, requirements-engineer, and architect subagents, one per phase, dispatched by the orchestrator. Every decision is tracked in `arrangement-state.md`. Your responsibility is to pick a layout, answer gap-only context questions, confirm or decline a modernization goal, and decide whether to install any recommended tooling.
+
+```
+/arrangement-workspace-flow Arrange this workspace, I have reference code in another repo
+/arrangement-workspace-flow Close the gaps in CONTEXT.md and ARCHITECTURE.md
+/arrangement-workspace-flow This is a modernization project, help me set it up
+```
+
+</details>
+
 <details>
 <summary><b>Self Help</b></summary>
 

docs/CODEMAP.md

@@ -1,6 +1,6 @@
 Code map of the Rosetta workspace — modules, key files, and entry points, 3-4 levels deep.
 
-## / — repo root (512 files total)
+## / — repo root (519 files total)
 
 README.md OVERVIEW.md QUICKSTART.md USAGE_GUIDE.md DEVELOPER_GUIDE.md CONTRIBUTING.md
 INSTALLATION.md TROUBLESHOOTING.md REVIEW.md SECURITY.md
@@ -95,14 +95,14 @@ subagent-directives/ tech-specs/ testing/
 architect.md discoverer.md engineer.md executor.md planner.md
 prompt-engineer.md requirements-engineer.md researcher.md reviewer.md validator.md
 
-#### instructions/r3/core/workflows/ — 16 top-level workflow files, 13 request types (+ phase files)
+#### instructions/r3/core/workflows/ — 17 top-level workflow files, 14 request types (+ phase files)
 
-adhoc-flow.md api-aqa-flow.md aqa-flow.md code-analysis-flow.md
-coding-agents-prompting-flow.md coding-flow.md external-lib-flow.md help-flow.md
-init-workspace-flow.md modernization-flow.md requirements-authoring-flow.md
+adhoc-flow.md api-aqa-flow.md aqa-flow.md arrangement-workspace-flow.md
+code-analysis-flow.md coding-agents-prompting-flow.md coding-flow.md external-lib-flow.md
+help-flow.md init-workspace-flow.md modernization-flow.md requirements-authoring-flow.md
 research-flow.md security-flow.md self-help-flow.md testgen-flow.md ui-aqa-flow.md
-(init-workspace-flow-*, aqa-flow-*, modernization-flow-*, security-flow-*,
-testgen-flow-* phase files)
+(init-workspace-flow-*, aqa-flow-*, arrangement-workspace-flow-*, modernization-flow-*,
+security-flow-*, testgen-flow-* phase files)
 
 13 request types: ui-aqa-flow + api-aqa-flow are one QA-automation type, aqa-flow is a
 backward-compat router over them plus testgen-flow, and self-help-flow is the deprecated

docs/definitions/workflows.md

@@ -1,6 +1,7 @@
 # Workflows
 
 - init-workspace-flow
+- arrange-workspace-flow
 - research-flow
 - code-analysis-flow
 - external-lib-flow

docs/web/_layouts/docs.html

@@ -54,6 +54,7 @@
 
     <p class="docs-sidebar-cat">Workflows</p>
     <a href="{{ '/docs/init-workspace-flow/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/init-workspace-flow/' %} active{% endif %}">Init Workspace</a>
+    <a href="{{ '/docs/arrangement-workspace-flow/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/arrangement-workspace-flow/' %} active{% endif %}">Arrangement Workspace</a>
     <a href="{{ '/docs/self-help-flow/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/self-help-flow/' %} active{% endif %}">Self Help</a>
     <a href="{{ '/docs/coding-flow/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/coding-flow/' %} active{% endif %}">Coding</a>
     <a href="{{ '/docs/requirements-authoring-flow/' | relative_url }}" class="docs-sidebar-link{% if page.url == '/docs/requirements-authoring-flow/' %} active{% endif %}">Requirements Authoring</a>