diff --git a/CONFIGURATION.md b/CONFIGURATION.md index 094ea5d39..22301c84e 100644 --- a/CONFIGURATION.md +++ b/CONFIGURATION.md @@ -2,7 +2,7 @@ **Who is this for?** Engineers setting up a workspace (in the VS Code sense) for the first time, so AI coding agents work well in it. -**When should I read this?** After you connect Rosetta (see [Quick Start](QUICKSTART.md)), and before you start real coding or modernization work. +**When should I read this?** After you connect Rosetta (see [Quick Start](README.md#quick-start)), and before you start real coding or modernization work. --- @@ -16,8 +16,8 @@ If you are migrating or modernizing a codebase, do the steps below first, then r ## 1. Install and Onboard -1. Connect Rosetta to your IDE — follow the [Quick Start](QUICKSTART.md). -2. Onboard the repository to Rosetta (Quick Start, Step 2). This is required before the steps below. +1. Connect Rosetta to your IDE — follow [PLUGINS.md](PLUGINS.md), [MCPs.md](MCPs.md), or [INSTALLATION.md](INSTALLATION.md). +2. Onboard the repository to Rosetta — follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository). This is required before the steps below. --- @@ -189,7 +189,7 @@ Setup actions: - Open the repository in your IDE. - Clone any read-only reference codebases into `refsrc/` as subfolders. -- Initialize Rosetta (see [Quick Start](QUICKSTART.md)). +- Initialize Rosetta (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)).
Detailed examples what should be in RefSrc folder @@ -328,7 +328,7 @@ Setup actions: - Create a new empty git repository to serve as the composite workspace envelope. - Request AI to add each sub-repository (code, infra, QA, frontend, shared libraries, etc.) as a git submodule and clone them into the envelope. -- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace and that `ARCHITECTURE.md` must record that submodules are used for dynamic and optionally sparse-checkout (see [Quick Start](QUICKSTART.md)). +- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace and that `ARCHITECTURE.md` must record that submodules are used for dynamic and optionally sparse-checkout (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)). - Development teams can then use sparse-checkout on modules and/or they can select submodules they need. - AI can dynamically check out a missing submodule at any point: `git submodule update --init `. @@ -369,7 +369,7 @@ Setup actions: - Create a new empty git repository to serve as the composite workspace envelope. - Clone each sub-repository (code, infra, QA, frontend, shared libraries, etc.) into the envelope as a plain folder. - Add each cloned folder to `.gitignore` so it is excluded from the envelope's git tracking. -- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace (see [Quick Start](QUICKSTART.md)). +- Initialize Rosetta in the envelope workspace, telling it this is a composite workspace (see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository)). --- @@ -402,3 +402,8 @@ The old code in `refsrc/` keeps its own `docs/CONTEXT.md` and `docs/ARCHITECTURE - Use `/requirements-authoring-flow` or `Allium` to generate specs from the existing old code. - Use `/coding-flow` for unit tests and `/ui-aqa-flow` for e2e tests to cover the old code before you change it. + +## Next Steps + +- [Workflows](USAGE_GUIDE.md#workflows) — choose and run the right Rosetta workflow. +- [Best Practices](USAGE_GUIDE.md#best-practices) — use the practices that improve workflow results. diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index dfc39261c..981efd9ae 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -70,7 +70,7 @@ fork/clone → branch → edit → validate → push → PR 5. **Test on DEV environment.** - Uninstall `local-files-mode.md` from target repository - [Publish to dev](#dev-environment-integration-testing) - - Enable Rosetta MCP or follow [Quick Start Guide](QUICKSTART.md) to install it + - Enable Rosetta MCP or follow [Installation](INSTALLATION.md) to install it - Use dev server URL `` - Test end-to-end through the HTTP MCP @@ -224,7 +224,7 @@ codex mcp add Rosetta \ **Pre-release builds:** Version suffixes like `b00` trigger automatic pre-release publishing. Use `--prerelease=allow` with uvx to pull these builds. -Add the bootstrap rule to your IDE as defined in [Quick Start — Add Bootstrap Rule](QUICKSTART.md#step-2-add-bootstrap-rule). +Add the bootstrap rule to your IDE as defined in [Installation — Add Bootstrap Rule](INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only). --- @@ -393,7 +393,7 @@ codex mcp add Rosetta --url Authenticate via OAuth as required. -Add the bootstrap rule to your IDE as defined in [Quick Start — Add Bootstrap Rule](QUICKSTART.md#step-2-add-bootstrap-rule). +Add the bootstrap rule to your IDE as defined in [Installation — Add Bootstrap Rule](INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only). ### 4. Test CLI changes @@ -439,7 +439,6 @@ Always publish the **entire** `/instructions` folder. Never subfolders or single The short version: - **README** — orientation, what and why -- **QUICKSTART** — zero to working setup - **PLUGINS** — install as a plugin (recommended) - **MCPs** — install via MCP (optional, secondary) - **OVERVIEW** — mental model, terminology @@ -620,7 +619,7 @@ Upgrading a workspace from R2 to R3 requires no structural migration — the fol - [Contributing](CONTRIBUTING.md) — fastest path to a merged PR - [Architecture](docs/ARCHITECTURE.md) — system structure, components, data flow -- [Quickstart](QUICKSTART.md) — zero to working setup +- [Quick Start](README.md#quick-start) — zero to working setup - [Overview](OVERVIEW.md) — mental model, key concepts - [Review Standards](REVIEW.md) — what reviewers verify - [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows diff --git a/FAQ.md b/FAQ.md index 90ca29935..b450c3224 100644 --- a/FAQ.md +++ b/FAQ.md @@ -17,7 +17,7 @@ If none of these are true, Rosetta is not active for this session. See [INSTALLA **How do I install Rosetta for the first time?** -See the [Quick Start Guide](QUICKSTART.md) for the fastest path, or [INSTALLATION.md](INSTALLATION.md) for the full setup including the fallback bootstrap rule. Once installed, [QUICKSTART.md](QUICKSTART.md) walks you through your first session. +See the [Quick Start](README.md#quick-start) for the fastest path, or [INSTALLATION.md](INSTALLATION.md) for the full setup including the fallback bootstrap rule. Once installed, follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository) for your first session. **Which Rosetta release should I use?** @@ -77,7 +77,7 @@ Pick a **medium** model — **Sonnet 5**, **GPT-5.6-terra-medium**, or **gemini- - **Running everything on a high-reasoning/Opus model.** Opus-class models spend heavily on reasoning and can exhaust a daily balance in one sitting. Rosetta already assigns an appropriate model per subagent and switches automatically, so you do not need to force the most expensive model for the whole session. - **Letting Auto pick the model.** Auto often downgrades to a weaker model mid-task, producing low-quality results. Choose the model explicitly. -See the model guidance in [QUICKSTART.md](QUICKSTART.md). +Use the model guidance in the [Model Selection](#model-selection) section above. **How do I reduce token cost?** diff --git a/INSTALLATION.md b/INSTALLATION.md index 27daf31a0..5a607810f 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -1,7 +1,7 @@ # Installation **Who is this for?** Complete setup reference for all installation modes. -**When should I read this?** When you need the full picture: plugins, offline, or the optional MCP modes (HTTP, STDIO) and their environment variables. For the fastest path, see [QUICKSTART.md](QUICKSTART.md). +**When should I read this?** When you need the full picture: plugins, offline, or the optional MCP modes (HTTP, STDIO) and their environment variables. For the fastest path, see the [Quick Start](README.md#quick-start). > [!CAUTION] > You must receive prior approval from your manager and company to use Rosetta. @@ -719,7 +719,7 @@ After initialization, Rosetta maintains these files in your repository. Read mor ## Related Docs - [PLUGINS.md](PLUGINS.md) - plugin contents and capabilities -- [QUICKSTART.md](QUICKSTART.md) - fastest path to a working setup +- [Quick Start](README.md#quick-start) - fastest path to a working setup - [MCPs.md](MCPs.md) - when and how to use the optional MCP path - [OVERVIEW.md](OVERVIEW.md) - mental model and terminology - [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - common issues and fixes diff --git a/MCPs.md b/MCPs.md index d6445f6be..bf9f72e23 100644 --- a/MCPs.md +++ b/MCPs.md @@ -204,7 +204,7 @@ It should use Rosetta MCP to retrieve agents, guardrails, and instructions: Once the MCP is verified: -- **Run your first session and initialize the repo** — see [QUICKSTART.md](QUICKSTART.md). +- **Run your first session and initialize the repo** — see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository). - **Explore the workflows** (coding, requirements authoring, modernization, and more) — see [USAGE_GUIDE.md — Workflows](USAGE_GUIDE.md#workflows). ## Links diff --git a/OVERVIEW.md b/OVERVIEW.md index 8e10639c7..d01d64ad5 100644 --- a/OVERVIEW.md +++ b/OVERVIEW.md @@ -111,7 +111,7 @@ Layers at the same resource path get merged: in Plugin mode, the generator merge ## Related Docs - [User Guide](user-guide/README.md) — using Rosetta day to day -- [Quick Start](QUICKSTART.md) — zero to working setup +- [Quick Start](README.md#quick-start) — zero to working setup - [Usage Guide](USAGE_GUIDE.md) — how to use Rosetta flows - [Contributing](CONTRIBUTING.md) — fastest path to a merged PR - [Architecture](docs/ARCHITECTURE.md) — system structure, components, data flow diff --git a/PLUGINS.md b/PLUGINS.md index 4ff12a991..b198b5343 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -160,5 +160,5 @@ See [INSTALLATION.md#upgrading](INSTALLATION.md#upgrading) for upgrade instructi Once the plugin is verified: - **Use Rosetta day to day** — see the [User Guide](user-guide/README.md). -- **Run your first session and initialize the repo** — see [QUICKSTART.md](QUICKSTART.md). +- **Run your first session and initialize the repo** — see [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository). - **Explore the workflows** (coding, requirements authoring, modernization, and more) — see [USAGE_GUIDE.md — Workflows](USAGE_GUIDE.md#workflows). diff --git a/QUICKSTART.md b/QUICKSTART.md deleted file mode 100644 index c2196c4af..000000000 --- a/QUICKSTART.md +++ /dev/null @@ -1,159 +0,0 @@ -# Quick Start - -**Who is this for?** New users setting up Rosetta for the first time. -**When should I read this?** When you want to go from zero to a working setup. - ---- - -> [!CAUTION] -> You must receive prior approval from your manager and company to use it. - -> [!WARNING] -> Use **Sonnet 5 medium**, **GPT-5.6-terra-medium**, **gemini-3.7-flash-high** or newer models. Please use **medium** reasoning effort or it will take 30 minutes in useless reasoning. Avoid Auto model selection. - -> [!NOTE] -> Rosetta is designed to never use or see data or IP. -> -> Instead it uses inversion of control, by providing a "menu" to AI coding agents. -> -> There will be conflict if you have similar plugins installed: JUXT, Superpowers, GSD, AI-DevKit. Use the ones you have the most experience with. - - -## Step 1: Install Rosetta - -| Option | Best for | -| ----------------------------------- | ------------------------------------------------------------------------------ | -| **[Plugins](PLUGINS.md)** — recommended | Everyone with a supported IDE (Claude Code · Cursor · Copilot · Codex · Antigravity). Files install locally — no server, no live connection needed. | -| **[Hosted MCP](MCPs.md)** — evaluation only | Try Rosetta with zero setup, or use any other MCP-compatible agent (Devin/Windsurf · Junie · OpenCode). Public demo endpoint — do not point production or sensitive repos at it. | -| **[Self-hosted MCP](docs/mcp/DEPLOYMENT_GUIDE.md)** — optional | MCP in production: your own MCP server and RAGFlow inside your perimeter. Only needed if you specifically require centrally-managed, always-fresh instructions with nothing copied into repos — most teams don't. | - -## Step 2: Initialize (once per repository and commit) - -Ask the agent: - -**Greenfield (new repository):** -``` -Initialize this repository using the respective Rosetta workflow, this is a new repository, target tech stack: ..., target architecture: ..., business context: ... -``` - -**Brownfield (existing repository):** - -Ask the agent to initialize the repository: - -``` -Initialize this repository using the respective Rosetta workflow -``` - -Optionally, add details to that same request. If your workspace contains multiple repositories: - -``` -Initialize this repository using the respective Rosetta workflow, this is a composite workspace -``` - -To tell the agent where dead code or existing specs live: - -``` -Initialize this repository using the respective Rosetta workflow, dead code is in , existing specs are in -``` - -The agent will analyze your tech stack, generate documentation (TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md, ARCHITECTURE.md, CONTEXT.md), and ask clarifying questions. Read more about [workspace files](INSTALLATION.md#workspace-files-created) and [all workflows](USAGE_GUIDE.md#workflows). - -> [!NOTE] -> **Prefer medium models:** High reasoning and Opus models consume too much token on reasoning. -> -> **Composite workspaces:** init each repository separately, then run the Brownfield form at the workspace level. -> -> **Dead code or existing specs:** mention their location in the prompt to save time. - -## Next Steps - -To properly set up an entire workspace, refer to [CONFIGURATION.md](CONFIGURATION.md). - -### Coding Workflow - -**WHAT**: Majority of tasks are actually coding tasks, including unit tests. Just ask exactly what is required. - -``` -/coding-flow Implement side bar on the home page, ... -``` - -``` -/coding-flow Identify and implement fix, ... -``` - -``` -/coding-flow Improve unit tests coverage to 85% for ... -``` - -### Business and Technical Requirements - -**WHY**: Requirements - is the source of truth for code and tests. Going requirements first is the most effective. In brownfield start with extracting. - -``` -/requirements-authoring-flow extract detailed business and technical requirements from community of ... using subagents. Additionally, ... . Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` - -``` -/requirements-authoring-flow extract high-level business and technical requirements at end-point level for controllers according to glob ... using subagents. Additionally, ... . Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` - -``` -/requirements-authoring-flow update existing requirements for so that it . Additionally, ... . Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` - -### Automated QA - -**WHAT**: Helps user go from a test case in Test Management System to a working test in the automation framework. Give it a test case, it gathers what it needs from your code and ticket system (for example, Jira) and AQA implements the automated test, asks questions when it sees contradictions, and helps fix the test until it passes. - -``` -/ui-aqa-flow Automate the test case for the checkout flow, ... -``` - -``` -/api-aqa-flow Implement automation for the API test cases in suite ..., ... -``` - -``` -/ui-aqa-flow Fix the failing automated test for ..., ... -``` - -### Modernization - -**FIRST**: Document modernization goals in CONTEXT.md, document target services technical aspects in ARCHITECTURE.md, document where source code should be created, keep refsrc populated with reference code source (old code, new code, reusable libraries, configuration and documentation files, and similar). - -**NOTE**: All phases are must. All phases to be implemented one-by-one with proper review. Phase 3: Pre-Modernization Test Coverage is a must (and must include both unit and integration/e2e tests). - -``` -/modernization-flow Perform modernization phase 1 to reuse library refsrc/... using subagents. -``` - -``` -/modernization-flow Perform modernization phase 2 to analyze service module ... using subagents. Target microservice name is ... . -``` - -``` -/modernization-flow Perform modernization phase 8 for target service to analyze service module ... using subagents. Must use `coding-flow.md` to actually implement and as the main flow. Once done spawn subagent to validate and repeat an entire loop until there are no issues detected. -``` - -### Save Tokens (Optional) - -Save cost — add the line below to your workspace AGENTS.md/CLAUDE.md to cut model output tokens: - -`MUST ALWAYS think, reason, plan, chat, document in compressed/terse/unicode chars/terms/always/no hieroglyphs; Exclude final artifacts, any tool calls, all code, etc.` - -To explore all workflows (coding, requirements authoring, modernization, and more), refer to [USAGE_GUIDE.md — Workflows](USAGE_GUIDE.md#workflows). - -## Links - -- [Usage Guide](USAGE_GUIDE.md) — see all Rosetta workflows -- [Overview](OVERVIEW.md) — mental model and terminology -- [Contributing](CONTRIBUTING.md) — make your first contribution -- [Architecture](docs/ARCHITECTURE.md) — system internals -- [Deployment Guide](docs/mcp/DEPLOYMENT_GUIDE.md) — self-hosted MCP (optional, rarely needed) - -## Video Tutorials - -- [Install without MCP](https://vimeo.com/1174124213/c50179147c?fl=ml&fe=ec) — limited internet access -- [Install Using MCP](https://vimeo.com/1174124251/f38e017d8d?fl=ml&fe=ec) — step-by-step setup -- [Initialize with Antigravity](https://vimeo.com/1174124165/8f5fbd7775?fl=ml&fe=ec) — project initialization -- [Subagents and Workflows in Claude Code](https://vimeo.com/1174124272/96056d5cc5?fl=ml&fe=ec) — advanced configuration diff --git a/README.md b/README.md index 99adf370a..61512ad1f 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,13 @@ Rosetta-guided work follows five phases — **Prepare → Research → Plan → Read more in the [User Guide](user-guide/README.md). -## [Quick Start](QUICKSTART.md) +## Quick Start -Overall Process: **Install** (plugin preferred) → **Initialize** workspace → **Configure** workspace ecosystem (tools, MCPs) → **Proceed** with Coding, Modernization, Analysis, etc. +**Install** Rosetta: use [PLUGINS.md](PLUGINS.md) when your IDE supports a plugin, or [MCPs.md](MCPs.md) when you need MCP. For every mode and the bootstrap fallback, see [INSTALLATION.md](INSTALLATION.md). -Please follow **[Quick Start Guide](QUICKSTART.md)** which will walk you through the process. +**Initialize** the repository once: follow [Installation — Initialize Repository](INSTALLATION.md#step-4-initialize-repository). -Very detailed information on installation and configuration in all available modes is in [Installation Guide](INSTALLATION.md). +**Configure** its context and tooling: use [CONFIGURATION.md](CONFIGURATION.md). Then use the [Usage Guide](USAGE_GUIDE.md) for coding, modernization, analysis, and other workflows. ## [Top Workflows](USAGE_GUIDE.md#workflows) @@ -217,7 +217,7 @@ Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for workflow and e | I want to... | Read | | ---------------------------------------------------- | ------------------------------------------ | | Use Rosetta day to day | [User Guide](user-guide/README.md) | -| Set up Rosetta | [QUICKSTART.md](QUICKSTART.md) | +| Set up Rosetta | [Quick Start](#quick-start) | | Install as a plugin (recommended) | [PLUGINS.md](PLUGINS.md) | | Connect over MCP (optional, secondary) | [MCPs.md](MCPs.md) | | Configure your coding-agent workspace | [CONFIGURATION.md](CONFIGURATION.md) | diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 5ce212166..9a1e84081 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -11,7 +11,7 @@ Most sections below are MCP-specific (connection, OAuth, server issues) — if y **OAuth prompt does not appear** - Restart your IDE and retry the connection -- Confirm your IDE supports HTTP MCP transport (see [QUICKSTART.md](QUICKSTART.md)) +- Confirm your IDE supports HTTP MCP transport (see [MCPs — Connect Rosetta MCP](MCPs.md#step-1-connect-rosetta-mcp)) - Some IDEs require manually triggering auth (Claude Code: `/mcp` > select Rosetta > Authenticate) **MCP server shows as disconnected** @@ -35,7 +35,7 @@ Most sections below are MCP-specific (connection, OAuth, server issues) — if y **If you installed via MCP (agent ignores Rosetta tools entirely):** - Confirm the MCP server shows as connected in your IDE's MCP settings - Add a [bootstrap rule](INSTALLATION.md) to your project. This is the universal fallback for any IDE or agent that doesn't reliably read MCP server prompts -- Download [mcp-files-mode.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r3/core/rules/mcp-files-mode.md?plain=1) and place it in your IDE's instruction file (see [QUICKSTART.md](QUICKSTART.md) Step 2 for paths) +- Download [mcp-files-mode.md](https://github.com/griddynamics/rosetta/blob/main/instructions/r3/core/rules/mcp-files-mode.md?plain=1) and place it in your IDE's instruction file (see [Installation — Add Bootstrap Rule](INSTALLATION.md#step-2-add-bootstrap-rule-http-and-stdio-modes-only) for paths) **Agent used Rosetta before but stopped (MCP)** - Check re-authentication (see above) @@ -43,7 +43,7 @@ Most sections below are MCP-specific (connection, OAuth, server issues) — if y - Re-add the bootstrap rule if it was removed **Untested IDE or agent** -- Not every IDE/agent has been validated with Rosetta. If yours isn't listed in [QUICKSTART.md](QUICKSTART.md), it may not invoke MCP tools reliably +- Not every IDE or agent has been validated with Rosetta. If its MCP configuration is not listed in [MCPs — Connect Rosetta MCP](MCPs.md#step-1-connect-rosetta-mcp), it may not invoke MCP tools reliably - The bootstrap rule works as a fallback for any agent that reads project-level instruction files - If neither MCP nor bootstrap works, your IDE/agent may not support the required capabilities. Open an [issue](https://github.com/griddynamics/rosetta/issues) diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md index c854f9312..517cd9eec 100644 --- a/USAGE_GUIDE.md +++ b/USAGE_GUIDE.md @@ -2,9 +2,9 @@ **Who is this for?** Engineers, leads, and architects using Rosetta in their daily work. -**When should I read this?** After [QUICKSTART.md](QUICKSTART.md). When you want to understand what Rosetta offers and how to use each flow. +**When should I read this?** After the [Quick Start](README.md#quick-start). When you want to understand what Rosetta offers and how to use each flow. -For terminology and mental model, see [OVERVIEW.md](OVERVIEW.md). For setup, see [QUICKSTART.md](QUICKSTART.md) or [INSTALLATION.md](INSTALLATION.md). +For terminology and mental model, see [OVERVIEW.md](OVERVIEW.md). For setup, see the [Quick Start](README.md#quick-start) or [INSTALLATION.md](INSTALLATION.md). --- @@ -183,6 +183,8 @@ Use this before building when expected behavior is unclear, high impact, or need ``` /requirements-authoring-flow Define requirements for the checkout flow covering discount codes, tax, and retries /requirements-authoring-flow Write requirements for the user onboarding experience +/requirements-authoring-flow Extract detailed business and technical requirements from the payment service using subagents. Once done, spawn a subagent to validate and repeat the entire loop until there are no issues detected. +/requirements-authoring-flow Update existing requirements for so that it . Once done, spawn a subagent to validate and repeat the entire loop until there are no issues detected. ```
@@ -368,9 +370,14 @@ Large migration workflow for code conversions, platform upgrades, framework upgr **Expect:** heavy subagent use, often one focused subagent per phase or project. HITL confirms applicable phases, phase transitions, target-spec approval, public API changes, and implementation start. Your responsibility is to provide source/target expectations, compatibility requirements, test expectations, deployment constraints, and careful spec review. +Before starting, complete [Modernization Additional Setup](CONFIGURATION.md#4-modernization-additional-setup). Phase 3 is optional and requires explicit approval. + ``` /modernization-flow Re-architect monolith to microservices /modernization-flow Migrate the billing module from Java 8 to Java 21, one phase at a time +/modernization-flow Perform modernization phase 1 to reuse library refsrc/... using subagents. +/modernization-flow Perform modernization phase 2 to analyze service module ... using subagents. Target microservice name is ... . +/modernization-flow Perform modernization phase 8 for target service to analyze service module ... using subagents. Must use coding-flow as the main flow. Once done, spawn a subagent to validate and repeat the entire loop until there are no issues detected. ``` @@ -669,6 +676,7 @@ See [PLUGINS.md](PLUGINS.md) for install commands. - **Be specific.** More context means better output and fewer questions. `/requirements-authoring-flow Define requirements for the checkout flow covering discount codes, tax calculation, and payment retries` beats `/requirements-authoring-flow Write requirements for checkout.` - **Read plans before approving.** The plan is your last checkpoint before work begins. Check scope, approach, and what will change. - **Answer questions fully.** When Rosetta asks, it targets a specific gap. Short answers lead to incomplete solutions. +- **Use focused subagents and independent validation loops.** Give each subagent one bounded responsibility. After implementation, use a separate subagent to validate the result and repeat the loop until no issues remain. - **Write requirements first.** The requirements workflow prevents scope creep and gives you a clear acceptance baseline. - **Invest in context files.** CONTEXT.md and ARCHITECTURE.md benefit every developer on the project. - **Point Rosetta at existing specs.** Reference requirements, API contracts, or design documents in CONTEXT.md. Rosetta uses them as constraints instead of generating assumptions. @@ -739,7 +747,7 @@ These videos were recorded in different IDEs to show that Rosetta works everywhe ## Related Docs - [Overview](OVERVIEW.md) — mental model and terminology -- [Quick Start](QUICKSTART.md) — zero to working setup +- [Quick Start](README.md#quick-start) — zero to working setup - [Installation](INSTALLATION.md) — all setup modes and environment variables - [Architecture](docs/ARCHITECTURE.md) — system structure, components, data flow - [Contributing](CONTRIBUTING.md) — fastest path to a merged PR diff --git a/docs/CODEMAP.md b/docs/CODEMAP.md index 94fdb6e8d..227431ed6 100644 --- a/docs/CODEMAP.md +++ b/docs/CODEMAP.md @@ -2,7 +2,7 @@ Code map of the Rosetta workspace — modules, key files, and entry points, 3-4 ## / — repo root (519 files total) -README.md OVERVIEW.md QUICKSTART.md USAGE_GUIDE.md DEVELOPER_GUIDE.md CONTRIBUTING.md +README.md OVERVIEW.md USAGE_GUIDE.md DEVELOPER_GUIDE.md CONTRIBUTING.md INSTALLATION.md TROUBLESHOOTING.md REVIEW.md SECURITY.md CHANGELOG.md AGENTS.md NOTICE LICENSE requirements.txt mypy.ini src/validate-types.sh @@ -36,14 +36,14 @@ instructions.py projects.py resources.py execution_controller.py feedback.py val tracker.py user_context.py -### src/rosetta-mcp-server/tests/ — unit tests (21 files) +### src/rosetta-mcp-server/tests/ — unit tests (22 files) test_bundler_and_query_builder.py test_instructions.py test_execution_controller.py test_oauth.py test_analytics.py test_authorizer.py test_migrations.py test_resources.py test_tool_contracts.py test_prompts.py test_validation.py test_config.py test_cache_ttl.py test_dataset_lookup.py test_document_client.py test_feedback_service.py test_keyword_search.py test_invite.py test_origin_middleware.py test_project_naming.py -conftest.py +test_compatibility_notice.py conftest.py ### src/rosetta-mcp-server/validation/ — integration / end-to-end testing diff --git a/docs/CONTEXT.md b/docs/CONTEXT.md index f3201a40b..22a7d6fa1 100644 --- a/docs/CONTEXT.md +++ b/docs/CONTEXT.md @@ -144,7 +144,7 @@ These principles shape every product and architectural decision: - [Developer Guide](../DEVELOPER_GUIDE.md): Repo navigation, where to change what - [Contributing](../CONTRIBUTING.md): Fastest path to merged PR - [Review](../REVIEW.md): What reviewers verify, what authors provide -- [Quickstart](../QUICKSTART.md): Zero to working setup +- [Quick Start](../README.md#quick-start): Zero to working setup - [Usage Guide](../USAGE_GUIDE.md): How to use Rosetta day-to-day - [Deployment Guide](mcp/DEPLOYMENT_GUIDE.md): Self-hosted MCP server and infrastructure setup (optional, rarely needed) - [Troubleshooting](../TROUBLESHOOTING.md): Symptom-first diagnosis diff --git a/docs/mcp/DEPLOYMENT_GUIDE.md b/docs/mcp/DEPLOYMENT_GUIDE.md index 22a6fa8df..88a3e3341 100644 --- a/docs/mcp/DEPLOYMENT_GUIDE.md +++ b/docs/mcp/DEPLOYMENT_GUIDE.md @@ -1,7 +1,7 @@ # Deployment Guide **Who is this for?** Engineers deploying self-hosted Rosetta MCP infrastructure for their organization. This is optional — only needed if you specifically require centrally-managed instructions or an IDE with no Rosetta plugin; most teams should use [Plugins](../../PLUGINS.md) instead. -**When should I read this?** When you've decided you need self-hosted MCP and want to stand up Rosetta Server (RAGFlow) and Rosetta MCP for your team. For single-user setup, see [QUICKSTART.md](../../QUICKSTART.md). For client/IDE configuration, see [INSTALLATION.md](../../INSTALLATION.md). +**When should I read this?** When you've decided you need self-hosted MCP and want to stand up Rosetta Server (RAGFlow) and Rosetta MCP for your team. For single-user setup, see the [Quick Start](../../README.md#quick-start). For client/IDE configuration, see [INSTALLATION.md](../../INSTALLATION.md). > [!WARNING] > **Never expose RAGFlow or Rosetta MCP directly to the internet.** Always place an API gateway, reverse proxy, or firewall in front of both services. Both have application-level authentication (RAGFlow: user accounts, OIDC/SSO, API keys; Rosetta MCP: OAuth 2.1), but network-level protection is still required as a defense-in-depth measure. @@ -527,7 +527,7 @@ Production deploys require a manual image tag bump in `values-prod.yaml`. ## Related Docs -- [QUICKSTART.md](../../QUICKSTART.md) - single-user setup (zero to working in minutes) +- [Quick Start](../../README.md#quick-start) - single-user setup (zero to working in minutes) - [INSTALLATION.md](../../INSTALLATION.md) - client/IDE configuration, all transport modes - [docs/ARCHITECTURE.md](../ARCHITECTURE.md) - system structure and component relationships - [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md) - common issues and fixes diff --git a/docs/reviews/DOC-STRUCTURE-PLAN.md b/docs/reviews/DOC-STRUCTURE-PLAN.md index 45a346dcf..32bf7ce81 100644 --- a/docs/reviews/DOC-STRUCTURE-PLAN.md +++ b/docs/reviews/DOC-STRUCTURE-PLAN.md @@ -6,7 +6,7 @@ Each doc answers one question for one reader at one moment. If a file answers tw Four reader types. Every doc serves one primary profile. README is the shared front door that routes all four. -- **User** — wants to use Rosetta on their own project. The primary audience. Path: README → QUICKSTART → install (PLUGINS — recommended / MCPs — optional, secondary / INSTALLATION — full reference) → CONFIGURATION → USAGE_GUIDE, with FAQ and TROUBLESHOOTING for support. +- **User** — wants to use Rosetta on their own project. The primary audience. Path: README → install (PLUGINS — recommended / MCPs — optional, secondary / INSTALLATION — full reference) → CONFIGURATION → USAGE_GUIDE, with FAQ and TROUBLESHOOTING for support. - **AI** — a coding agent reading the repo to learn Rosetta. Path: README points it to `llms-full.txt`, one dense machine-readable source. - **Contributor** — develops for Rosetta. Path: CONTRIBUTING → OVERVIEW → CONTEXT → ARCHITECTURE → DEVELOPER_GUIDE → REVIEW. MCP-CONTEXT and MCP-ARCHITECTURE are optional deep-dives reached from CONTEXT/ARCHITECTURE, not separate stops on the main path. - **Organization** — wants to roll out Rosetta company-wide. For nearly all organizations this is the User path at scale (plugins distributed via IDE marketplaces) — no server to deploy. Path: INSTALLATION → docs/mcp/DEPLOYMENT_GUIDE → SECURITY exists only for the rare organization that specifically needs self-hosted, centrally-managed MCP; reuses ARCHITECTURE/MCP-ARCHITECTURE. @@ -15,7 +15,6 @@ Four reader types. Every doc serves one primary profile. README is the shared fr |---|---|---|---| | `README.md` | Orientation + route to the right doc. | Anyone landing on the repo. | Front door (all) | | `ELEVATOR_PITCH.md` | 30-second pitch for the unconvinced. | Someone asked "what is Rosetta?" in a hallway. | User | -| `QUICKSTART.md` | Fastest path to a working setup. | A user who decided to try it. | User | | `INSTALLATION.md` | Complete setup reference, all modes and transports. | A user or org with a non-default setup. | User + Organization | | `PLUGINS.md` | Plugin install path, per IDE. Recommended default; never mentions MCP. | Users on the plugin install route (nearly everyone). | User | | `MCPs.md` | MCP install path — optional, secondary. | Users with no plugin path for their IDE, or a specific centrally-managed-instructions need. | User | @@ -47,7 +46,7 @@ Four reader types. Every doc serves one primary profile. README is the shared fr - **Answers:** "What is this, and where do I go next?" - **Owns:** one-paragraph what-it-is, the value proposition in brief, the routing table ("I want to… → read X"), community/license pointers. - **Structure:** badges/hero → one-line what-it-is → value proposition → Quick Start teaser (links out) → "I want to… → read X" routing table → who-it's-for → community/license. -- **Excludes:** full install steps (→ QUICKSTART/INSTALLATION), mental model and concepts (→ OVERVIEW), workflow how-tos (→ USAGE_GUIDE). +- **Excludes:** full install steps (→ INSTALLATION), mental model and concepts (→ OVERVIEW), workflow how-tos (→ USAGE_GUIDE). - **Sources:** ELEVATOR_PITCH + OVERVIEW (value prop), the live doc set (routing table), PyPI badges (`rosetta-mcp`, `rosetta-cli`). ### OVERVIEW.md @@ -56,7 +55,7 @@ Four reader types. Every doc serves one primary profile. README is the shared fr - **Answers:** "How should I think about Rosetta? What does it do and not do?" - **Owns:** problem statement, core mental model, key concepts/terminology, session lifecycle, the "what Rosetta does not do" boundary. - **Structure:** problem statement → core mental model → key concepts/terminology → session lifecycle → "what Rosetta does not do". -- **Excludes:** install/setup steps (→ INSTALLATION/QUICKSTART), per-workflow how-tos (→ USAGE_GUIDE), code-level internals (→ ARCHITECTURE/DEVELOPER_GUIDE). +- **Excludes:** install/setup steps (→ README/INSTALLATION), per-workflow how-tos (→ USAGE_GUIDE), code-level internals (→ ARCHITECTURE/DEVELOPER_GUIDE). - **Sources:** ELEVATOR_PITCH (why), `workflows/` + `skills/` (concepts/terminology), ARCHITECTURE (session lifecycle). ### docs/CONTEXT.md @@ -83,18 +82,9 @@ Four reader types. Every doc serves one primary profile. README is the shared fr - **Answers:** "Why does this exist, in 30 seconds?" - **Owns:** the pitch — problem, solution, one-line core idea, proof. - **Structure:** hook/problem → solution in one line → how it helps → proof/outcome. -- **Excludes:** setup/how-to (→ QUICKSTART), conceptual depth (→ OVERVIEW), feature reference (→ USAGE_GUIDE). +- **Excludes:** setup/how-to (→ README), conceptual depth (→ OVERVIEW), feature reference (→ USAGE_GUIDE). - **Sources:** the value-proposition deck/slide, README intro, real proof points/metrics. -### QUICKSTART.md -- **Profile:** User. -- **Audience:** a user who decided to try it and wants it working now. -- **Answers:** "Minimum steps to a working setup?" -- **Owns:** install one-liner, initialize-once step, a short "next steps" pointing into the workflows. Happy path only. -- **Structure:** prerequisites → install one-liner → initialize once → run your first workflow → next steps (links into CONFIGURATION/USAGE_GUIDE). -- **Excludes:** exhaustive install modes/transports (→ INSTALLATION), workspace configuration (→ CONFIGURATION), per-workflow detail (→ USAGE_GUIDE). -- **Sources:** INSTALLATION (canonical steps), PLUGINS/MCPs (install routes), the actual init prompt/command. - ### INSTALLATION.md - **Profile:** User + Organization. - **Audience:** a user whose setup is non-default (HTTP/STDIO, offline, specific IDE). @@ -128,7 +118,7 @@ Four reader types. Every doc serves one primary profile. README is the shared fr - **Answers:** "How do I set up my workspace so Rosetta works well here?" - **Owns:** capturing CONTEXT.md / ARCHITECTURE.md, providing refsrc, defining patterns, choosing a workspace layout, ecosystem config. - **Structure:** capture CONTEXT.md / ARCHITECTURE.md → provide refsrc → define patterns → choose a workspace layout → ecosystem (MCPs/CLIs) config. -- **Excludes:** install steps (→ INSTALLATION), first-run happy path (→ QUICKSTART), running workflows (→ USAGE_GUIDE), migration principles/prompts (→ docs/MODERNIZATION.md). +- **Excludes:** install steps and first-run happy path (→ README/INSTALLATION), running workflows (→ USAGE_GUIDE), migration principles/prompts (→ docs/MODERNIZATION.md). - **Sources:** `gain.json` schema, the Rosetta file set (CONTEXT.md / ARCHITECTURE.md / refsrc), pattern templates. ### USAGE_GUIDE.md @@ -279,7 +269,6 @@ flowchart TD subgraph USER["User — use Rosetta"] ELEV["ELEVATOR_PITCH"] - QS["QUICKSTART"] PLUG["PLUGINS
(recommended)"] MCP["MCPs
(optional, secondary)"] INST["INSTALLATION"] @@ -308,19 +297,17 @@ flowchart TD SEC["SECURITY"] end - README -->|user| QS + README -->|user| PLUG + README -.->|no plugin path, or
specific MCP need| MCP + README --> INST README -.-> ELEV README -->|AI| LLMS README -->|contributor| CONT README -.->|organization,
only if self-hosting| INSTO - ELEV --> QS - QS --> PLUG - QS -.->|no plugin path, or
specific MCP need| MCP - QS --> INST + ELEV --> README PLUG --> INST MCP -.-> INST - QS --> CONF INST --> CONF CONF --> USAGE USAGE <--> FAQ @@ -344,7 +331,7 @@ flowchart TD classDef org fill:#b45309,stroke:#5a2900,color:#ffffff; class README entry; - class ELEV,QS,PLUG,MCP,INST,CONF,USAGE,FAQ,TRBL user; + class ELEV,PLUG,MCP,INST,CONF,USAGE,FAQ,TRBL user; class LLMS ai; class CONT,OVER,CTX,ARCH,DEV,REV contrib; class INSTO,DEP,SEC org; @@ -352,14 +339,10 @@ flowchart TD --- -## 5. Known overlaps to clarify at the sync - -Observed today, stated as boundary questions — not deletion proposals. These are the concrete "who owns this fact" decisions to make with Igor. - -1. **Setup steps** appear in QUICKSTART, INSTALLATION, CONFIGURATION, and USAGE_GUIDE. Decide the owner per step: install → INSTALLATION, first-run init → QUICKSTART, workspace setup → CONFIGURATION. Others link. -2. **Bootstrap rule + verify** are spelled out in INSTALLATION, PLUGINS, and MCPs. Decide whether INSTALLATION owns the canonical version and the two children link to it. -3. **FAQ vs TROUBLESHOOTING** boundary: FAQ = "is this expected?", TROUBLESHOOTING = "fix this break". Sort each existing entry into one. -4. **README length:** README currently carries a Quick Start section *and* links to QUICKSTART. Decide whether README keeps a 3-line teaser that links out, or the inline steps. (This is the exact Yuriy↔Igor disagreement — resolving #1 resolves it.) -5. **Video tutorial + links blocks** are repeated across QUICKSTART, MCPs, USAGE_GUIDE. Decide one owner (likely USAGE_GUIDE) and link from the rest. +## 5. Resolved ownership -Resolving overlap #1 dissolves most of the others, because nearly all of them are the same setup facts written in more than one place. +- **README** owns the concise quick-start route: install, initialize, configure, then use. +- **INSTALLATION** owns complete installation, bootstrap, and initialization instructions. +- **CONFIGURATION** owns post-install workspace setup and routes configured users to workflow guidance. +- **USAGE_GUIDE** owns workflow examples, focused-subagent validation practice, and video tutorials. +- **FAQ** answers expected-behavior questions; **TROUBLESHOOTING** addresses failures. diff --git a/src/rosetta-mcp-server/rosetta_mcp/constants.py b/src/rosetta-mcp-server/rosetta_mcp/constants.py index d0b7d2321..aad48a8f3 100644 --- a/src/rosetta-mcp-server/rosetta_mcp/constants.py +++ b/src/rosetta-mcp-server/rosetta_mcp/constants.py @@ -94,7 +94,7 @@ XML_FRONTMATTER_CLOSE = "" XML_CONTENT_NOT_LOADED = "" -COMPATIBILITY_MODE_UPGRADE_URL = "https://github.com/griddynamics/rosetta/blob/main/QUICKSTART.md" +COMPATIBILITY_MODE_UPGRADE_URL = "https://github.com/griddynamics/rosetta/blob/main/MCPs.md" COMPATIBILITY_MODE_UPGRADE_NOTICE = ( "\n\n" "\nThis Rosetta MCP is running in legacy compatibility mode." diff --git a/src/rosetta-mcp-server/tests/test_compatibility_notice.py b/src/rosetta-mcp-server/tests/test_compatibility_notice.py new file mode 100644 index 000000000..1c7e148f7 --- /dev/null +++ b/src/rosetta-mcp-server/tests/test_compatibility_notice.py @@ -0,0 +1,7 @@ +"""Tests for the legacy compatibility-mode notice.""" + +from rosetta_mcp.constants import COMPATIBILITY_MODE_UPGRADE_NOTICE + + +def test_compatibility_notice_links_to_mcps_guide(): + assert "https://github.com/griddynamics/rosetta/blob/main/MCPs.md" in COMPATIBILITY_MODE_UPGRADE_NOTICE