claude-md-downstream

Files (5)

• SKILL.md
• merge-classification.md · references/
• report-format.md · references/
• fetch-upstream.sh · scripts/
• match-version.sh · scripts/

SKILL.md (first lines)

# claude-md-downstream

Keep a downstream `CLAUDE.md` in step with the template it came from, without losing the
project-specific instructions that were added to it locally.

## Contract

- **Input:** a mode — `repo` or `user` — and optionally an alternative upstream repository.
- **Output:** a report in the conversation, and in the update cases a rewritten `CLAUDE.md` plus a
  timestamped backup of the file it replaced.
- **Not in scope:** judging whether the instructions in `CLAUDE.md` are any good. That is what
  `claude-md-improver` and `revise-claude-md` do. This skill only asks how the file relates to its
  upstream template.
- **Never commits.** The user reviews the diff and decides what enters history.

**Explicit invocation.** This skill starts only when it was named. A remark about `CLAUDE.md`
("my CLAUDE.md is getting long", "check the project memory") is not an invocation — this skill
rewrites a file that governs every later session, so it must never start on a guess.

## The idea behind the workflow

A downstream `CLAUDE.md` is the template plus whatever the project added to it. Once both sides
have moved, a plain diff can no longer tell the two apart: it reports "these 40 lines differ" and
leaves you to guess which side owns them. Applying such a diff either wipes local instructions or
drags in upstream rules that contradict them.

So the workflow first finds the **template version the local file grew out of** — the merge base.
With a base, each difference has an owner: upstream changed it, or the project did. Only where
*both* changed the same rule is there anything to decide, and that is exactly what gets brought to
the user.

The merge itself is done by reading and reasoning, not by `patch`. A `CLAUDE.md` is a set of
instructions to an agent, and instructions interact: a rule that reads fine in isolation can
contradict the one three sections down, or point at a tool this repository does not have. Text
that applies cleanly as a patch can still be wrong as a document. Checking the *result* for
coherence is the point of Step 6, and it is why a patch would not do.

### Taking the template 1:1 stays on the table

The merge assumes the project wants to keep what it wrote. That assumption is usually right and
sometimes wrong: the local edits may be accidental drift, an experiment nobody stands behind, or a
divergence the project has decided to end. Then a conflict-by-conflict merge is an expensive route
to a file the user could have had in one step.

So wherever this skill reports a difference, **"take the current template 1:1 — drop everything
local"** is an available answer, alongside the per-rule options. It is an option, never a
recommendation: it deletes instructions someone wrote on purpose, and this skill's default stance
is that they meant them. Offer it plainly in one line, do not argue for it, and never carry it out
before the user has seen the list of what it removes — that is Step 7a.

## Prerequisites

- `git` (any version with `clone --filter` support; the scripts fall back to a full clone).
- `bash` 3.2+ (macOS default works), `python3` (used by the scripts for safe JSON encoding).
- Network access on first run. Later runs reuse the cached clone and continue — degraded, loudly —
  when upstream is unreachable.
- `jq` is not required by the scripts, but it makes their JSON easier to read.

## Modes

| Mode   | Local file                                    | Upstream template                       |
| ------ | --------------------------------------------- | --------------------------------------- |
| `repo` | `<git repository root>/CLAUDE.md`             | `claude/claude-md-template.repo.md`     |
| `user` | `~/.claude/CLAUDE.md`                         | `claude/claude-md-template.user.md`     |

In `repo` mode the target is always the **repository root**, no matter which subdirectory the
session is working in. A `CLAUDE.md` in a subdirectory is never the target; if the user meant that
one, they have to say so, and this skill does not handle it.

Upstream defaults to `https://github.com/CreativeCodersTeam/ai-store.git`. A fork or a private
mirror is passed through `--repo-url` to both scripts.

## Workflow

### Step 1 — Determine the mode

Take the mode from the invocation when it names one (`/claude-md-downstream repo`, "run
claude-md-downstream in user mode"). Otherwise ask once — the two modes touch different files, and
picking the wrong one edits a file the user was not thinking about.

Also accept an upstream override if the user supplies one, and carry it into both script calls.

**Non-interactive invocation** (you are a sub-agent, or no user is reachable): do not guess the
mode and do not stall. Report that the mode is missing, state what each mode would have targeted,
and stop. Everything else in this workflow that asks the user degrades the same way — see
*Non-interactive path* below.

### Step 2 — Fetch upstream

```
scripts/fetch-upstream.sh [--repo-url <url>] [--cache-dir <path>]
```

Parse the JSON `{repo_url, cache_dir, head_sha, head_short, default_branch, action, stale}`.

The materialised template versions of Step 3 land in `<cache-dir>-work/<mode>/`, beside the cache
rather than inside it.

- Exit 0 with `stale: false` — continue.
- Exit 0 with `stale: true` — upstream was unreachable and the cached clone is being reused. Say so
  plainly before reporting any result: the comparison is against whatever was cached, so a "you are
  up to date" verdict could be stale. Then continue.
- Exit 2 — no cache and upstream unreachable. Report the URL and the git error and stop; there is
  nothing to compare against.
- Exit 1 — usage error; check the arguments, correct, retry. If they were right, report the bug.

### Step 3 — Match the local file against the template history

```
scripts/match-version.sh --cache-dir <cache> --mode repo|user [--start-dir <path>]
                         [--template-path <path>] [--branch <name>] [--max-history <n>]
```

In `repo` mode pass the session's working directory as `--start-dir`; the script resolves the
repository root itself.

Exit codes: `0` success — the outcome is in `.status`; `1` usage; `2` the cache is not a usable
clone (re-run Step 2 once, then report); `3` `repo` mode outside a git repository — report that
`repo` mode needs a repository and offer `user` mode instead.

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store