chum - Context Hierarchy Using Markdown

chum is a suite of installable agent skills for maintaining filesystem-first repository documentation and creating spec-driven workflow artifacts.

It turns the workflow described in AGENTS.template.md into a skill plus a deterministic Python processor:

uv run skills/chum/scripts/chum.py targets --root . --json
uv run skills/chum/scripts/chum.py normalize --root . --target src/foo.py --stdin --write
uv run skills/chum/scripts/chum.py validate --root . --target src/foo.py --json
uv run skills/chum/scripts/chum.py check --root . --json
uv run skills/chum/scripts/chum.py archive --root . <change-id> --write --json

The script does not call an LLM. The active agent session keeps shared codebase context, plans its own route through related files and directories, writes current-state specs, and uses scripts/chum.py for discovery, validation, normalization, init, and archive mechanics.

Install

The publishable skills live in skills/:

• $chum maintains and validates current-state specs.
• $chum-design creates design documents.
• $chum-plan creates implementation specs and phase plans.
• $chum-review creates evidence-led review documents.
• $chum-debug creates evidence-led debug documents.
• $chum-probe tests focused assumptions with bounded, reversible checks.

Codex

To install from GitHub in Codex, ask Codex to install each skill:

https://github.com/jumploops/chum/tree/main/skills/chum
https://github.com/jumploops/chum/tree/main/skills/chum-design
https://github.com/jumploops/chum/tree/main/skills/chum-plan
https://github.com/jumploops/chum/tree/main/skills/chum-review
https://github.com/jumploops/chum/tree/main/skills/chum-debug
https://github.com/jumploops/chum/tree/main/skills/chum-probe

Then restart Codex so the new skill is picked up.

For a local manual install of the complete suite:

mkdir -p ~/.codex/skills
cp -R skills/chum skills/chum-design skills/chum-plan skills/chum-review skills/chum-debug skills/chum-probe ~/.codex/skills/

Claude Code

For a personal Claude Code skill available across projects:

mkdir -p ~/.claude/skills
cp -R skills/chum skills/chum-design skills/chum-plan skills/chum-review skills/chum-debug skills/chum-probe ~/.claude/skills/

For a project-local Claude Code skill, copy it into that project's .claude/skills/ directory:

mkdir -p /path/to/project/.claude/skills
cp -R skills/chum skills/chum-design skills/chum-plan skills/chum-review skills/chum-debug skills/chum-probe /path/to/project/.claude/skills/

Claude Code exposes the skills from their installed directory names. If Claude Code was already running and the target skills directory did not exist yet, restart Claude Code so it can discover the new skill directory.

Each stage skill contains SKILL.md, agents/openai.yaml, and its analyzed template at references/template.md. The core skill surface is:

• skills/chum/SKILL.md
• skills/chum/agents/openai.yaml
• skills/chum/scripts/chum.py
• skills/chum/references/

The remaining files are project docs and tests for maintaining this repo.

Skill Usage

Start with skills/chum/SKILL.md. The usual loop is:

1. Run targets --json.
2. Read existing specs and related source files.
3. Update specs with accumulated repo context.
4. Run normalize and validate for focused targets.
5. Finish with check --json.

Use python3 skills/chum/scripts/chum.py ... as a local development fallback when uv is not installed. In restricted sandboxes where uv cannot write its default cache, set UV_CACHE_DIR=/tmp/chum-uv-cache.

When the skill is installed outside the target repo, resolve the script path from the installed skill directory and pass the repository to inspect via --root:

uv run /path/to/chum/scripts/chum.py targets --root /path/to/repo --json

Development

python3 skills/chum/scripts/chum.py --help
python3 -m unittest discover tests
UV_CACHE_DIR=/tmp/chum-uv-cache uv run skills/chum/scripts/chum.py --help
python3 skills/chum/scripts/chum.py check --root . --json

Status

The current implementation is the Python skill surface in SKILL.md, scripts/, references/, and agents/ under skills/chum/.