context-packs 0.1.0 → 0.2.0

package/README.md

@@ -1,97 +1,125 @@
 # context-packs
 
-Sync shared agent rules and docs into each repo's `AGENTS.md`.
+Keep your coding agents' rules in one git repo, and sync them into the `AGENTS.md` of every repo that should follow them.
 
-A context pack is a folder in a git repo holding rules every agent session should see, and docs that agents read only for some kinds of work. `context-packs` copies the packs a repo installs into that repo, pinned to a tag or commit, so Claude Code, Codex and any other agent that reads `AGENTS.md` get the same rules. That includes cloud sessions and fresh clones, which see only what's committed.
+Agent rules copied from repo to repo drift apart. context-packs syncs them instead:
 
-## Install
+- **One source.** Every repo that installs a pack gets the same text, pinned to a tag or commit, and moves on with `update`.
+- **Committed, so every session sees it.** Packs are copied in, not linked or loaded by a hook, so clones, CI and cloud agent sessions get them too.
+- **Read only when relevant.** Long docs don't load into every session: `AGENTS.md` gets a table saying when to read each one.
+- **Any agent.** Anything that reads `AGENTS.md` works, and `CLAUDE.md` is linked to it for Claude Code.
 
-Run it with npx:
+A synced pack in `AGENTS.md`:
 
-```bash
-npx github:mjewell/context-packs <command>
-```
-
-It syncs the current folder. Pass `--dir <folder>` before the command to sync another.
-
-It needs `git`, Node 18 or later, and Python 3.9 or later. On macOS, the Xcode command line tools that provide `git` provide Python too.
-
-This repo is also a Claude Code plugin with a `/context-packs` skill, which runs the commands for you. Add it to a plugin marketplace, or install just the skill for Claude Code and Codex with `npx skills add mjewell/context-packs -g -a claude-code -a codex`.
+```markdown
+<!-- context-packs:start team-rules from=https://github.com/acme/agent-rules.git path=context ref=v1.2.0 -->
+Prefer small PRs. Never commit secrets.
 
-## Use it
+## team-rules context
 
-```bash
-npx github:mjewell/context-packs add team-rules https://github.com/acme/agent-rules.git --path context
+| When | Read |
+|---|---|
+| Writing or changing tests | `docs/agents/packs/team-rules/testing.md` |
+<!-- context-packs:end sha256:3f2c1aa0b9d4 -->
 ```
 
-That writes two blocks into `AGENTS.md`: a header block explaining context packs, and one for the pack. It also copies the pack's doc sets into `docs/agents/packs/team-rules/`, and creates `CLAUDE.md` as a symlink to `AGENTS.md`, so Claude Code reads the same file. Commit the result.
-
-If `AGENTS.md` already exists, the first run prints two marker lines instead. Paste them where the shared rules should go, after the intro and before the project-specific sections, and run it again.
+Run it with `npx context-packs`, or [let your agent run it](#let-your-agent-run-it). It needs `git`, Node 18+ and Python 3.9+; on macOS, the command line tools provide both `git` and Python.
 
-| Command | Does |
-|---|---|
-| *(none)* | Resyncs every pack at its pinned ref |
-| `add <name> <origin> [--path P] [--ref R] [--docs a,b]` | Installs a pack, pinned to the origin's latest commit or to `--ref` |
-| `remove <name>` | Uninstalls a pack |
-| `update [name…]` | Moves packs to their latest version |
-| `update <name> --ref R` | Pins one pack to a tag or commit |
-| `docs <name> a,b` | Replaces a pack's optional doc sets (`''` for none) |
-| `list` | Lists each pack and its doc sets, marking the installed ones |
+## Write a pack
 
-A folder that holds several repos without being one can be synced too, so sessions started there get the rules. A Claude Code session started inside one of those repos then loads both copies, since Claude Code reads `CLAUDE.md` from the folders above it as well.
+A pack is a folder in any git repo. `pack.md` holds the rules every session sees, and each doc set, one `.md` file or a folder with an `index.md`, covers a topic agents read about only when it's relevant:
 
-### Pinning and updates
+```text
+context/
+├── pack.md          # rules pasted into every repo's AGENTS.md
+├── testing.md       # a doc set in one file
+└── typescript/
+    ├── index.md     # a doc set's entry point
+    └── react.md     # linked from index.md
+```
 
-Each pack's start marker records where it comes from and where it's pinned:
+Each doc set starts with front matter. `when` becomes its row in the table, and `tier: required` installs it in every repo; without it, the set is optional and each repo chooses it with `--docs`.
 
 ```markdown
-<!-- context-packs:start team-rules from=https://github.com/acme/agent-rules.git path=context ref=v1.2.0 -->
+---
+when: Writing or changing tests
+tier: required
+---
 ```
 
-`--ref` takes a tag or a commit, never a branch, since a branch moves. `update` moves a pack along what it's pinned to:
+Keep `pack.md` short, since every session loads it.
 
-- **A commit** moves to the tip of the origin's default branch.
-- **A release tag**, meaning a prefix followed by dot-separated numbers such as `v1.2.0` or `acme-v3`, moves to the newest release with the same prefix. Pre-releases like `v2.0.0-rc1` are skipped.
-- **Any other tag** stays put.
+Tags are optional. A repo pins to a commit by default, and `update` moves it to the tip of your default branch. Tag releases like `v1.2.0` once you want repos to pin to versions and `update` from one release to the next.
 
-The sync fetches origins into `~/.cache/context-packs/` using your own git credentials, so private repos work.
+## Sync a pack from another repo
 
-A pack can also live in the repo it's synced into: `add <name> . --path <folder>` reads it from the working tree, with no ref. Its table points at the docs where they are instead of copying them, and it installs every doc set it has.
+```bash
+npx context-packs add <name> <git-url> --path <folder>
+```
 
-That's the way to keep a repo's own context docs. Put each one in `docs/agents/project/` with a `when:` line, run `add project . --path docs/agents/project` once, and resync after adding a doc or changing its `when:`. The table in `AGENTS.md` stays generated from the docs.
+- `<name>` is what this repo calls the pack, such as `team-rules`.
+- `<git-url>` is the repo holding the pack, as you'd pass it to `git clone`.
+- `<folder>` is the pack's folder in that repo, such as `context`. Leave out `--path` if the pack is the whole repo.
 
-### Edits stay upstream
+That adds the pack's block to `AGENTS.md`, creating it if needed, and copies the doc sets into `docs/agents/packs/<name>/`, pinned to the origin's latest commit or to `--ref <tag or commit>`. Commit the result. If `AGENTS.md` already exists, the first run prints two marker lines to paste where the shared rules should go; then run it again.
 
-Each block ends with a hash covering its text and its docs folder. If either was edited in the repo, the sync stops without changing anything and says what to fix. Change a pack in its origin, then update.
+Later, `npx context-packs update` moves packs to their latest version, and `npx context-packs` resyncs at the pinned ones. Private repos work, since origins are fetched with your own git credentials.
 
-## Write a pack
+## Sync your project's own docs
 
-A pack is a folder holding an optional `agents.md` and any number of doc sets. A doc set is a single `.md` file, or a folder whose `index.md` links to its other files:
+The same table works for a repo's own docs. Put each in a folder with a `when:` line, and install the folder as a pack read from the working tree:
 
-```text
-context/
-├── agents.md           # rules pasted into the pack's block
-├── testing.md          # a doc set in one file
-└── typescript/
-    ├── index.md        # a doc set's entry point
-    └── react.md        # other files, linked from index.md
+```bash
+npx context-packs add <name> . --path <folder>
 ```
 
-Each doc set's entry point starts with front matter saying when to read it:
+- `<name>` is what this repo calls the pack.
+- `.` is the origin: the pack is in this repo, so it has no ref and syncs from your working tree.
+- `<folder>` holds the docs.
 
-```markdown
----
-when: Writing or changing tests, or fixing a bug
-tier: required
----
+Any name and folder work. We suggest `project` and `docs/agents/project`:
+
+```bash
+npx context-packs add project . --path docs/agents/project
 ```
 
-The pack's block lists its installed doc sets in a table that agents check before starting work. `tier: required` installs the set in every repo that installs the pack. Leave `tier` out for an optional set, which each repo chooses with `--docs` or `docs`.
+Its table points at the docs where they are. Resync after adding a doc or changing a `when:` line.
 
-Keep `agents.md` small, since every session loads it, and put anything needed only for some work in a doc set. agy stops reading `AGENTS.md` after 24 KB.
+## Let your agent run it
 
-## Tests
+The `context-packs` skill lets you skip the commands: ask Claude Code or Codex in plain words, and it runs them, shows you what changed, and leaves the result uncommitted for you to review. Install it for every project:
 
 ```bash
-python3 -m unittest discover tests
+npx skills add mjewell/context-packs -g
 ```
+
+Leave out `-g` to install it into the current project instead.
+
+Then ask things like:
+
+- "Add the context pack in the `context` folder of github.com/acme/agent-rules"
+- "Update our context packs"
+- "Install the typescript docs from team-rules"
+- "Sync our project docs"
+
+In Claude Code, `/context-packs` invokes it directly.
+
+## Reference
+
+Each command syncs the current folder, or `--dir <folder>`, and prints what changed. The folder can also hold several repos without being one itself, so sessions started there get the rules too.
+
+| Command | Does |
+|---|---|
+| *(none)* | Resyncs every pack at its pinned ref |
+| `add <name> <origin> [--path P] [--ref R] [--docs a,b]` | Installs a pack, pinned to the origin's latest commit or to `--ref` |
+| `remove <name>` | Uninstalls a pack |
+| `update [name…]` | Moves packs to their latest version |
+| `update <name> --ref R` | Pins one pack to a tag or commit |
+| `docs <name> a,b` | Replaces a pack's optional doc sets (`''` for none) |
+| `list` | Lists each pack and its doc sets, marking the installed ones |
+
+**Pinning.** `--ref` takes a tag or a commit, never a branch, since a branch moves. `update` moves a pack pinned to a commit to the tip of the default branch, and one pinned to a release tag (a prefix and dot-separated numbers, such as `v1.2.0` or `acme-v3`) to the newest release with the same prefix, skipping pre-releases. Other tags stay put.
+
+**Edits stay upstream.** Each block ends with a hash of its text and synced docs. If either was edited in the repo, the sync stops and says what to fix: change the pack in its origin, then `update`.
+
+**Contributing.** [design.md](docs/agents/project/design.md) explains the choices behind the format. Run the tests with `python3 -m unittest discover tests`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-packs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Sync shared agent rules and docs into each repo's AGENTS.md",
   "license": "MIT",
   "bin": {
@@ -13,5 +13,8 @@
   "engines": {
     "node": ">=18"
   },
-  "repository": "github:mjewell/context-packs"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mjewell/context-packs.git"
+  }
 }

package/src/blocks.py

@@ -19,10 +19,12 @@ BLOCK = re.compile(r'^<!-- context-packs:start (\S+)((?: \S+)*) -->\n(.*?)'
 
 
 class Region(NamedTuple):
-    """Where AGENTS.md's context-packs blocks sit, the packs they hold, and the doc sets each installed."""
+    """Where AGENTS.md's context-packs blocks sit, each block's text by name, the packs they hold, and the doc sets
+    each installed."""
     text: str
     start: int
     end: int
+    blocks: Dict[str, str]
     packs: List[Pack]
     installed: Dict[str, List[str]]
 
@@ -110,4 +112,5 @@ def region(repo):
             sys.exit(f'context-packs: {agents_md}: the {name} block or a doc in {PACKS / name} was edited since '
                      'the last sync. Move the change into its context pack or outside them, revert it, '
                      'then sync again.')
-    return Region(text, blocks[0].start(), blocks[-1].end(), packs, current)
+    return Region(text, blocks[0].start(), blocks[-1].end(), {m.group(1): m.group(0) for m in blocks}, packs,
+                  current)

package/src/cli.py

@@ -11,6 +11,7 @@ import shutil
 import sys
 
 import origins
+import report
 from blocks import HEADER, HEADER_RULES, HEADER_START, block, region, snapshot
 from packs import LOCAL, PACKS, Pack, Source, fetch
 
@@ -139,23 +140,26 @@ def main():
         for gone in {p.name for p in found.packs} - {p.name for p in packs}:
             if (repo / PACKS / gone).exists():
                 shutil.rmtree(repo / PACKS / gone)
-        blocks = [block(HEADER_START, HEADER_RULES)]
+        blocks = {HEADER: block(HEADER_START, HEADER_RULES)}
         for source in sources:
             if source.pack.local:
-                blocks.append(block(starts[source.pack.name], bodies[source.pack.name]))
+                blocks[source.pack.name] = block(starts[source.pack.name], bodies[source.pack.name])
                 continue
             synced = repo / source.pack.synced
             if synced.exists():
                 shutil.rmtree(synced)
             for name in chosen[source.pack.name]:
                 source.copy(name, synced)
-            blocks.append(block(starts[source.pack.name], bodies[source.pack.name], snapshot(synced)))
+            blocks[source.pack.name] = block(starts[source.pack.name], bodies[source.pack.name], snapshot(synced))
         if (repo / PACKS).is_dir() and not any((repo / PACKS).iterdir()):
             (repo / PACKS).rmdir()
-        text = found.text[:found.start] + '\n'.join(blocks) + found.text[found.end:]
+        text = found.text[:found.start] + '\n'.join(blocks.values()) + found.text[found.end:]
+        created = not (repo / 'AGENTS.md').exists()
         (repo / 'AGENTS.md').write_bytes(text.encode('utf-8'))
         if not linked:
             claude_md.symlink_to('AGENTS.md')
+        for line in report.changes(found, packs, chosen, blocks, created, linked):
+            print(line)
 
 
 if __name__ == '__main__':

package/src/packs.py

@@ -42,14 +42,18 @@ class Pack(NamedTuple):
 
 
 class Source(NamedTuple):
-    """A pack's content, fetched into a folder holding its agents.md and doc sets."""
+    """A pack's content, fetched into a folder holding its pack.md and doc sets."""
     pack: Pack
     folder: Path
 
     def available(self):
-        """The pack's doc sets: each a folder holding an index.md, or a single .md file other than agents.md."""
+        """The pack's doc sets: each a folder holding an index.md, or a single .md file other than pack.md."""
+        if (self.folder / 'agents.md').is_file():
+            sys.exit(f'context-packs: {(Path(self.pack.path) / "agents.md").as_posix()} in {self.pack.origin} holds '
+                     'rules under the name packs used before 0.2.0. Rename it to pack.md in the pack, or run update '
+                     'to move to a version of the pack that has one.')
         folders = {p.name for p in self.folder.iterdir() if p.is_dir() and not p.name.startswith('.')}
-        files = {p.stem for p in self.folder.glob('*.md') if p.name != 'agents.md'}
+        files = {p.stem for p in self.folder.glob('*.md') if p.name != 'pack.md'}
         for name in sorted(folders & files):
             sys.exit(f'context-packs: {self.pack.origin} has both {name}.md and {name}/ in '
                      f'{self.pack.path or "its root"}, so the doc set {name} is ambiguous. Keep one.')
@@ -85,7 +89,7 @@ class Source(NamedTuple):
             shutil.copy2(self.folder / f'{name}.md', synced / f'{name}.md')
 
     def body(self, names):
-        rules_file = self.folder / 'agents.md'
+        rules_file = self.folder / 'pack.md'
         rules = rules_file.read_text(encoding='utf-8') if rules_file.is_file() else ''
         # The end marker has to start its own line, or the next sync can't find the block.
         if rules and not rules.endswith('\n'):

package/src/report.py

@@ -0,0 +1,43 @@
+"""What a sync changed, in lines for the person who ran it."""
+from blocks import HEADER
+from origins import COMMIT
+
+
+def short(ref):
+    """ref as git shows it: a commit abbreviated, a tag in full."""
+    return ref[:7] if COMMIT.fullmatch(ref) else ref
+
+
+def at(pack):
+    """Where the pack is pinned, or nothing for one that syncs from the repo's working tree."""
+    return f' @ {short(pack.ref)}' if pack.ref else ''
+
+
+def sets(names):
+    return ', '.join(names) or 'none'
+
+
+def changes(found, after, chosen, blocks, created, linked):
+    """Lines describing what the sync did: whether it created AGENTS.md or found CLAUDE.md already linked to it, and
+    how the packs found in AGENTS.md became the packs after it, with chosen holding the doc sets each pack installs
+    and blocks the text the sync wrote for each."""
+    before = found.packs
+    old = {p.name: p for p in before}
+    new = {p.name for p in after}
+    lines = (['Created AGENTS.md'] * created + ['Linked CLAUDE.md to AGENTS.md'] * (not linked)
+             + ['Updated the header block'] * (not created and found.blocks[HEADER] != blocks[HEADER]))
+    for pack in after:
+        was = old.get(pack.name)
+        if not was:
+            docs = chosen[pack.name]
+            lines.append(f'{pack.name}: added{at(pack)}' + f' (docs: {sets(docs)})' * bool(docs))
+        elif was.ref != pack.ref:
+            lines.append(f'{pack.name}: {short(was.ref)} → {short(pack.ref)}')
+        elif not pack.local and found.installed[pack.name] != chosen[pack.name]:
+            lines.append(f'{pack.name}: doc sets {sets(found.installed[pack.name])} → {sets(chosen[pack.name])}')
+        elif found.blocks[pack.name] != blocks[pack.name]:
+            lines.append(f'{pack.name}: changed')
+    lines += [f'{p.name}: removed' for p in before if p.name not in new]
+    if lines:
+        return lines
+    return [f'Nothing changed: {", ".join(p.name + at(p) for p in after) or "no packs installed"}']