name: bulk-update

description: After a non-trivial round of changes, run the full documentation+commit cycle in one shot — PM updates PROJECT_SCOPE.md, programmer agents sync CLAUDE.md and project docs (DOCUMENTATION.md, Methodology.md, plus any new top-level *.md files), then git add/commit/push if a remote is configured. Use when the user says "bulk update", "sync docs", "finalize this round", or similar after a meaningful set of edits.

bulk-update

A one-shot orchestration to keep the project's documentation, scope record, and version control in sync after a round of code changes. Designed to be run at the END of a meaningful unit of work (a feature, a bugfix series, a refactor), NOT after every tiny edit.

When to use

User says "bulk update", "sync everything", "wrap this up", "finalize the round", or similar.
A meaningful set of changes has landed (new feature, bug fix, schema change, new file added) and the docs / scope / repo are now stale.
Skip for trivial single-line edits where the cycle would create more churn than signal.

Inputs the orchestrator gathers BEFORE spawning agents

Before launching any sub-agents, the main thread MUST collect:

Recent change summary — review the conversation transcript and git status / git diff --stat for the changes since the last commit. Write a 5-10 line plain-English summary of WHAT changed and WHY. This summary is passed to every sub-agent so they don't duplicate the investigation.
New files inventory — git status --porcelain | awk '/^\?\?/ {print $2}' plus any modified top-level files. Identify any new top-level documentation files (Methodology.md was an example) that need to be referenced from CLAUDE.md and the project README.
Remote configured? — git remote -v. If origin is set, the push step runs; otherwise it's skipped and reported.
PROJECT_SCOPE.md exists? — if not, this skill is the wrong tool; tell the user to run the PM agent in design mode first.

Orchestration plan

Run as three sequential phases. Within each phase, parallel sub-agents fan out where independent.

Phase 1 — PM updates PROJECT_SCOPE.md (sequential, 1 agent)

Spawn the PM agent with the change summary and instructions to:

Read current PROJECT_SCOPE.md.
Update Implementation Status, In-Scope, Out-of-Scope, Known Risks, and Future-Considerations sections to reflect the new reality.
Add a dated entry to any change-history section (if present).
Keep edits surgical — don't rewrite sections that haven't changed.
Report back what was changed (1-3 sentence summary).

PM is the ONLY agent allowed to edit PROJECT_SCOPE.md (per global CLAUDE.md rule). Do NOT spawn a programmer for this file.

Phase 2 — Doc + CLAUDE.md sync (parallel, N agents)

Spawn programmer agents in parallel — one per doc target. Always include:

CLAUDE.md — keep under its declared line cap (check the file's "Maintenance Rules" section); update Stack / Architecture Decisions / Pipeline / Data Layout / Frontend Pages / Conventions / Known Issues sections as relevant. Prune outdated lines; one-line-per-decision style.
DOCUMENTATION.md (if present) — update affected sections only. Common targets: §8 file layout (new scripts/files), §9 regeneration commands (new build steps), §11 change log (always append).
Methodology.md (if present) — update only if the methodology actually changed (new metric, classifier change, new data source). Pure UI changes or refactors do NOT touch Methodology.md.
README.md inside the shipping artifact (if results/<N>/README.md exists and build_app.py regenerates it) — usually skipped because build_app.py overwrites on every build. Only edit if the change affects the embedding contract.
Any other top-level .md file discovered in the new-files inventory — needs a routing decision: is it a one-off note (leave it), a permanent reference (link from CLAUDE.md + DOCUMENTATION.md §8), or a deferred-concerns log (link from CLAUDE.md "Known Issues")?

Each programmer agent gets:

The change summary from Phase 0.
The PM's scope summary from Phase 1.
The specific file(s) it owns and the sections to consider.
Explicit instruction: DO NOT touch any file outside its assigned set.

Phase 3 — Git commit + push (sequential, 1 agent or inline)

If origin is configured, run inline (no sub-agent — git operations are quick and the orchestrator has the context):

git status --short to confirm only expected files changed.
git diff --stat for the commit-message subject material.
Stage with git add -A (the .gitignore is trusted to exclude secrets and build outputs).
Commit with a HEREDOC message:
- First line: imperative subject (≤72 chars) summarizing the change.
- Body: 3-8 lines covering what changed and why, mirroring the Phase 0 summary.
- Trailing: Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Use env-var author (GIT_AUTHOR_NAME / GIT_AUTHOR_EMAIL / GIT_COMMITTER_*) if local git config user.email is unset — DO NOT modify git config.
Push: git push origin <branch> (current branch, usually master or main).
If the push is blocked by the harness's auto-classifier (external remote = potential data exfiltration), STOP and surface the block to the user with the explicit message they need to type to retry (! git push origin master). Do NOT try to bypass.

If origin is NOT configured, skip Phase 3 entirely and tell the user that the commit was made locally only.

What to report at the end

A compact 4-6 line summary covering:

PROJECT_SCOPE.md sections that PM updated (or "no changes needed").
Files synced in Phase 2 (CLAUDE.md, DOCUMENTATION.md, Methodology.md, etc.) with line-count deltas.
Commit SHA + push outcome.
Any blockers or follow-ups (e.g., harness blocked the push, new file needs a manual routing decision).

Anti-patterns

DO NOT run this skill after every conversation turn. It's a wrap-up tool.
DO NOT spawn a programmer to edit PROJECT_SCOPE.md — global rule says PM only.
DO NOT bypass the gitignore. Trust it; if something sensitive leaks, fix the gitignore in a follow-up commit rather than untracking files mid-push.
DO NOT re-derive the change summary inside each sub-agent's investigation — pre-compute it once and pass it down. Repeated git-log inside sub-agents wastes context and produces inconsistent framings.
DO NOT skip the report. The user needs to know what changed AND what didn't.

Failure modes and recovery

PM says scope is unchanged: Phase 2 still runs (docs may still need updates), Phase 3 still runs if there are uncommitted code changes.
No code changes, just doc updates pending: skip Phase 1 (nothing for PM to update), run Phase 2 + 3.
Tests are red: do NOT proceed. Tell the user to fix the tests first. This skill assumes the working tree is in a shippable state.
Push blocked: commit is preserved; user can retry with ! git push.

SKILL.md 6.9 KB History Raw