RED: Research, Evolve, Document

Keep your AI collaborator grounded in what your project has agreed, what is changing, and what still needs investigation.

RED is a methodology for maintaining project knowledge across AI conversations. Use it when an agent confuses an old idea with a current requirement, loses the reasoning behind a design, or leaves you with discussions that never turn into decisions and working changes.

Read the paper: English · 中文

How RED works

Start a task from the relevant Document sources and implementation evidence. Investigate decision-blocking unknowns in Research; a clear change can enter Evolve directly. Review the result before updating Document. Keep small, resolved work in the task; preserve R/E records when work needs handoff, review, or further investigation. Your project chooses whether those records live in Git, local files, issues, or pull requests.

What this package provides

• The RED Skill: instructions that guide a compatible agent through investigation, implementation, review, and documentation. It includes references and artifact templates.
• The red CLI: project configuration, artifact identifiers, structural checks, Skill installation and updates, and instruction-file management.

The Skill guides the agent's work. The CLI manages files and records decisions you authorize. People or a project-authorized decision process approve transitions; passing a check does not accept a proposal. When code or runtime evidence conflicts with Document, investigate the discrepancy before changing the baseline.

This Python package and the npm distribution provide the same command contract and Skill snapshot. Choose the runtime you already use.

Install the Skill

Requires Python 3.11 or later and pipx. From your project directory:

pipx run --spec red-methodology red skill install --scope repo

This installs the Skill into .agents/skills/red. Use a host that discovers Skills there, and ask the agent to use RED for the project. --scope user installs into your user-level .agents/skills/red instead. Repository scope selects the discovery location; your project decides whether to track or generate the installed files.

The one-shot command runs the installer without adding a permanent red executable to your PATH. For regular CLI use:

pipx install red-methodology
red version

If you already use uv, uvx --from red-methodology red skill install --scope repo is another one-shot option. For a persistent command with uv, use uv tool install red-methodology; upgrade it with uv tool upgrade red-methodology.

Start using RED

After installing the CLI, run these commands from the target project:

red init
# Edit red.toml to map your existing documentation and R/E locations.
red check --json
red status --json

red init creates red.toml and refuses to overwrite an existing configuration. Map the documentation you already maintain; no repository reorganization is required. The Skill can also work without the CLI or configuration when the agent can identify the project's knowledge sources.

Ask your agent, for example:

Use RED to add CSV export. Read the existing requirements, investigate unknowns that affect the design, and show me the implementation and proposed documentation before acceptance.

When an investigation or change needs its own record:

red new research --title "Clarify CSV compatibility requirements"
red new evolve --title "Add CSV export"

These create records in the configured locations. Continue design, implementation, tests, and revision within the agreed scope. At review, the agent presents evidence and the proposed Document update. After acceptance, it synchronizes the maintained documentation. See the CLI contract for promotion commands and JSON output.

Update or remove the Skill

Upgrade the CLI package first, then update the Skill snapshot it carries:

pipx upgrade red-methodology
red skill status --scope repo
red skill update --scope repo

For one-shot use, run pipx run --spec red-methodology red skill update --scope repo. Replacing the runner alone does not update an installed Skill.

red skill uninstall --scope repo

Update and uninstall use the installer's .red-install.json metadata and refuse to alter an unmanaged Skill directory.

Hosts without Skill support

Use a managed block in an existing AGENTS.md, or export standalone instructions:

pipx run --spec red-methodology red instructions install --target AGENTS.md
pipx run --spec red-methodology red instructions export --output RED.md

The managed block preserves the rest of AGENTS.md. Choose the instruction form your host reads; see the adoption guide.

Learn more

• Paper: English · 论文：中文
• RED Protocol 1
• Source and contribution guide
• Report an issue
• Releases, standalone Skill, and plugin archives

Licensed under Apache-2.0.