@eric0117/agentforge 0.1.0

package/dist/sync-skills.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { readMasterDir } from "./agents/io.js";
+import { getAgent } from "./agents/index.js";
+import { masterDir, requireWorkspace } from "./agentforge-config.js";
+import { SKILLS } from "./skills-data.js";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const CYAN = "\x1b[36m";
+const BOLD = "\x1b[1m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+export async function runSyncSkills(opts) {
+    const root = resolve(opts.pathArg ?? process.cwd());
+    const cfg = requireWorkspace(root);
+    if (!existsSync(masterDir(root))) {
+        process.stderr.write(`\n${YELLOW}⚠${RESET} No master skills directory at ${DIM}${masterDir(root)}${RESET}\n\n` +
+            `  Run ${CYAN}agentforge init${RESET} here first to set up the workspace.\n\n`);
+        process.exit(1);
+    }
+    const { skills: masterSkills, skipped, warnings } = readMasterDir(masterDir(root));
+    if (skipped.length > 0) {
+        console.log(`${YELLOW}skipped invalid master files:${RESET}`);
+        for (const sk of skipped) {
+            console.log(`  ${DIM}- ${sk.file}: ${sk.reason}${RESET}`);
+        }
+        console.log("");
+    }
+    if (warnings.length > 0) {
+        console.log(`${YELLOW}master file warnings:${RESET}`);
+        for (const w of warnings) {
+            console.log(`  ${DIM}- ${w.file}: ${w.warning}${RESET}`);
+        }
+        console.log("");
+    }
+    if (masterSkills.length === 0) {
+        console.log(`${YELLOW}no valid master skills found — nothing to sync.${RESET}`);
+        return;
+    }
+    console.log(`${BOLD}${GREEN}↻${RESET} syncing ${masterSkills.length} skill(s) → ${cfg.agents.length} agent(s) in ${CYAN}${root}${RESET}`);
+    console.log("");
+    // sync-skills is propagate-by-design: always back up and overwrite. Pass
+    // forceSkills=true unconditionally; forceClaude only when explicit.
+    for (const id of cfg.agents) {
+        const adapter = getAgent(id);
+        console.log(`${BOLD}${CYAN}▸ ${adapter.label}${RESET}`);
+        adapter.install({
+            root,
+            masterSkills,
+            skillCatalog: SKILLS.slice(),
+            lang: cfg.lang,
+            forceSkills: true,
+            forceClaude: opts.forceClaude,
+        });
+        console.log("");
+    }
+    console.log(`${BOLD}${GREEN}✓${RESET} sync complete  ${DIM}(skills: ${masterSkills.map((s) => s.id).join(", ")})${RESET}`);
+}

package/dist/templates/CLAUDE.md.tpl

@@ -0,0 +1,141 @@
+# Multi-Repo Workspace
+
+This directory is an [agentforge](https://github.com/) workspace — a bootstrapped layout
+for working across multiple repositories with Claude Code, designed for the case where
+one feature spans several repos and several features need to be developed in parallel.
+
+## Directory layout
+
+```
+.
+├── repos/          # main branch of each repo (read / explore only)
+├── anvil/          # per-feature worktrees — ONLY in-progress work
+│   └── <slug>/
+│       ├── <repo>/         # a worktree of <repo> for this feature
+│       └── CLAUDE.md       # feature description + repos in scope
+├── artifacts/        # closed features, grouped by completion date
+│   └── <YYYYMMDD>/
+│       └── <slug>/
+│           ├── CLAUDE.md   # original feature metadata (moved here on retro)
+│           ├── RETRO.md    # retrospective
+│           ├── sessions/   # Claude Code transcripts
+│           ├── plans/      # plan files
+│           └── refs.json   # per-repo branch + HEAD + PR pointers
+├── agentforge/     # workspace metadata + master skills (the single source of truth)
+│   ├── config.json
+│   ├── skills/
+│   └── log.jsonl   # append-only activity log
+└── .claude/skills/  .cursor/rules/  .agents/skills/   # per-agent generated files
+```
+
+- **`repos/<name>/`** — you `git clone` your repos here yourself. Used for
+  read / explore only. Don't edit code here.
+- **`anvil/<slug>/<repo>/`** — feature work happens in worktrees. The
+  `agentforge-feature-start` skill creates these.
+- **`artifacts/<YYYYMMDD>/<slug>/`** — once `feature-retro` closes a feature, the
+  worktree is removed and the retrospective + supporting artifacts land here.
+  `ls artifacts/` shows every completed feature, newest dates first.
+- **`agentforge/skills/<id>.md`** — master copy of every skill. Edit a file here
+  and run `agentforge sync-skills` to push the change to every installed agent.
+
+## Installed skills
+
+All skills below are workspace-local (under `.claude/skills/`) and are auto-loaded by
+Claude Code when you run `claude` from this directory or any subdirectory. Trigger them
+by describing what you want in natural language — you don't have to remember the names.
+
+### Day-to-day
+
+#### Ask a question / explore code
+From the workspace root, just describe what you want.
+**`agentforge-project-router`** picks the right `repos/<name>/` to look in, or asks you
+when ambiguous.
+
+> "Where is the auth handler in the backend API?"
+> "What does the admin's user list page do?"
+
+### Feature lifecycle
+
+#### 1. Start a new feature
+> "Let's start a new feature: search ranking."
+
+**`agentforge-feature-start`** proposes a kebab-case slug, asks which repos the feature
+touches, and creates `git worktree`s under `anvil/<slug>/<repo>/`.
+
+#### 2. Work on the feature
+```bash
+cd anvil/<slug>/
+claude
+```
+A single session at that path sees all worktrees of the feature at once.
+
+#### 3. Check what a change would break (before touching shared code)
+> "Where else is `doSomething` used?" · "Blast radius of removing `/v1/things`?"
+
+**`agentforge-cross-repo-impact`** searches every other `repos/*` for call sites,
+imports, HTTP callers, type usages, etc. and flags breaking changes.
+
+#### 4. Pre-deploy sanity check
+> "Anything ops needs before I ship this?" · "Pre-deploy check."
+
+**`agentforge-pre-deploy-check`** scans the worktree diff for non-code changes —
+DB migrations, env vars, cache keys, message-queue schemas, dependency locks, infra
+config, feature flags, API surface, cron jobs — and outputs a checklist + deploy
+order.
+
+#### 5. Open PRs for the feature
+> "Open PRs for this feature." · "Make the PRs."
+
+**`agentforge-pr-create`** detects which worktrees have commits ahead, lets you
+multi-select, then opens one PR per repo via `gh`. Drafts titles + bodies from the
+feature's `CLAUDE.md` and the per-repo diff stat, and cross-links the PRs to each
+other.
+
+#### 6. Audit review comments
+> "Audit the PR comments." · "What do we need to fix from the review?"
+
+**`agentforge-pr-review-analyze`** pulls every review thread, verifies each against the
+live code, classifies impact (Critical → Discussion), traces the call path, and notes
+test coverage. Returns a prioritized action list.
+
+#### 7. Wrap up a finished feature
+> "We're done with this feature." · "Write a retro and clean up."
+
+**`agentforge-feature-retro`**:
+1. Creates `artifacts/<YYYYMMDD>/<slug>/` (close-date directory).
+2. Copies Claude Code session logs (`~/.claude/projects/.../*.jsonl`) into
+   `artifacts/<YYYYMMDD>/<slug>/sessions/`.
+3. Copies relevant plan files (`~/.claude/plans/*.md`) into the same archive's
+   `plans/`.
+4. Captures per-repo branch + HEAD + PR pointers into `refs.json`.
+5. Writes `RETRO.md` — what was asked, decided, built, learned.
+6. Moves `anvil/<slug>/CLAUDE.md` into the archive directory.
+7. Removes each `anvil/<slug>/<repo>/` worktree (only if no dirty / unpushed
+   changes), then deletes the now-empty `anvil/<slug>/` directory so `anvil/`
+   only contains in-progress features.
+
+### Looking back
+
+#### Recall past features
+> "How did we handle the retry logic last time?" · "Which feature touched
+> mobile-app for queue config?" · "Find that PR about search rankings."
+
+**`agentforge-history`** searches every `artifacts/<YYYYMMDD>/<slug>/` (RETROs, plan
+files, `refs.json` with branch/HEAD/PR pointers) and answers with grounded
+references — file paths, commit hashes, PR URLs — so you can verify and dig
+deeper. Filters by keyword, repo, date window, or PR/commit. Read-only.
+
+### Operations
+
+#### Incident context (you just got paged)
+> "Got an alert about `NullPointerException at Foo.process` — pull context."
+
+**`agentforge-incident-context`** searches every repo for matching code, identifies
+recent merged PRs that touched it, names the last committers, traces the call path
+(highlighting async entry points), and proposes next steps. Optimized for a 30-second
+read.
+
+## Current repos
+
+Run `ls repos/` to see them. agentforge does not maintain a separate metadata file —
+the filesystem is the source of truth.

package/dist/templates/context-handoff.SKILL.md.tpl

@@ -0,0 +1,222 @@
+---
+name: agentforge-context-handoff
+description: Packages a feature's current state into a single handoff document so another developer (or future-self) can pick up without context loss. Gathers per-worktree git state, open PRs and their review state, unaddressed comments, pending plan items, recent decisions, recently touched files, open TODOs and questions. Writes anvil/<slug>/HANDOFF.md. Optionally posts the same summary as a comment on each related PR — only with explicit user confirmation. Never modifies CLAUDE.md, never pushes commits. Triggers on "hand this off", "휴가 가니 정리해줘", "leave notes for next session", "다음 사람한테 넘길 패키지", "package this up".
+---
+
+# context-handoff
+
+Packages the current state of a feature into a single document — `HANDOFF.md` —
+so another developer (or future-you, three weeks from now) can resume without
+having to reconstruct context from git, PR threads, and memory.
+
+Read-mostly: writes one new file in the feature directory and, only with
+explicit confirmation, posts the same summary as a comment on each related PR.
+Never touches existing CLAUDE.md, never pushes commits, never modifies code.
+
+## When to apply
+
+Trigger phrases:
+- "Hand this off." / "Package this up."
+- "Leave notes for next session."
+- "휴가 가니 정리해줘." / "다음 사람한테 넘길 패키지."
+- "I'm switching pairs — write a handoff."
+
+Also a good fit before a long pause (vacation, parental leave, sprint
+boundary), or before genuinely handing the feature to a different developer.
+
+## Resolve scope
+
+The handoff is **always per-feature**. Resolve the slug from cwd:
+
+- `…/anvil/<slug>/` (or anywhere inside it) → that feature.
+- Workspace root, no obvious context → ask the user for the slug, or list
+  active features (`ls anvil/`).
+
+If the named slug has no `anvil/<slug>/` directory, stop and tell the user —
+either the feature was already wrapped up (check `artifacts/`) or the slug is
+wrong.
+
+## Step 1 — Gather feature metadata
+
+Read `anvil/<slug>/CLAUDE.md`:
+- Feature description (the heading + first paragraph)
+- `Started:` / `Expanded:` dates
+- `Repos in scope:` list with per-repo branch names
+
+If `anvil/<slug>/PLAN.md` exists (from `feature-plan` or hand-written), read
+its pending items.
+
+## Step 2 — Per-worktree state
+
+For each repo in scope (`ls -d anvil/<slug>/*/`):
+
+```bash
+branch=$(git -C anvil/<slug>/<repo> rev-parse --abbrev-ref HEAD)
+base=$(git -C anvil/<slug>/<repo> symbolic-ref --quiet refs/remotes/origin/HEAD \
+        | sed 's@^refs/remotes/origin/@@')
+
+# Recent commits on this branch (since base)
+git -C anvil/<slug>/<repo> log --oneline "origin/$base..HEAD" | head -20
+
+# Working-tree state — uncommitted work is the most important thing to flag
+git -C anvil/<slug>/<repo> status --porcelain
+
+# Unpushed commits
+git -C anvil/<slug>/<repo> log @{u}..HEAD --oneline 2>/dev/null
+
+# Files recently touched (signal for "where I left off")
+git -C anvil/<slug>/<repo> diff --name-only "origin/$base"...HEAD
+git -C anvil/<slug>/<repo> diff --name-only        # unstaged
+git -C anvil/<slug>/<repo> diff --cached --name-only  # staged
+```
+
+Capture per repo:
+- branch + base
+- # of commits ahead of base
+- dirty? (uncommitted changes — itemize files)
+- unpushed? (local commits not on remote)
+- last commit message + date (a one-line "where I was")
+
+## Step 3 — Open PRs and their state
+
+For each repo's branch, look up the PR:
+
+```bash
+gh -R <owner>/<repo> pr list --head "$branch" --state open \
+  --json number,url,isDraft,mergeStateStatus,statusCheckRollup,reviews,reviewRequests
+```
+
+If a PR exists, also pull:
+
+```bash
+gh -R <owner>/<repo> pr view <num> --json title,body,comments,reviewDecision
+gh api repos/<owner>/<repo>/pulls/<num>/comments    # inline review threads
+```
+
+For each PR, capture:
+- number + URL + draft/ready
+- CI status (failing / pending / green)
+- review state (approved / changes-requested / pending)
+- **unaddressed comments**: review threads where the last reply is from a
+  reviewer and not the author, and the thread is not marked resolved. These are
+  the most important things for the next person to handle.
+
+Note repos with no PR yet — that's a follow-up item.
+
+## Step 4 — Decisions, TODOs, open questions
+
+Extract from sources in this order:
+
+1. `anvil/<slug>/CLAUDE.md` — any free-text decisions the user wrote.
+2. `anvil/<slug>/PLAN.md` — pending plan items (unchecked boxes).
+3. Recent commits with subjects like `chore:`, `fixup!`, `WIP:` — flag these
+   as "needs cleanup before merge."
+4. `git -C anvil/<slug>/<repo> diff "origin/$base"...HEAD | grep -E '^\+.*(TODO|FIXME|XXX)'`
+   — TODOs the user introduced in this feature.
+5. The most recent Claude Code session transcript for this feature (under
+   `~/.claude/projects/.../*.jsonl` matching this workspace), if accessible —
+   skim the last summary block for "next steps" / "blocked on" phrases. Don't
+   re-read the entire session.
+
+If extraction yields nothing concrete, leave the section as
+"(no explicit open questions captured — ask the original author)."
+
+## Step 5 — Write HANDOFF.md
+
+Write to `anvil/<slug>/HANDOFF.md` (overwrite if it exists; back up the old one
+to `HANDOFF.md.bak` first). Structure:
+
+```markdown
+# Handoff: <slug>
+
+> Generated <YYYY-MM-DD HH:MM> by agentforge-context-handoff.
+> This file is informational. Source of truth is git + the open PRs.
+
+## Feature
+
+<one-paragraph description from CLAUDE.md>
+
+Started <date>. <N> repo(s) in scope.
+
+## State at handoff time
+
+| Repo | Branch | PR | CI | Reviews | Dirty? | Unpushed? |
+|---|---|---|---|---|---|---|
+| <repo-1> | <branch-1> | #<N> | <icon> | <state> | <yes/no> | <yes/no> |
+| ... |
+
+## What's done
+
+- <repo-1>: <N> commits ahead — <high-level summary of what the diff does>
+- <repo-2>: ...
+
+## What's pending
+
+### Unaddressed review comments
+- <repo-1> #<N>: <comment thread summary + file:line + reviewer> → <link>
+- ...
+
+### Open questions
+- <extracted question 1>
+- ...
+
+### TODO markers introduced in this feature
+- <file:line>: <TODO text> (<repo>)
+- ...
+
+### Plan items not yet done
+- [ ] <item from PLAN.md>
+- ...
+
+## Where to look next
+
+- <repo-1>/<file>:<line> — most recently edited; <last commit message>
+- ...
+
+## How to resume
+
+1. `cd anvil/<slug>/` and start a session (`claude` or your CLI).
+2. Read this file first.
+3. Read each open PR's unaddressed comments.
+4. Run `agentforge-feature-resume` (if available) for an AI briefing.
+```
+
+After writing, print the path and a one-line summary to the user.
+
+## Step 6 — (Optional) PR comments
+
+Ask the user explicitly: "Post a handoff summary as a comment on each open PR?
+(default: no)"
+
+Only on "yes":
+
+```bash
+# Summarize for PR audience (different from the full HANDOFF.md — shorter,
+# focused on what reviewers need to know to keep the PR moving)
+gh -R <owner>/<repo> pr comment <num> --body "<summary>"
+```
+
+The PR comment should include:
+- "Handoff posted on <date>" + link to `anvil/<slug>/HANDOFF.md` path (relative)
+- A short list of "what's pending on this PR specifically"
+- Who the next person to contact is, if known
+
+**Never post comments without explicit user confirmation** — comments are
+visible to teammates and can confuse them if posted prematurely.
+
+## Rules
+
+- **Read-only on existing files** — never edit `CLAUDE.md`, `PLAN.md`, code, or
+  PR descriptions. Only write the new `HANDOFF.md`.
+- **No git push, no PR merge, no PR review.**
+- **PR comments only with explicit confirmation.**
+- **Back up before overwrite** — if `HANDOFF.md` exists, move it to
+  `HANDOFF.md.bak` first (don't silently overwrite).
+- **Branch names from worktrees, not slug** — per-repo branches may differ.
+- **Dirty worktrees are the #1 thing to flag** — uncommitted work is invisible
+  to anyone but the original author; the handoff exists primarily to surface
+  this.
+
+## Output language
+
+{{OUTPUT_LANGUAGE_INSTRUCTION}}

package/dist/templates/cross-repo-impact.SKILL.md.tpl

@@ -0,0 +1,241 @@
+---
+name: agentforge-cross-repo-impact
+description: Traces the blast radius of a change across every repo in the workspace. Given a symbol (function, class, type, API endpoint, env var, config key) or the current worktree's diff, finds all the places in other repos that depend on it, classifies each usage (call site / import / HTTP caller / string reference), and flags breaking-change risks. Triggers on "what's the impact of this change?", "where else is X used?", "if I rename this, what breaks?", "blast radius of …", "any callers in other repos?".
+---
+
+# cross-repo-impact
+
+This is the multi-repo workspace's blast-radius tool. When the user changes something in
+one repo, this skill finds every other repo in the workspace that touches it and
+reports the impact, grouped by repo and by usage kind.
+
+**Read-only.** This skill never modifies code.
+
+## When to apply
+
+Trigger on questions like:
+- "What's the impact of this change?"
+- "Where else is `<symbol>` used?"
+- "If I rename / change the signature of `<symbol>`, what breaks?"
+- "Blast radius of removing endpoint `/v1/things`?"
+- "Anything in admin-web that calls this?"
+
+If the user is mid-implementation and asks "before I touch this, who uses it?" — that's
+this skill.
+
+## Locate the workspace
+
+This skill needs the workspace layout (`repos/` and possibly `anvil/<slug>/`). Walk up
+from cwd until you find a directory containing `repos/`. If no such directory is found,
+tell the user: "Not inside an agentforge workspace — falling back to current repo only,"
+and proceed with cwd as the single search target.
+
+The source repo (where the change lives) is determined from cwd:
+- `…/anvil/<slug>/<repo>/` → source = that `<repo>`; search the **other** `repos/*`
+  (and other `anvil/<slug>/*` worktrees) for usages.
+- `…/repos/<name>/` → source = `<name>`; search the other `repos/*`.
+- Elsewhere → ask the user which repo is the source.
+
+The search set is every `repos/<other>/` plus every `anvil/<other-slug>/<other-repo>/`
+the user wants included (default: just `repos/*` to avoid duplicate hits from sibling
+worktrees of the same repo).
+
+## Determine what to analyze
+
+Two modes:
+
+### Mode A — user names a target
+
+The user gives one or more of:
+- A symbol name (`doSomething`, `User`, `SomeType`)
+- An HTTP endpoint (`POST /v1/things`, `/api/users/:id`)
+- A config / env key (`KAFKA_BROKER_URL`, `feature.search-ranking.enabled`)
+- A message / event name (`ItemCreated`, `something.changed`)
+
+Use this verbatim.
+
+### Mode B — auto from worktree diff
+
+If the user says "what does this change touch?" without naming a target, derive
+candidates from the current diff:
+
+```bash
+git -C <source-repo> diff --unified=0 <main-branch>...HEAD
+```
+
+Extract candidate targets:
+- **Function / method renames or signature changes** — look for hunks where a `def`,
+  `function`, `fun`, `func` line was modified.
+- **Newly exported / removed symbols** — look for changes in `export`, `pub`, public
+  visibility.
+- **HTTP route changes** — look for hunks containing route decorators / annotations
+  (`@RequestMapping`, `@Get(`, `app.get(`, `@router.get`, Gin/Fiber/Express patterns).
+- **Removed env / config keys** — look for `process.env.X`, `System.getenv("X")`,
+  `os.getenv("X")`, `viper.GetString("X")` patterns that disappeared.
+- **Type / schema changes** — modified `interface`, `type`, `class`, `data class`,
+  `struct`, proto fields.
+
+Show the user the candidate list and ask them to pick which ones to analyze. Don't
+silently analyze everything — the diff may contain noise.
+
+## Detect languages per target repo
+
+For each repo in the search set, sample a few source files to infer language(s):
+
+```bash
+find <repo> -maxdepth 3 -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.kt' \
+  -o -name '*.java' -o -name '*.py' -o -name '*.go' -o -name '*.rs' \
+  -o -name '*.rb' -o -name '*.php' \) 2>/dev/null | head -10
+```
+
+Per-language search idioms (use whichever applies):
+
+| Language | Call / use patterns |
+|---|---|
+| TypeScript / JavaScript | `\bX\(` , `import {[^}]*X[^}]*}` , `from ['"][^'"]*['"]` |
+| Kotlin / Java | `\.X\(` , `import .*\.X` |
+| Python | `\bX\(` , `from .* import .*X` , `import .*X` |
+| Go | `\.X\(` , `X\(` (after dot-less import) |
+| Rust | `::X\(` , `\.X\(` , `use .*::X` |
+| Ruby | `\.X\b` , `X\(` |
+| PHP | `->X\(` , `::X\(` , `use .*\\X` |
+
+For HTTP endpoints, search for the literal path in any source/config file (route
+strings are usually written as-is in client code), not just the framework idiom. For
+config / env keys, grep the literal key name.
+
+## Standard exclusions (apply to every grep / search in this skill)
+
+Always exclude these from any code search to avoid noise + speed up big repos:
+
+```
+:!node_modules :!dist :!build :!target :!.next :!.nuxt :!.venv :!__pycache__
+:!*.lock :!package-lock.json :!yarn.lock :!pnpm-lock.yaml :!Cargo.lock
+:!*.min.js :!*.bundle.js :!coverage :!.git :!vendor
+```
+
+With `git grep`, pass them as pathspec exclusions:
+```bash
+git -C <repo> grep -nE '<pattern>' \
+  -- ':!node_modules' ':!dist' ':!build' ':!target' ':!.next' \
+     ':!*.lock' ':!coverage' ':!vendor'
+```
+
+With plain `grep -r`, use `--exclude-dir=` / `--exclude=` repeatedly. If the user has
+a `.gitignore`, prefer `git grep` (which already honors it).
+
+## Search & classify
+
+For each (target, target-repo) pair, run the searches and classify each hit into one
+of these kinds:
+
+| Kind | Signal |
+|---|---|
+| 📞 **Call site** | symbol invoked: `X(...)` |
+| 📥 **Import** | imported but not yet shown to be called in the surrounding hunk |
+| 🌐 **HTTP caller** | code that opens the URL (axios/fetch/http client) targeting the endpoint string |
+| 🔤 **String reference** | literal name appears in a log message, config, schema |
+| 🧩 **Type usage** | the changed type appears in a signature, declaration, or generic parameter |
+| 📜 **Schema / proto** | reference in a `.proto`, OpenAPI, JSON schema, SQL migration |
+| 🧪 **Test reference** | hit is inside a test file (`*test*` , `__tests__`, etc.) |
+
+Test hits are reported separately because they signal regression coverage rather than
+production risk.
+
+## Breaking-change assessment
+
+For each target, decide what kind of change it is and what that means for callers:
+
+| Change kind | Effect on call sites |
+|---|---|
+| **Renamed** | All non-test call sites break — they need updating. |
+| **Removed** | Hard break for all kinds. Highest urgency. |
+| **Signature changed** (params added / removed / reordered / typed) | Call sites with the old shape break. Required vs optional parameters matter — note the difference. |
+| **Return type changed** | Callers consuming the return value need updating. |
+| **Behavior changed (same signature)** | Compiler / type checker won't catch it. Manual review per call site. |
+| **New symbol** | No callers can break yet, but document it for discoverability. |
+| **Endpoint URL changed** | HTTP callers using the old path break. Headers / methods matter too. |
+| **Env / config key renamed** | Deployments need re-configuring before code roll-out. Mention deployment ordering. |
+
+Note the trickiest case: **behavior changed, signature unchanged**. Static search can
+list call sites, but the caller code still compiles. Flag this explicitly so the user
+knows manual review is needed.
+
+## Output format
+
+```markdown
+# Cross-repo impact: <target description>
+
+> Source: `<source-repo>` (from `<cwd>`)
+> Change kind: <renamed / removed / signature / behavior / new / endpoint / config>
+> Search set: 3 repos (`admin-web`, `worker-service`, `mobile-app`)
+
+---
+
+## 💥 Breaking call sites
+
+### `admin-web` — 4 hits
+
+| File | Line | Kind | Snippet |
+|---|---|---|---|
+| `src/pages/things.tsx` | 42 | 📞 Call site | `doSomething(id)` |
+| `src/api/things.ts` | 11 | 📥 Import | `import { doSomething } from '@/api'` |
+| `src/components/SomeButton.tsx` | 88 | 📞 Call site | `await doSomething(...)` |
+| `src/__tests__.test.ts` | 19 | 🧪 Test | `doSomething(mockInput)` |
+
+### `mobile-app` — 1 hit
+
+| File | Line | Kind | Snippet |
+|---|---|---|---|
+| `src/handlers/things.kt` | 102 | 📞 Call site | `someClient.doSomething(...)` |
+
+---
+
+## ⚠️ Same-signature behavior changes
+
+If applicable, list call sites that won't be caught by the compiler but may behave
+differently. Same table layout.
+
+---
+
+## ✅ Safe references (no action needed)
+
+Things that match the symbol name but are unrelated (different scope, comment, log
+string). Keep this list short — only include hits that the user might worry about.
+
+---
+
+## Summary
+
+- `admin-web`: 3 production + 1 test → must update before merge
+- `mobile-app`: 1 production → must update before merge
+- `worker-service`: no hits
+
+Suggested next steps:
+1. Update `admin-web` first (largest blast radius).
+2. Coordinate deploy ordering: backend-api before clients.
+3. Add a deprecation shim if you can't update all clients in one go.
+```
+
+Group by repo, then by file. Always include the snippet (one line). Don't truncate
+file paths.
+
+## Rules
+
+- **Never edit code.** Report only.
+- **Don't claim a hit is broken without seeing it.** When the snippet alone is
+  ambiguous (e.g. the symbol name is a common word), open the file and confirm scope.
+- **Respect the workspace boundary.** Only search `repos/*` (and explicitly-included
+  worktrees). Don't escape into the user's home directory or unrelated dirs.
+- **Distinguish production vs test hits.** Both matter, but test hits are coverage
+  signal, not regression risk.
+- **Acknowledge unknowns.** If a language in the workspace isn't in the table above,
+  fall back to a plain symbol-name grep and tell the user the analysis is best-effort.
+- **Common names need extra care.** A symbol called `get` or `update` will match
+  noise — narrow the search using import paths or enclosing scope before reporting.
+- **Don't truncate.** If there are too many hits, summarize counts per file but still
+  list every file.
+
+## Output language
+
+{{OUTPUT_LANGUAGE_INSTRUCTION}}