manage-docs

Register and maintain project spec documents (PRD, SRS, ERD, ADR, sitemap, architecture notes) so AI agents know where to find them when they need product or design context.

This skill manages document location and registration, not document content. It does not read status fields, sync content between sources, resolve merge conflicts, or validate document quality. See Out of Scope for the boundaries.

Two modes are supported:

1. In-repo folder — A managed INDEX.md lives next to spec files (e.g., docs/specs/INDEX.md). The index is the source of truth for which specs exist and are active.
2. External platform — Specs live in Notion, Linear, Confluence, GitBook, Obsidian, or another tool with an MCP server. The platform itself is the index; this skill only adds usage convention to AGENTS.md.

Guardrails

#	Check	On failure
1	CWD is a Git repository	"Please run this inside a Git repository."
2	AGENTS.md exists (warning, non-blocking)	"AGENTS.md not found. Run /init-public-rules first for best results. Continuing."
3	Attempting to register an out-of-scope file (README, CHANGELOG, AGENTS.md, auto-generated docs)	" is not a managed spec type. See references/managed-doc-types.md for the in-scope list. Stopping."
4	INDEX.md contains git merge markers (<<<<<<<)	"INDEX.md has unresolved merge conflicts. Resolve them and re-run /manage-docs."
-	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-collab/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-collab {SELF} has a new version ({LOCAL} → {manifest.skills[SELF]}). Run /agent-collab-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-collab-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-collab-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.

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.

Workflow

Step 1: Detect intent

Determine the entry mode before doing anything else.

Entry signal	Treatment
User explicitly invoked /manage-docs (or similar phrasing)	Slash mode → go to Step 2 (action interview)
User created a spec-shaped file (e.g., payment-prd.md, erd-v2.md, adr-001-cache.md)	Auto mode → see Auto-trigger handling below
User asked to write a PRD/ERD/ADR but no file exists yet	Auto mode → see Auto-trigger handling below
User pasted a Notion/Linear/Confluence/GitBook URL while discussing specs	Auto mode → see Auto-trigger handling below

Auto-trigger handling principle: Never re-run the full setup interview from auto mode. At most ask one or two yes/no questions, then either act or step out cleanly.

Situation	Setup state	Behavior
User created/asked for a spec file	Not set up	Print one-line guidance: "No spec folder is configured. Run /manage-docs to set one up." Then exit.
User created/asked for a spec file	Set up (in-repo)	Ask: "Register this in [folder]/INDEX.md? (y/n)". If yes → go to Step 3b.
User created a spec file outside the managed folder	Set up (in-repo)	Ask: "This looks like a spec but is outside [folder]. Move it and register? (y/n)". If yes → move + Step 3b.
User pasted a platform URL	Set up (matching external platform)	Ask: "Add this page to the active references in AGENTS.md? (y/n)". If yes → update.
User pasted a platform URL	Not set up, or different platform	Print one-line guidance and exit.

Step 2: Action interview (slash mode)

Ask which action to perform. Only one action per invocation.

무엇을 하시겠어요?

[ ] 처음 셋업 — in-repo 폴더 또는 외부 플랫폼 등록
[ ] 새 spec 추가 — 기존 인덱스/AGENTS.md에 항목 추가
[ ] 정리 — 사라진 파일(dangling) 검사 및 archive 이동
[ ] 상태 확인 — 현재 인덱스 요약 출력

If setup has not been done yet, "처음 셋업" is forced (other options are skipped).

Step 3a: First-time setup

Ask where the project's spec documents will live.

spec 문서를 어디서 관리하시나요?

[ ] in-repo 폴더 — 이 git repo 안에 폴더로 같이 관리
[ ] 외부 플랫폼 — Notion / Linear / Confluence / GitBook / Obsidian / 기타
[ ] 아직 없음 — in-repo 폴더만 만들고 나중에 채울 예정

Branch A: in-repo folder

1. Folder name. Ask:

   폴더 이름을 선택하세요:
   
   [ ] docs/specs   (권장: docs 폴더 안에 specs 하위)
   [ ] specs        (루트에 specs 폴더)
   [ ] docs         (모든 문서를 docs에 통합)
   [ ] wiki         (wiki 명칭 선호)
   [ ] 직접 입력
   

   Default: docs/specs. If the chosen folder already exists and contains files, ask whether to use it as-is or create a fresh subfolder.

2. Git tracking. Default to tracking. Ask only if the user wants to override:

   "이 폴더는 기본적으로 git에 추적됩니다 (PRD/ERD는 팀 자산). gitignore에 추가하시려면 알려주세요."

3. Create folder + INDEX.md. Read references/index-template.md and write it to <folder>/INDEX.md. Do not create any other files.

4. Add ## Specs section to AGENTS.md. Append (or create) the section using this exact wording:

   ## Specs
   
   This project's spec documents (PRD, ERD, architecture, ADRs) live in
   `<folder>/`. The index is at `<folder>/INDEX.md` — read it before working
   on features that need product or design context. Do not assume specs
   exist; always check the index.
   
   When you create or remove a spec, run `/manage-docs` to keep the index
   in sync.
   

   If a ## Specs section already exists, ask whether to overwrite or merge.

5. Print summary (see Step 4).

Branch B: external platform

1. Choose platform. Present this list:

   어느 플랫폼을 사용하시나요?
   
   [ ] Notion
   [ ] Linear
   [ ] Confluence (Atlassian)
   [ ] Jira
   [ ] GitBook
   [ ] Obsidian
   [ ] Google Docs
   [ ] Coda
   [ ] 기타 (직접 입력)
   

2. Verify integration availability. Read references/platform-integration-matrix.md for the per-platform check. For each platform the matrix lists multiple integration paths in priority order — MCP server, official CLI, Claude Code skill plugin (e.g., makenotion/claude-code-notion-plugin), or community alternatives. Detect them in order:

   1. Is a matching MCP tool prefix loaded in the current agent session?
   2. Is the official CLI on PATH?
   3. Is a corresponding skill plugin installed?
   • At least one available → continue to step 3.
   • None available → print the install hint from the matrix and stop. Do not create the AGENTS.md section. The user can re-run after installing any one of the listed paths.

   This is strict mode by design. A registration without a working integration path produces broken references.

3. Collect identifiers. Ask for the workspace, team, or root page ID that scopes this project's specs (varies per platform — see the matrix).

4. Add ## Specs (<Platform>) section to AGENTS.md. Use this template, filling in platform-specific fields:

   ## Specs (<Platform>)
   
   This project's spec documents live in <Platform>, not in this repo.
   
   - <Identifier label>: <value>
   - <Optional URL>: <value>
   
   To reference a spec:
   1. Use the <Platform> MCP (`<mcp tool prefix>`) to search and load pages
      under the identifier above.
   2. Never copy spec bodies into the repo — <Platform> is the source of truth.
   
   ### Active references
   <!-- managed by /manage-docs -->
   (none yet)
   

   The ### Active references list is the only part this skill keeps mutating after first setup. Section header text must not be edited by hand.

5. Print summary (see Step 4).

Branch C: empty folder (none yet)

Same as Branch A but skips the spec-file-related steps. Creates folder + empty INDEX.md + AGENTS.md ## Specs section. Useful when starting a new project that will accumulate specs over time.

Step 3b: Add a new spec

1. Identify scope. If the input is a file path, verify it points to a managed doc type by reading references/managed-doc-types.md. If it's a platform URL/page id, verify the platform matches the registered external platform.

   • Out-of-scope (e.g., README, CHANGELOG, OpenAPI output) → reject with reason. Do not register.

2. Collaboration check (in-repo only). Ask once:

   이 문서는 누가 관리하나요?
   
   [ ] 나 혼자 — 자유롭게 수정
   [ ] 팀과 공유 — 협업 가이드 출력
   

   This answer is not stored anywhere. It only changes which guidance text is printed in the summary.

3. Update the index.

   • In-repo: Add the file path under ## Active work in INDEX.md. Insert in alphabetical order. Do not add timestamps, owners, or status comments — keep entries to one line.
   • External: Add the page title + id under ### Active references in the AGENTS.md section. Insert in alphabetical order.

4. Print collaboration guidance if the user chose "팀과 공유". See references/index-template.md for the exact text. Otherwise just print the success line.

Step 3c: Prune

Run only against in-repo mode. External platforms are not pruned (would require platform API calls and risk false positives).

1. Dangling check. For every entry in INDEX.md (Always-on + Active work), verify the file exists. Collect missing entries.

2. Report and confirm. Show the dangling list to the user. Ask:

   다음 항목들이 사라졌습니다. 어떻게 처리할까요?
   
   [ ] Archive로 이동 (히스토리 보존)
   [ ] 완전히 제거
   [ ] 그대로 두기
   

3. Apply the chosen action. Never auto-delete without confirmation.

4. The ## Archived section keeps entries as plain (non-imported) lines for history.

Step 3d: Status

Print a one-screen summary of the current index state. No mutations.

Spec index at <folder>/INDEX.md

  Always-on:    <N> entries
  Active work:  <M> entries
  Archived:     <K> entries
  Dangling:     <D> entries  (run /manage-docs prune to handle)

Recent additions (top 3 in Active work):
  - <path>
  - <path>
  - <path>

For external platform mode, list ### Active references from the AGENTS.md section instead.

Step 4: Summary

Print what was done plus a short pointer to next steps.

Done:
  - <folder>/INDEX.md created / updated
  - AGENTS.md "## Specs" section added / updated

Next:
  - Add specs to <folder>/ and run /manage-docs to register them.
  - Run /manage-docs to prune missing entries when you finish working on
    a spec.
  - This skill does not track document status, ownership, or content. See
    "Out of Scope" in this skill for what is intentionally not handled.

Out of Scope

This skill manages document registration and location, not document content. The following are intentionally NOT handled:

• Document status / lifecycle fields. Frontmatter like status: draft|review|approved, checkboxes, or progress markers are ignored. Use your own convention or tools like Obsidian Dataview, Notion, or Linear if you need workflow tracking.
• Content sync between in-repo files and external platforms. Pick one source of truth per document. This skill never copies content across modes.
• Merge conflict resolution. INDEX.md and spec files are normal git files. The skill keeps entries sorted alphabetically to reduce conflict frequency, but does not resolve conflicts when they happen.
• Auto-generated docs (OpenAPI/Swagger output, JSDoc, TypeDoc). Code is the source of truth.
• Document content quality (spelling, completeness, schema validation).
• Time-based expiration / TTL. No automatic pruning based on age. The skill only removes entries the user explicitly approves.
• Collaboration metadata storage. The "혼자 vs 팀" question at registration time only changes printed guidance. Nothing is persisted.
• Private (gitignored) spec management. This skill is for shared, public spec documents. Personal notes belong in your private rules file (see /init-private-rules).

If you need any of these, the skill will not become the tool — but it will not get in the way of one either.

Collaboration Notes

Suggested patterns when multiple contributors edit specs. These are guidance only; the skill does not enforce them.

• One owner per spec document. Treat each PRD/ADR/ERD like a code module — assign someone responsible for changes.
• PR-based changes. Avoid direct push to spec files. Code review applies to specs too.
• Big revisions become new ADRs, not edits to existing ones. Preserve history.
• INDEX.md merge conflicts — entries are sorted alphabetically, so most adds auto-merge. When a conflict occurs, resolve manually and run /manage-docs (status action) to verify.
• If real-time co-editing is essential, use the external platform mode (Notion/Confluence/Linear) instead of in-repo folders. In-repo folders are optimized for git workflow, not concurrent editing.

Relationship to other skills

• /init-public-rules — creates AGENTS.md. Run this before /manage-docs so the ## Specs section has a file to live in.
• /init-private-rules — manages personal config. Spec management is not part of personal config in v0.1.
• /audit-rules — audits AGENTS.md and other rule files. It does not yet validate INDEX.md; that integration is on the roadmap.

References

• references/managed-doc-types.md — In-scope vs out-of-scope document types
• references/platform-integration-matrix.md — Per-platform integration paths (MCP / CLI / skill plugin) and install hints
• references/index-template.md — INDEX.md seed structure and collaboration guidance text
• references/sources.md — External sources used in the skill design