Diffs

Diffs is a Cumulus Codex plugin for simple change reports and wireframe-first planning.

It creates .diffs/ documentation that explains:

• what was done,
• what was removed,
• what is missing,
• which files changed,
• and the raw diff for each file.

The goal is simple delivery for users who do not want to read code first.

For long tasks, Diffs can also create rough Balsamiq-style wireframe prompts, Mermaid state maps, visual-pass notes, implementation plans, and handoff prompts before coding.

What Is Included

• plugins/diffs/.codex-plugin/plugin.json defines the plugin metadata.
• plugins/diffs/hooks/hooks.json enables the startup hook.
• plugins/diffs/hooks/session-start-diffs.mjs adds a short reminder.
• plugins/diffs/skills/write-diff-docs/SKILL.md explains how Codex should write the docs.
• plugins/diffs/skills/write-diff-docs/scripts/create_diff_docs.py creates .diffs/ skeleton files from git changes.
• plugins/diffs/skills/diffs-wireframe-pipeline/SKILL.md explains the wireframe-first workflow.
• plugins/diffs/skills/diffs-wireframe-pipeline/scripts/create_pipeline_docs.py creates .diffs/pipeline/ starter files.
• agents/ stores the packaged custom-agent TOML files.
• eval-skills/ stores deterministic eval skills for the agents.
• docs/agent-pipeline/ stores reusable start, handoff, and manifest docs for the Diffs pipeline.

Setup

Clone the repo:

git clone https://github.com/Cumulus-s/diffs.git
cd diffs

Run validation:

python3 scripts/validate.py

Install the plugin for local Codex use:

mkdir -p "$HOME/plugins"
cp -R plugins/diffs "$HOME/plugins/diffs"

Add this entry to $HOME/.agents/plugins/marketplace.json:

{
  "name": "diffs",
  "source": {
    "source": "local",
    "path": "./plugins/diffs"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

The marketplace file should keep its existing name, interface, and other plugins.

Restart Codex or reload plugins after changing the marketplace.

Repo-Local Development

The repo-local marketplace entry is here:

.agents/plugins/marketplace.json

Usage

From a git repository with pending changes:

python3 plugins/diffs/skills/write-diff-docs/scripts/create_diff_docs.py --repo . --out .diffs

With a plan file:

python3 plugins/diffs/skills/write-diff-docs/scripts/create_diff_docs.py --repo . --out .diffs --plan-file PLAN.md

The script creates skeleton docs. Codex must still read the diff and replace TODO text with simple explanations.

Wireframe-First Pipeline

For long work, create pipeline docs before coding:

python3 plugins/diffs/skills/diffs-wireframe-pipeline/scripts/create_pipeline_docs.py --repo . --task "Build the worker dashboard"

This creates:

• .diffs/pipeline/start_prompt.md
• .diffs/pipeline/wireframes.md
• .diffs/pipeline/states.mmd
• .diffs/pipeline/visual_pass.md
• .diffs/pipeline/implementation_plan.md
• .diffs/pipeline/stage_manifest.json
• .diffs/pipeline/handoff_prompt.md

Use paid ChatGPT image generation when available. Do not use API keys.

Agent Package

Two optional custom agents are included:

• diffs-wireframe-architect: creates rough wireframes, state maps, affordance notes, and visual-pass notes.
• diffs-pipeline-controller: controls the full staged pipeline and blocks work when hard gates fail.

Install them locally:

mkdir -p "$HOME/.codex/agents"
cp agents/diffs-*.toml "$HOME/.codex/agents/"

Install eval skills locally:

mkdir -p "$HOME/.codex/skills"
cp -R eval-skills/eval-diffs-* "$HOME/.codex/skills/"

Verification

Run this before a release:

python3 scripts/validate.py

License

MIT. See LICENSE.