feat: populate new flow arrange-workspace-flow - #217
Merged
Conversation
…ering of initial phases
github-actions
Bot
added
enhancement
Contributor
Rosetta Triage ReviewSummary: Adds Findings:
Caveats:
Suggestions:
Questions:
Automated triage by Rosetta agent |
… and update the number of workflows in FAQ
YevheniiaLementova
changed the title
isolomatov-gd
requested changes
Aug 10, 2026
…nd remove the subagent call from the workflow
…ace-flow phases - already loaded in prerequisites
…_context with meaninful description
isolomatov-gd
changed the title
…kspace-flow phases
…hnical context phases
isolomatov-gd
requested changes
Aug 13, 2026
Contributor
|
Plus merge latest main to your PR and update its new docs/user-guide as well |
…sed on review comments
…-setup Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # docs/web/_layouts/docs.html # docs/web/docs/usage-guide.md
Contributor
📋 Prompt Quality Validation Report❌ Validation FailedThe full markdown report and raw JSON output are available in the workflow artifacts for 5 days. Files With Issues
📄
|
| Severity | Gate | Details |
|---|---|---|
| High | Conflict Resolution | Problem: Phase 5 is gated applies="modernization goal" (line 52) and line 54 says to skip when the goal is not modernization, but nothing says where that goal comes from. Phases 1 and 2 both gate on a value explicitly recorded in the state file.Reason: An inferred flag decides whether a whole phase runs. On a re-run or after compaction the inference can flip, and phase 5 silently does nothing on a real modernization project. Solution: Add a step to phase 3 that records in the state file whether the project goal is modernization as a user-confirmed yes/no, and change line 54 to read that recorded field instead of inferring. |
| High | Failure Handling | Problem: Phases 3-5 read docs/CONTEXT.md, docs/ARCHITECTURE.md, and docs/PATTERNS/INDEX.md, which are produced by init-workspace-flow. The only mention that init must run first is a pitfall on line 106. No phase has a branch for these files being missing.Reason: On a workspace where init never ran, load-project-context fires its own 'strongly suggest init-workspace-flow' message mid-run. With no arbitration line, the agent either derails into a flow the user did not ask for or ignores its own bootstrap skill.Solution: Add a prerequisite item to phase 0: if CONTEXT.md, ARCHITECTURE.md, or PATTERNS/ are absent, say that init-workspace-flow.md normally runs first, ask the user to confirm continuing anyway, and record the answer in the state file. |
| High | Precision & Explicitness | Problem: Line 20 says state goes to agents/TEMP/<FEATURE>/arrange-state.md, but this flow is workspace-wide and has no feature, so <FEATURE> is never bound. All six phases then refer only to the bare name arrange-state.md with no path. The schema in docs/schemas/workflow.md also expects the name arrange-workspace-flow-state.md.Reason: The agent has to invent the folder name. If the session compacts, the phase files carry no path at all and the agent writes a second, empty state file. The <completion> gate on line 111 then reads a ledger that does not reflect the work done.Solution: Replace <FEATURE> on line 20 with a fixed literal path and use the schema name, for example agents/TEMP/arrange-workspace/arrange-workspace-flow-state.md. Add one prerequisite line telling the agent to create the file at phase 0 with one row per phase (status, decision, skip reason), and repeat the full path once in each phase file. |
| Medium | Bloat Control | Problem: The <next_steps> block on lines 67-103 is copied byte for byte from init-workspace-flow.md lines 121-157, roughly 37 duplicated lines. It carries that file's broken markdown link on line 69, (USAGE GUIDE)[https://...], with the brackets reversed, and it re-shows the full modernization example block even to a user who just finished the modernization interview.Reason: The broken link is the flow's main call to action and renders as plain text for the user. Duplicated blocks in two files drift apart over time, and every line is resent on each model call. Solution: Fix the link on line 69 to [USAGE GUIDE](https://griddynamics.github.io/rosetta/docs/usage-guide/), trim the copied example sections to the ones relevant to this flow, and state the restart reason that actually applies here (CONTEXT.md and ARCHITECTURE.md changed, so the session is holding stale context). |
| Medium | Rosetta | Problem: Line 18 reads USE SKILL \\load-project-context\, \\hitl\`` and omits orchestration, which docs/schemas/workflow.md line 38 requires for all but trivial flows. Sibling flows research-flow.md, security-flow.md, and modernization-flow.md all include it. The line also drops the mandatory `MUST` wording.Reason: This is a six-phase flow that writes several shared documents. Without the orchestration skill the agent loses the guidance it needs to manage a long multi-phase run. Solution: Add `orchestration` to the phase 0 skill list and restore the `MUST USE SKILL` wording used by the sibling flows. |
📄 instructions/r3/core/workflows/arrange-workspace-flow-choose-workspace-layout.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| Very High | Workflow Completeness | Problem: Options 2 and 3 relocate the workspace: lines 91 and 130 say 'Create a new empty git repository to serve as the composite workspace envelope' and line 93 says 'Initialize Rosetta in the envelope workspace'. Nothing in this phase or any later phase re-anchors the working root, and phases 3-6 keep writing to plain relative paths such as docs/CONTEXT.md.Reason: Without it the agent keeps running inside the original sub-repository and writes every context document to the wrong repo, while the composite index promised on line 64 is never created anywhere. Solution: Add a step to <apply_setup step="1.3">: when Option 2 or 3 is chosen and the envelope does not yet exist, record the layout in the state file, stop the flow, and tell the user to re-run it from the envelope repository root. |
| Very High | Conflict Resolution | Problem: Line 145 orders the agent to guide the chosen option's setup actions from layout_guidance 'exactly'. Option 1's setup actions on line 55 say 'Clone any read-only reference codebases into refsrc/ as subfolders'. Line 146 then forbids exactly that: 'do not clone into refsrc/ here'. The layout_guidance block is marked compact="NEVER" summarize="AS-IS" (line 28), so the conflicting sentence cannot be reworded at runtime.Reason: This fires on Option 1, the option the text itself calls the recommended starting point, so it hits the most common path. The agent is told to follow one line exactly and to ignore it one line later, and the pitfall on line 159 names the trap without resolving it. Solution: Remove the refsrc/ cloning bullet from Option 1's setup actions on line 55, since line 146 and the Reference Source Code phase already own that step. Keep line 146 as the single source of truth. |
📄 instructions/r3/core/workflows/arrange-workspace-flow-reference-source-code.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| High | Dependency Management | Problem: The .gitignore exceptions agents/TEMP/, refsrc/, and !refsrc/INDEX.md are set up only here, on lines 30-35, inside a phase gated applies="Single Repo Workspace (Option 1)". The modernization phase tells the agent to clone legacy code into refsrc/<name> with no layout condition at all.Reason: On a composite workspace that also runs modernization, the agent clones a whole legacy codebase into a refsrc/ folder that was never excluded from git, so the legacy tree and the agents/TEMP/ state file get staged and committed.Solution: Move the three-line .gitignore block out of step 2.2 into the root flow's phase 0 as an applies="ALL" item, so the exclusions are in place regardless of which layout the user picked. |
| Medium | Precision & Explicitness | Problem: Line 42 says 'Ask if there is reference code to add; if not, record no-op and stop.' The word 'stop' is not scoped to the phase. Reason: 'No reference code' is the most common answer. A plausible reading ends the entire flow there, silently dropping phases 3-6, which carry most of the flow's value. Solution: Change 'stop' to 'end this phase', matching how the root flow phrases skips ('skip, record skip reason, proceed to phase 3'). |
📄 instructions/r3/core/workflows/arrange-workspace-flow-business-context.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| Very High | Conflict Resolution | Problem: Lines 36-66 embed a 31-line '# Universal Starter Definition of Done' checklist inside <starter_topics> with no instruction attached to it. Its content is mostly technical: 'Build, lint, type, and static checks pass', 'changed code coverage >=85%', 'migrations tested, safe, and reversible', 'CI/CD, and deployment assets updated'. The <context_contract> in the same file (lines 70-72) says CONTEXT.md must have 'No technical details' and a 100-line limit, and the pitfall on line 82 warns against 'Mixing business context with technical architecture'.Reason: The block has no governing verb and no compact="NEVER" marker, unlike the genuine verbatim blocks elsewhere in this flow, so the agent cannot tell whether to show it, ask about it, or paste it. The most likely reading is to paste it into CONTEXT.md, which breaks the file's own contract and burns a third of the 100-line budget on content that belongs in ARCHITECTURE.md. CONTEXT.md is read in full at every session start, so the cost is permanent.Solution: Remove lines 36-66 from <starter_topics>; the topic bullet 'Accepted SDLC, DoD, and processes related to the project' on line 33 already covers the interview need. If a starter checklist is wanted, give it its own step writing to its own file, outside the business-context contract. |
| High | Output Contract | Problem: Step 2 on line 19 says to record confirmed answers to docs/CONTEXT.md, and <context_contract> describes only the shape of the file. Neither says whether to create, append, or replace, and neither protects existing human-written content. The validation checklist on line 76 only checks the file 'exists, non-empty, <=100 lines'.Reason: This flow runs on workspaces where CONTEXT.md already exists and may be human-curated. Without the guard, and with a 100-line cap in force, the agent can rewrite or truncate content it did not author. Solution: Add 'extend, never replace' and a preserve-human-content clause to <context_contract>, matching the wording already used in the modernization phase's doc_contract. |
| Medium | Single Responsibility | Problem: The phase is scoped to interviewing for business context, but the embedded Definition of Done checklist on lines 36-66 introduces a second, unrelated job (defining project quality gates) inside the same section. Reason: Mixing two jobs in one section makes the agent's task ambiguous and pushes technical content into a phase explicitly scoped to non-technical facts. Solution: Remove the checklist as described above, keeping this phase to the single job named in its <description_and_purpose>. |
📄 instructions/r3/core/workflows/arrange-workspace-flow-technical-context.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| High | Output Contract | Problem: Step 2 on line 19 records confirmed answers to docs/ARCHITECTURE.md and <architecture_contract> (lines 39-42) defines only the shape of the file. Neither states create-versus-update behavior nor protects existing human-written content, while the sibling modernization phase does say 'extend, never replace'.Reason: ARCHITECTURE.md usually already exists when this flow runs, and it is read in full at every session start. Combined with the 100-line cap, the missing guard lets the agent overwrite or truncate content a human wrote. Solution: Add 'extend, never replace' and a preserve-human-content clause to <architecture_contract>, matching the modernization phase's doc_contract. |
📄 instructions/r3/core/workflows/arrange-workspace-flow-modernization.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| High | Input Contract | Problem: This phase mandates refsrc/<name> with no layout condition, but the phase that establishes refsrc/ conventions is gated to Option 1 only, and the Reference Source Code phase's pitfall explicitly rules composite siblings out of refsrc/. A composite workspace running modernization is told to populate a folder this flow never sets up for that layout.Reason: Composite plus modernization is a realistic combination, and today the two phases give contradictory guidance about whether refsrc/ applies to it.Solution: State in <patterns_contract> or step 3 where reference code lives for composite layouts, or require the refsrc/ gitignore and INDEX conventions to be confirmed before cloning when the layout is Option 2 or 3. |
| High | Workflow Completeness | Problem: Step 3 on line 20 guides cloning the old codebase into refsrc/<name> but never requires a matching refsrc/INDEX.md entry. The validation checklist on line 58 only checks that the location was 'captured' and the clone 'recommended'. The Reference Source Code phase does enforce the INDEX entry for every other reference codebase.Reason: load-project-context greps refsrc/INDEX.md to discover reference code. The legacy codebase is the single most important reference in a modernization project, and it is the one that bypasses the indexing path, so it stays invisible to every later session.Solution: Extend step 3 to add the refsrc/INDEX.md entry for the cloned legacy code, and add that entry to <validation_checklist>. |
| High | Failure Handling | Problem: Line 41 asks for the old-to-new equivalent 'for every pattern in docs/PATTERNS/INDEX.md' and line 51 says to 'Write docs/PATTERNS/INDEX.md — all patterns with one-line descriptions'. That file is produced by init-workspace-flow-patterns.md, a different flow. There is no branch for it being absent, and the write is unconditional and whole-file, while the producing phase carries an explicit 'PRESERVE-HUMAN: never overwrite human-curated content' guard that was not copied across.Reason: With no absence branch the agent either interviews the user to hand-enumerate every legacy pattern or invents an INDEX.md to satisfy the write instruction. Because the write is unconditional and whole-file, it can also destroy a real, human-curated index. That file feeds the grep roster that load-project-context runs at every session start.Solution: Add to <patterns_contract>: if docs/PATTERNS/INDEX.md is missing, skip the patterns topic, record the skip reason, and recommend running init-workspace-flow.md first. Also add the create-or-update and preserve-human clauses used by the producing phase. |
| Medium | Success Criteria | Problem:<patterns_contract> requires writing docs/PATTERNS/INDEX.md and docs/PATTERNS/CHANGES.md, but <validation_checklist> on lines 57-59 checks only CONTEXT.md, ARCHITECTURE.md, the old-code location, and the state file. Neither PATTERNS output is verified.Reason: Outputs that no checklist covers are the ones agents quietly skip, and the patterns mapping is the main technical deliverable of this phase. Solution: Add checkpoints to <validation_checklist> confirming that docs/PATTERNS/INDEX.md and docs/PATTERNS/CHANGES.md reflect the old-to-new mapping captured in this phase. |
📄 instructions/r3/core/workflows/arrange-workspace-flow-configure-ecosystem.md
⚠️ Issues Found
| Severity | Gate | Details |
|---|---|---|
| High | Conflict Resolution | Problem: Line 78 says 'Add a note to docs/CONTEXT.md on what got installed', and the checklist on line 85 repeats it. MCPs, CLIs, LSPs, and plugins are technical tooling. The business-context phase's contract says CONTEXT.md holds 'No technical details', and the technical-context phase names ARCHITECTURE.md as the technical home, with a starter topic covering 'Any AI agentic harnesses to use'.Reason: Three files in the same flow disagree about which document holds tooling facts. CONTEXT.md is read in full at every session start and was capped at 100 lines two phases earlier, with no re-check after this phase appends to it. Solution: Change line 78 and the matching checklist item on line 85 to write the installed-tooling note to docs/ARCHITECTURE.md instead of docs/CONTEXT.md. |
| Medium | Success Criteria | Problem: The first checklist item on line 83 is 'Guidance shown to user', which restates the step rather than giving observable proof. The sibling layout phase uses a stronger form: 'Layout options shown to the user verbatim, unabridged.' Reason: A checkpoint that just repeats the instruction cannot fail, so it gives no real protection against the agent summarizing a block marked compact="NEVER".Solution: Reword the item to something checkable, such as confirming the ecosystem_guidance block was shown verbatim and unabridged. |
isolomatov-gd
approved these changes
Aug 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Workspace setup today is documented in
CONFIGURATION.md: a manual checklist the user has to read end-to-end and execute by hand — capture business context, capture technical context, add reference source code, pick a workspace layout, set up modernization docs, configure MCPs/CLIs. Nothing enforces it happens, nothing tracks what's done, and nothing adapts the interview to what's already in the repo.Solution
Adds
arrange-workspace-flow, a new Rosetta workflow that turns that checklist into an AI-guided, HITL, phase-by-phase flow. Instead of the user readingCONFIGURATION.mdand self-driving each step, the agent walks them through it interactively, loads one phase at a time , asks only gap-only questions (skips what's already covered), routes unconfirmed inferences todocs/ASSUMPTIONS.md, and persists progress inarrange-state.mdso nothing is silently skipped.All six phases are executed sequentially by a single agent — no subagent dispatch. Each phase is its own file (
arrange-workspace-flow-*.md), loaded and executed only when reached, keeping context small and enforcement structural rather than just instructional.Phases added
refsrc/,refsrc/INDEX.md,.gitignoredocs/CONTEXT.md; unconfirmed inferences →docs/ASSUMPTIONS.mddocs/ARCHITECTURE.md; unconfirmed inferences →docs/ASSUMPTIONS.mddocs/CONTEXT.md/docs/ARCHITECTURE.md/docs/PATTERNS/Allium recommendation
Phase 6 (Configure Ecosystem) now recommends Allium in its "Recommended Plugins" list — an MIT-licensed skill for spec-first, behavior-driven development. It's shown as guidance only, same as every other entry in that list.
Documentation
OVERVIEW.md,FAQ.md,USAGE_GUIDE.md,docs/CODEMAP.md,docs/definitions/workflows.mdand theirdocs/web/mirrors (docs/web/docs/overview.md,docs/web/docs/faq.md,docs/web/docs/usage-guide.md):arrange-workspace-flowamong request types, counts corrected to 17 workflow types (from 13).New
docs/web/docs/arrange-workspace-flow.md— full workflow page (TL;DR, phase table, two Mermaid diagrams, per-phase breakdown, source links).llms-full.txt—/arrange-workspace-flowentry added in §9. No skill-catalog entry needed; the flow reuses existing skills rather than introducing a new one.Verification
bash src/run-tests.shexit 0 — full suite green (rosettify 1087, rosettify-plugins 572, rosettify-prompts 96, curiocity 429, hooks 1142, plus the Python suites: rosetta-mcp-server 327, rosetta-cli 35).Plugins regenerated with
npx -y rosettify-plugins@latest --release r3 --deterministic-hooks false; the only new propagation wasarrange-workspace-flow(1 main + 6 phase files), landing across all 7 plugin targets (core-claude,core-cursor,core-cursor-standalone,core-copilot,core-copilot-standalone,core-codex,core-antigravity) with correspondingINDEX.md/hooks.jsonrefreshes and no unrelated drift.Counts checked against disk: 7
arrange-workspace-flow*source files (1 main + 6 phases) ininstructions/r3/core/workflows/, propagated 7/7 plugin targets.Type validation (
src/validate-types.sh) passed.Closes #137 and Closes #140