Developer Guide

Who is this for? Active contributors and maintainers. When should I read this? After CONTRIBUTING.md. Before making your first change.

Overall Development Flow

Prepare local Rosetta repository.
- Fork repository entirely and work in the main branch
- Clone and create feature branch from the main branch
- Rosetta uses main as target branch for PR
- See Contributing Workflow for git-related info
Develop Rosetta using claude code / codex / cursor or Use the prompting flow.
- Development: existing rules will kick in, we use HTTP MCP, everything is preconfigured using claude standards. The repo's .mcp.json pre-configures Claude Code to connect to the dev MCP endpoint (rosetta-dev.example.com/mcp) — this is intentional so contributors see their in-progress instruction changes reflected immediately. End users connect to the production endpoint instead.
- Prompting: use the coding-agents-prompting-flow (description + examples) to author, refactor, or harden prompts.
Check your output.
Test locally on a target repo.
- Disable Rosetta MCP
- Set up Local Instructions Mode on target repository.
- Test your prompts against on a real codebase.
- Modify your prompts in instructions in target repository
- Restart coding agents or new sessions after changes made
- Copy back changed files to the Rosetta repository
Test on DEV environment.
- Uninstall local-files-mode.md from target repository
- Publish to dev
- Enable Rosetta MCP or follow Quick Start Guide to install it
- Use dev server URL <rosetta MCP development server URL>
- Test end-to-end through the HTTP MCP
Open a PR.
- Follow the Pull Request Checklist
- Prompting: include a prompt brief, before/after examples, and validation evidence
- Coding: include tests and validation changes
- All: update documentation, including web site
Pipelines.
- Automated pipelines will execute
- Static AI review and scenario comparison
- Both must pass

Repository Layout

rosetta/
├── instructions/         ← Prompts: skills, agents, workflows, rules, templates
│   └── r2/
│       ├── core/         ← OSS foundation
│       └── <org>/        ← Organization extensions (e.g., grid/)
├── ims-mcp-server/       ← Rosetta MCP server (PyPI: ims-mcp)
│   ├── ims_mcp/          ← Server source code
│   ├── tests/            ← Unit tests (pytest)
│   └── validation/       ← verify_mcp.py integration test
├── rosetta-cli/          ← Rosetta CLI package (PyPI: rosetta-cli)
│   ├── rosetta_cli/      ← CLI source package
│   ├── pyproject.toml    ← Package metadata + entrypoints
│   └── tests/            ← CLI unit tests
├── deployment/           ← Helm charts (RAGFlow)
├── plugins/              ← IDE plugin definitions
├── docs/                 ← Deep documentation (Architecture, RAGFlow, Context)
│   └── web/              ← Jekyll website (GitHub Pages)
└── refsrc/               ← Reference sources (read-only, resolves AI stale knowledge)

Prerequisites

Python 3.12+
uvx (included with uv)
Podman or Docker (optional, for Redis, used by full MCP plan_manager tests)

Local Development: Instructions

Use this when editing prompts (skills, agents, workflows, rules, templates).

Instructions run locally without MCP.

Copy them into a target repository and point your IDE using the local-files-mode.md bootstrap file.

Follow Offline Installation, except you copy your new instructions files:

  cp -r instructions/ /path/to/target-repo/instructions/

No server, no API key, no network. Edit instructions, reload, test.

Local Development: MCP

Use this when changing MCP server code, tool prompts, or bundler logic.

Run MCP locally in STDIO mode against the dev RAGFlow instance.

Redis (optional, for plan_manager)

Start a Redis-compatible container:

# Podman
podman run -d --name rosetta-redis -p 6379:6379 docker.io/valkey/valkey:latest

# Docker
docker run -d --name rosetta-redis -p 6379:6379 valkey/valkey:latest

Connect your IDE to local MCP

Claude Code:

claude mcp add --transport stdio Rosetta \
  --env ROSETTA_SERVER_URL=https://<developement server URL>/ \
  --env ROSETTA_API_KEY=ragflow-xxxxx \
  --env VERSION=r2 \
  --env REDIS_URL=redis://localhost:6379/0 \
  -- uvx --prerelease=allow ims-mcp@latest

Codex:

codex mcp add Rosetta \
  --env ROSETTA_SERVER_URL=https://<developement server URL>/ \
  --env ROSETTA_API_KEY=ragflow-xxxxx \
  --env VERSION=r2 \
  --env REDIS_URL=redis://localhost:6379/0 \
  -- uvx --prerelease=allow ims-mcp@latest

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["--prerelease=allow", "ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://<developement server URL>/",
        "ROSETTA_API_KEY": "ragflow-xxxxx",
        "VERSION": "r2",
        "REDIS_URL": "redis://localhost:6379/0"
      }
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--prerelease=allow", "ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://<developement server URL>/",
        "ROSETTA_API_KEY": "ragflow-xxxxx",
        "VERSION": "r2",
        "REDIS_URL": "redis://localhost:6379/0"
      }
    }
  }
}

API key: Get yours from the RAGFlow UI. The dataset you test against must be owned by user of this API key.

VERSION: Set explicitly here for local development testing. Always test with both VERSION=r1 and VERSION=r2.

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.

Local Development: CLI

Use this when changing publish, verify, or cleanup commands.

python3 -m venv venv
venv/bin/pip install -r requirements.txt
cp .env.dev .env  # Points at dev RAGFlow instance
venv/bin/rosetta-cli verify

Use two stages when developing the CLI: first test your checkout from the repo virtualenv, then test the packaged CLI with uvx after push/merge.

Preview changes without publishing:

cd rosetta-cli
../venv/bin/python -m rosetta_cli version
../venv/bin/python -m rosetta_cli verify --env dev
../venv/bin/python -m rosetta_cli publish ../instructions --dry-run --env dev

After the package is published, test the packaged CLI with uvx:

uvx rosetta-cli@latest verify --env dev
uvx rosetta-cli@latest publish ../instructions --dry-run --env dev

The --dry-run flag shows what would be published (new, changed, unchanged files) without writing anything to RAGFlow.

Validation

MCP integration tests

# From repo root, with the root venv activated
cp .env.dev .env && VERSION=r1 venv/bin/python ims-mcp-server/validation/verify_mcp.py
cp .env.dev .env && VERSION=r2 venv/bin/python ims-mcp-server/validation/verify_mcp.py

# With Redis (tests plan_manager with RedisPlanStore)
cp .env.dev .env && REDIS_URL="redis://localhost:6379/0" VERSION=r2 venv/bin/python ims-mcp-server/validation/verify_mcp.py

Run both r1 and r2. If your change touches Redis-dependent features, run with and without REDIS_URL.

Unit tests

# MCP server tests
venv/bin/pytest ims-mcp-server/tests

# CLI tests
venv/bin/pytest rosetta-cli/tests

Type checking

./validate-types.sh

Run this after any Python code change.

Git pre-commit hook

The repository ships a native Git pre-commit hook shim in .githooks/pre-commit. It runs the Python entrypoint at scripts/pre_commit.py, which first regenerates plugin payloads and then executes type validation. The generated plugin trees are:

plugins/core-claude — mirrored from instructions/r2/core with Claude model: frontmatter normalized to opus, sonnet, haiku, or inherit
plugins/core-cursor — mirrored from instructions/r2/core without model rewriting

Use the root repo virtualenv for hook execution:

python3 -m venv venv
venv/bin/pip install -r requirements.txt
git config core.hooksPath .githooks

Git does not automatically use the repository's .githooks/ directory. Each developer must run git config core.hooksPath .githooks once in their local clone to enable the native pre-commit hook.

On Windows, use the matching root-venv interpreter and pip executable:

py -3 -m venv venv
venv\Scripts\pip.exe install -r requirements.txt
git config core.hooksPath .githooks

You can test the hook entrypoint directly:

venv/bin/python scripts/pre_commit.py

Dev Environment: Integration Testing

After local validation passes, test end-to-end against the dev environment.

Environments (two separate servers):

Rosetta Server (RAGFlow) prod: https://<production server URL>/ — document engine backend, dataset management, API keys
Rosetta Server (RAGFlow) dev: https://<developement server URL>/ — used by STDIO MCP and CLI for publishing
Rosetta HTTP MCP prod: <rosetta MCP production server URL> — production MCP endpoint for end users
Rosetta HTTP MCP dev: <rosetta MCP development server URL> — dev MCP endpoint for integration testing

1. Publish instructions to dev

cp .env.dev .env
uvx rosetta-cli@latest publish instructions

This publishes to the dev RAGFlow instance. Only changed files are uploaded (MD5-based change detection). Use --force to republish everything.

2. Test MCP (STDIO against dev)

Connect your IDE using the STDIO configs from Local Development: MCP. This validates that your published instructions are served correctly through the MCP layer.

3. Test Instructions from MCP (HTTP, default mode)

This is the mode end users run. Connect your IDE to the hosted dev MCP endpoint over HTTP.

Claude Code — the repo's .mcp.json already contains this config; no extra setup needed:

claude mcp add --transport http Rosetta <rosetta MCP development server URL>

Codex:

codex mcp add Rosetta --url <rosetta MCP development server URL>

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "Rosetta": {
      "url": "<rosetta MCP development server URL>"
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "Rosetta": {
      "type": "http",
      "url": "<rosetta MCP development server URL>"
    }
  }
}

Authenticate via OAuth as required.

Add the bootstrap rule to your IDE as defined in Quick Start — Add Bootstrap Rule.

4. Test CLI changes

If you changed CLI commands, first test the checkout from source with the repo virtualenv:

cd rosetta-cli
../venv/bin/python -m rosetta_cli publish ../instructions --dry-run --env dev
../venv/bin/python -m rosetta_cli publish ../instructions --env dev
../venv/bin/python -m rosetta_cli list-dataset --dataset aia-r2 --env dev

After push/merge and package publish, repeat the same checks through the published package:

uvx rosetta-cli@latest publish instructions --dry-run --env dev
uvx rosetta-cli@latest publish instructions --env dev
uvx rosetta-cli@latest list-dataset --dataset aia-r2 --env dev

Where to Change What

Change type	Location	Validation
New/modified skill	`instructions/r2/core/skills/<name>/SKILL.md`	Publish, test via MCP
New/modified agent	`instructions/r2/core/agents/<name>.md`	Publish, test via MCP
New/modified workflow	`instructions/r2/core/workflows/<name>.md`	Publish, test via MCP
New/modified rule	`instructions/r2/core/rules/<name>.md`	Publish, test via MCP
Organization extension	`instructions/r2/<org>/` (same type structure)	Publish, test via MCP
MCP tool or prompt	`ims-mcp-server/ims_mcp/server.py`, `tool_prompts.py`	verify_mcp.py, pytest, validate-types.sh
CLI command	`rosetta-cli/rosetta_cli/commands/`	pytest, dry-run, publish to dev
Website	`docs/web/`	Local Jekyll build
Documentation	`docs/`, repo root `.md` files	Use AI to check consistency

Always publish the entire /instructions folder. Never subfolders or single files (breaks tag extraction). See Architecture — Rosetta CLI for details on auto-tagging and change detection.

How Documentation Is Organized

See plan/INDEX.md for the full document routing map. The short version:

README — orientation, what and why
QUICKSTART — zero to working setup
OVERVIEW — mental model, terminology
CONTRIBUTING — PR workflow, checklist
DEVELOPER_GUIDE (this doc) — repo navigation, local dev
docs/ARCHITECTURE — system structure, components, data flow
REVIEW — what reviewers check
USAGE_GUIDE — how to use Rosetta flows
DEPLOYMENT_GUIDE — RAGFlow, MCP, Helm deployment
TROUBLESHOOTING — symptom-first diagnosis

Related Docs

Contributing — fastest path to a merged PR
Architecture — system structure, components, data flow
Quickstart — zero to working setup
Overview — mental model, key concepts
Review Standards — what reviewers verify
Usage Guide — how to use Rosetta flows
Deployment Guide — RAGFlow, MCP, Helm deployment
Troubleshooting — symptom-first diagnosis

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Developer Guide

Overall Development Flow

Repository Layout

Prerequisites

Local Development: Instructions

Local Development: MCP

Redis (optional, for plan_manager)

Connect your IDE to local MCP

Local Development: CLI

Validation

MCP integration tests

Unit tests

Type checking

Git pre-commit hook

Dev Environment: Integration Testing

1. Publish instructions to dev

2. Test MCP (STDIO against dev)

3. Test Instructions from MCP (HTTP, default mode)

4. Test CLI changes

Where to Change What

How Documentation Is Organized

Related Docs

FilesExpand file tree

DEVELOPER_GUIDE.md

Latest commit

History

DEVELOPER_GUIDE.md

File metadata and controls

Developer Guide

Overall Development Flow

Repository Layout

Prerequisites

Local Development: Instructions

Local Development: MCP

Redis (optional, for plan_manager)

Connect your IDE to local MCP

Local Development: CLI

Validation

MCP integration tests

Unit tests

Type checking

Git pre-commit hook

Dev Environment: Integration Testing

1. Publish instructions to dev

2. Test MCP (STDIO against dev)

3. Test Instructions from MCP (HTTP, default mode)

4. Test CLI changes

Where to Change What

How Documentation Is Organized

Related Docs