--- 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: 1. **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. 2. **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. 3. **Remote configured?** — `git remote -v`. If `origin` is set, the push step runs; otherwise it's skipped and reported. 4. **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//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): 1. `git status --short` to confirm only expected files changed. 2. `git diff --stat` for the commit-message subject material. 3. Stage with `git add -A` (the .gitignore is trusted to exclude secrets and build outputs). 4. 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) ` - 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. 5. Push: `git push origin ` (current branch, usually `master` or `main`). 6. 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`.