From octo
Scans project .md files and syncs with git diff: auto-updates factual content (paths, counts, versions, tables); flags risky narrative edits; updates PR body post-PR.
npx claudepluginhub nyldn/claude-octopus --plugin octoThis skill uses the workspace's default tool permissions.
Automated documentation synchronization for the Deliver phase. After code is committed and a PR is created, this skill reads all `.md` files in the project, cross-references the diff, auto-updates factual content, checks cross-doc consistency, and updates the PR body.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Automated documentation synchronization for the Deliver phase. After code is committed and a PR is created, this skill reads all .md files in the project, cross-references the diff, auto-updates factual content, checks cross-doc consistency, and updates the PR body.
Find all .md files in the project root (max depth 2), skipping node_modules/ and .git/.
# Discover all markdown files (max depth 2, skip noise directories)
DOC_FILES=$(find . -maxdepth 2 -name '*.md' \
-not -path './node_modules/*' \
-not -path './.git/*' \
-not -path './vendor/*' \
-not -path './.claude/*' \
2>/dev/null | head -30)
DOC_COUNT=$(echo "$DOC_FILES" | wc -l | tr -d ' ')
echo "Found $DOC_COUNT doc files to scan (cap: 30)"
if [[ "$DOC_COUNT" -ge 30 ]]; then
echo "WARNING: Doc file cap reached (30). Some files may be skipped."
fi
Read each discovered doc file so you have their current content in context.
Run git diff --stat HEAD~1 (or diff against the base branch if on a feature branch) to identify which files changed and what content may now be stale in each doc.
# Get the diff stat to identify changed files
BRANCH=$(git rev-parse --abbrev-ref HEAD)
if [[ "$BRANCH" == "main" || "$BRANCH" == "master" ]]; then
DIFF_STAT=$(git diff --stat HEAD~1)
DIFF_FULL=$(git diff HEAD~1)
else
BASE_BRANCH=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null)
DIFF_STAT=$(git diff --stat "$BASE_BRANCH"..HEAD)
DIFF_FULL=$(git diff "$BASE_BRANCH"..HEAD)
fi
echo "$DIFF_STAT"
For each doc file, check whether any paths, function names, counts, or version numbers mentioned in the doc were affected by the diff.
Fix paths, counts, table entries, and version numbers automatically. These are mechanical changes that do not alter meaning.
Auto-update targets:
v9.5.0 when package.json bumped)WHY: Stale factual references erode trust in documentation. A user who sees a wrong path or count will doubt everything else in the doc.
Flag narrative, philosophy, or security-related doc sections for user confirmation. Do NOT auto-edit these.
Risky categories (require user approval):
## Why or ## Rationale headingsSECURITY.md or CONTRIBUTING.md beyond version bumpsWHY: Narrative and philosophy sections reflect human judgment. Silently rewriting them risks misrepresenting the project's intent.
When risky changes are detected, present them to the user:
The following doc sections may need updating but contain narrative/philosophy content.
I will NOT auto-edit these. Please review and confirm each change:
1. README.md ## Philosophy — mentions "single-binary deployment" but diff adds Docker support
2. SECURITY.md ## Threat Model — new auth endpoint not documented
Approve changes? (list numbers to approve, or "skip all")
Apply the "sell test" to every CHANGELOG entry: "Would a user reading this bullet think 'oh nice, I want to try that'?"
Rules:
Example transformations:
BAD: "Refactored spawn_agent to use parameter expansion instead of basename"
GOOD: "Speed up agent spawning by eliminating 750 subshell forks (92% reduction)"
BAD: "Added SUPPORTS_MCP_ELICITATION flag"
GOOD: "Support MCP elicitation for richer interactive prompts (CC v2.1.76+)"
WHY: The CHANGELOG is marketing copy for developers. Every bullet should make someone want to upgrade.
Check that key values are aligned across all documentation files.
Consistency checks:
README.md, CLAUDE.md, package.json, CHANGELOG.md, and any other files referencing the current version# Example: check version consistency
PKG_VERSION=$(grep '"version"' package.json | head -1 | sed 's/.*"version": *"//' | sed 's/".*//')
echo "package.json version: $PKG_VERSION"
# Check README mentions this version
if ! grep -q "$PKG_VERSION" README.md 2>/dev/null; then
echo "WARNING: README.md does not mention version $PKG_VERSION"
fi
# Check CHANGELOG has an entry for this version
if ! grep -q "$PKG_VERSION" CHANGELOG.md 2>/dev/null; then
echo "WARNING: CHANGELOG.md has no entry for version $PKG_VERSION"
fi
Ensure every documentation file is reachable from README.md or CLAUDE.md. Orphaned docs are invisible docs.
Check:
.md file in the project should be linked from either README.md or CLAUDE.md (directly or transitively through another linked doc)WHY: Documentation that cannot be found does not exist from the user's perspective. Every doc must be one or two clicks from the entry points.
Update the project's task tracking based on the diff.
Actions:
# Find new TODOs added in the diff
NEW_TODOS=$(echo "$DIFF_FULL" | grep '^+' | grep -iE 'TODO|FIXME|HACK' | grep -v '^+++' || true)
if [[ -n "$NEW_TODOS" ]]; then
echo "New TODOs found in diff:"
echo "$NEW_TODOS"
fi
# Find TODOs removed in the diff
REMOVED_TODOS=$(echo "$DIFF_FULL" | grep '^-' | grep -iE 'TODO|FIXME|HACK' | grep -v '^---' || true)
if [[ -n "$REMOVED_TODOS" ]]; then
echo "Resolved TODOs (removed in diff):"
echo "$REMOVED_TODOS"
fi
Commit all documentation changes to the current branch and update the PR body with a doc-sync summary.
# Stage only .md files that were modified by this skill
git add *.md docs/*.md 2>/dev/null || true
# Check if there are staged changes
if git diff --cached --quiet; then
echo "No documentation changes needed — all docs are up to date."
else
git commit -m "docs: post-ship documentation sync
- Auto-updated paths, counts, and version references
- CHANGELOG entries polished for user benefit
- Cross-doc consistency verified
- Discoverability check passed
"
echo "Documentation sync committed."
fi
If a PR exists for the current branch, update its body to include a doc-sync section:
# Update PR body with doc-sync summary (if PR exists)
PR_NUMBER=$(gh pr view --json number -q '.number' 2>/dev/null || true)
if [[ -n "$PR_NUMBER" ]]; then
echo "Updating PR #$PR_NUMBER with doc-sync summary..."
fi
This skill is designed to work as a sub-step of flow-deliver. After validation and review are complete, invoke doc-sync to ensure documentation stays current with the shipped code.
Invocation from flow-deliver:
After PR creation and CI passes:
1. Run doc-sync to update documentation
2. Push doc changes to the PR branch
3. Re-run CI if doc changes affect tests
Standalone invocation:
User: "sync docs"
User: "update documentation after merge"
User: "document changes from last release"