00.Feat 260525013.Done.Docsync Close Hook

---
id: '260526001'
type: task
status: done
priority: '00'
slug: create_docs_sync_skill
title: Create /agn:docs-sync skill
---

# Create /agn:docs-sync skill

# Create /agn:docs-sync skill

## Problem statement

Users need a skill that processes the doc-sync queue, reviews upstream docs against the closed unit's body and linked spec, proposes diffs, and waits for user approval before applying changes. The skill must follow `rules/doc-maintenance.md` for what to check on closure.

## Scope

In scope:
- Create `plugins/agn/skills/docs-sync/SKILL.md`.
- Workflow:
  1. Read `tasks/docs-sync-queue.txt`. If empty, report "no pending entries" and stop.
  2. For each pending entry (task/feature/epic): load the unit file + its linked spec if any; identify which upstream docs to check per the dependency chain in `rules/doc-maintenance.md` (vision → spec → requirements → architecture → linked spec).
  3. For each upstream doc, propose diffs (or explicitly state "no update needed").
  4. Present diffs to user; iterate; apply approved diffs via Edit tool.
  5. After all approved diffs land for an entry, remove that entry from the queue.
  6. Report summary at end.
- Argument optional: `/agn:docs-sync [<queue-entry-id>]` lets user process a single entry; default processes all.

Out of scope:
- Triggering the skill (sibling task — taskman.sh hint + opt-in SessionStart hook).
- The `rules/doc-maintenance.md` content (already shipped).

## Acceptance criteria

- Skill file exists at `plugins/agn/skills/docs-sync/SKILL.md` with valid YAML frontmatter.
- Workflow processes each queue entry, proposes diffs, applies after user approval, clears entry on completion.
- Skill follows `rules/doc-maintenance.md` for what to check and when no update is needed.
- Skill explicitly handles the empty-queue case (no-op with a clear message).

## Quality gates

- Skill body parses; YAML frontmatter intact.
- `taskman.sh validate` passes (queue file outside lifecycle folders, exempt from validation).

## Summary

### Steps completed

1. Wrote `plugins/agn/skills/docs-sync/SKILL.md` (~95 lines). YAML frontmatter with optional `$1` filter (line-number, slug, or path) for selective processing.
2. Workflow defined in 3 stages: read queue → per-entry processing → final report. Per-entry processing walks the 5-doc dependency chain (vision → spec → requirements → architecture → linked spec) and surfaces either proposed diffs or an explicit no-op note.
3. Documented queue-clearing mechanics (read all lines, filter out processed line, write back via Write tool; leave file empty if all processed, don't delete the file itself).
4. Discipline section: propose-don't-commit, stay in scope, mandatory explicit no-op, dependency-order processing for multi-entry runs.
5. No-active-session fallback section documents how the queue persists, how `taskman.sh list` surfaces the hint, and points to the README's opt-in SessionStart snippet for users who want automatic surfacing.
6. Confirmed Claude Code auto-discovered the new skill (it appears in the available-skills list after creation, no plugin reconfiguration needed).

### Changes made

Created:
- `plugins/agn/skills/docs-sync/` (directory)
- `plugins/agn/skills/docs-sync/SKILL.md`

### Notable decisions

- **Optional `$1` filter for selective processing.** Default processes all entries — covers the common case (small queue, batch process). Filter handles the edge case where the user wants to address one entry now, defer others.
- **Explicit no-op is mandatory.** From `rules/doc-maintenance.md`: "Silence is worse than a deliberate no-op note." Encoded into the workflow so the skill never simply "moves on" without verdict.
- **Propose, don't commit.** Skill applies diffs via Edit tool after user approval; never runs `git add` or `git commit`. Git ownership stays with the user (matches the broader plugin pattern).
- **Don't delete the queue file when empty.** taskman.sh expects the file to exist for `check_docs_sync_queue`. Truncating to empty (no lines) is sufficient — taskman handles empty correctly (returns 0 early).
- **Multi-entry processing in dependency order.** When the queue has many entries spanning broad changes, process one at a time and present per-entry. Avoids bundling cross-cutting diffs from multiple entries into a single review, which would be hard for the user to triage.

### Links

- Skill file: `plugins/agn/skills/docs-sync/SKILL.md`
- Rules followed: `plugins/agn/rules/doc-maintenance.md`
- Sibling tasks: `design_postclose_hook`, `handle_no_active_session_fallback`