manage-refs

Manage the ## References section in AGENTS.md. This section is a minimal list of pointers to documents the agent may need (planning, design, spec, architecture, decisions) — not the documents themselves.

Philosophy. Document content lives in files. AGENTS.md's job is to tell the agent "when you need architectural context, look here; when you need the API spec, look there." The agent reads the actual file on demand via its Read tool. This skill never auto-loads, never builds an index, never copies content.

Scope

In scope:

• Add a new path to ## References
• Remove an existing path from ## References
• Verify all listed paths exist on disk (and offer to prune dead ones)
• Create the ## References section if it does not exist

Out of scope:

• Managing document content or format
• Building an INDEX.md or any folder registry
• Status tracking (use an issue/project tracker)
• Merging, sorting, or formatting prose inside the referenced documents
• External URL references (URLs are allowed in the section but not validated)
• Documents inside .git/, node_modules/, or other build/dependency paths

Guardrails

#	Check	On failure
1	CWD is a Git repository	"Please run this inside a Git repository."
2	AGENTS.md exists	"AGENTS.md not found. Run /init-public-rules first."
3	Path being registered contains @ prefix (e.g., @docs/foo.md)	"The @path syntax auto-loads files into context at session start. Use a plain path like docs/foo.md or a markdown link instead. Stopping."
4	Path being registered is outside the repo or does not exist	"The path <path> does not exist in this repository. Create the file first or check the path."
-	Skill update check	Let SELF be the value of the name field in this SKILL.md's frontmatter (e.g., init-public-rules). Let LOCAL be metadata.version from this same frontmatter. Fetch https://raw.githubusercontent.com/dev-goraebap/agent-collabo/main/manifest.json (1 HTTP request, fail silently on network error). Then evaluate exactly one case in this order: Case A — outdated: if manifest.skills[SELF] exists and LOCAL < manifest.skills[SELF], tell the user (in their language) "agent-collabo {SELF} has a new version ({LOCAL} → {manifest.skills[SELF]}). Run /agent-collabo-updater when convenient. Continuing with the current task." then proceed. Case B — up to date: if manifest.skills[SELF] exists and LOCAL === manifest.skills[SELF], proceed silently. Case C — renamed away: if SELF does NOT exist as a key in manifest.skills AND SELF exists as a key in manifest.deprecated (note: check the keys of deprecated, not the renamedTo values), tell the user "This skill {SELF} was renamed to {manifest.deprecated[SELF].renamedTo} since v{manifest.deprecated[SELF].since}. Run /agent-collabo-updater to migrate." then proceed. Case D — unknown: if SELF is not in manifest.skills and not in manifest.deprecated, tell the user "Skill {SELF} is no longer maintained. Run /agent-collabo-updater to clean up." then proceed with caution. Important: manifest.deprecated maps OLD names → NEW names. Never warn about a skill whose name is currently in manifest.skills just because that name appears as a renamedTo value somewhere in deprecated. CDN cache caveat: GitHub raw enforces Cache-Control: max-age=300, so right after a new release is pushed the manifest may be stale for up to 5 minutes via Fastly PoPs. If the user explicitly mentions they just released a new version (e.g., "I just pushed v0.X.Y") and this check still reports up-to-date or shows an older manifest.version, do not insist the local install is current — instead mention the 5-minute CDN window and suggest retrying shortly. For all other users this is invisible because they fetch long after the cache expires.

Language Policy

Conduct all user-facing communication in the user's language: interview questions, follow-up prompts, status messages, diagnostic reports, and summaries. Detect the language from (in order):

1. The language of the user's most recent messages in the current session
2. Declarations in their local rules file (e.g., CLAUDE.local.md, .cursor/rules/local.mdc) — look for instructions like "respond in Korean"
3. OS locale ($LANG, $LC_ALL)
4. English as fallback

Generated file content follows the file's audience: team-shared files (AGENTS.md, CHANGELOG.md) stay in English regardless of the user's language; personal files (CLAUDE.local.md, GEMINI.local.md, etc.) use the user's language unless they specify otherwise.

Entry format

Entries in ## References follow a consistent single-line format:

## References

- `docs/system-design.md` — Distributed architecture and data flow
- `docs/api-spec.md` — REST API contract
- [Payment PRD](docs/specs/payment-prd.md) — Product requirement for the payment flow

Allowed forms:

1. Backtick path + em dash + one-line description (preferred for in-repo files)
2. Markdown link + em dash + one-line description (when a title is more descriptive than the filename)

Forbidden:

• @path/to/file.md — Claude Code's auto-load import syntax; would pull every referenced document into always-on context
• Multi-line descriptions or nested bullets
• Categorization headers (### Design docs, ### ADRs, etc.) — keep the section flat

Workflow

Step 1: Detect intent

Determine what the user wants to do before asking anything else.

Entry signal	Mode
User explicitly invoked /manage-refs	Slash mode → Step 2 (action interview)
User created a document matching spec-shaped patterns (PRD/SRS/ERD/ADR/RFC/sitemap/architecture/schema/etc.)	Auto mode → Step 2a (one-question register)
User mentioned or pasted a path to such a document in conversation	Auto mode → Step 2a

Auto-trigger principle. Never re-run the full interview from auto mode. Ask at most one yes/no question, then act or exit.

Step 2: Action interview (slash mode)

What would you like to do?

1. Add a reference
2. Remove a reference
3. Verify all references (checks paths exist on disk)
4. Cancel

Only one action per invocation.

Step 2a: One-question register (auto mode)

The file `<path>` looks like a planning/design document. Register it
in AGENTS.md's ## References section?

1. Yes — register
2. No — skip this time
3. Never — this is not a spec document

If the section does not exist, create it before appending. If the user picks "No", exit silently. If the user picks "Never", note the exclusion for the session only (do not persist a denylist — the skill is stateless).

Step 3a: Add

1. Ask for the path if not already provided by auto-trigger. Accept either a bare path or a markdown link.
2. Apply Guardrail 3 (reject @) and Guardrail 4 (path must exist).
3. Ask for a one-line description:

   One-line description for this reference (what the agent should
   expect to find here):
   

4. If ## References does not exist in AGENTS.md, create it at the end of the file (after ## Boundaries if present, otherwise as the last section).
5. Append the entry. Do not sort or reorder existing entries.
6. Show the resulting section and confirm.

Step 3b: Remove

1. Parse the current ## References section and list entries with indices:

   Current references:
   
   1. `docs/system-design.md` — Distributed architecture and data flow
   2. `docs/api-spec.md` — REST API contract
   3. [Payment PRD](docs/specs/payment-prd.md) — Product requirement for the payment flow
   
   Which entry to remove?
   

2. Accept an index, a path, or a link title.
3. Remove the matching entry. If nothing matches, report and stop.
4. If the section is now empty, ask:

   The ## References section is now empty. Remove the section header too?
   

Step 3c: Verify

1. Parse the current ## References section.
2. For each entry, resolve the path and check existence on disk.
3. Report:

   References in AGENTS.md (3):
   
   ✅ docs/system-design.md
   ✅ docs/api-spec.md
   ❌ docs/specs/payment-prd.md — FILE NOT FOUND
   
   1 dead reference found. Remove it from ## References?
   1. Yes
   2. No
   

4. On "Yes", remove dead entries and show the updated section.

URL entries (starting with http:// or https://) are not validated; they are reported as "🔗 external".

Step 4: Summary

✅ Done.

Current ## References section:

- `docs/system-design.md` — Distributed architecture and data flow
- `docs/api-spec.md` — REST API contract
- `docs/specs/payment-prd.md` — Payment flow product requirement

Tip: run `/manage-refs` with "Verify" periodically to catch paths
that moved or were deleted.

Interaction with other skills

• /audit-rules runs R1 (dead reference paths) against the same section. When R1 reports dead paths, re-run /manage-refs (Verify action) to prune.
• /init-public-rules does not create a ## References section — it is created lazily by this skill on first add.
• /work-unit-ritual reads ## References at runtime to understand the project's planning/design landscape, but does not write to it.

Prohibited actions

• Never use @path import syntax — always plain paths or markdown links
• Never batch-register multiple files in one run (one path per invocation keeps the skill predictable)
• Never read or summarize the content of referenced documents — this skill only manages pointers
• Never create subsections inside ## References — keep it flat