메뉴
End-of-branch workflow. Dispatches the design-doc, context-doc, and user-docs agents to update every documentation layer, then creates a changeset, squashes commits, pushes, and opens a PR. Use when finishing work on a branch before merge.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Generate cross-reference graph showing relationships between design documents. Use when visualizing doc dependencies, finding related docs, or understanding documentation structure.
Validate design doc structure and frontmatter. Use when checking design docs for compliance, ensuring proper formatting, or verifying metadata before commits.
Comprehensive quality audit for CLAUDE.md context files. Use when performing thorough quality checks, preparing for releases, ensuring context efficiency, or verifying token optimization.
Style rules for LLM context files (CLAUDE.md, AGENTS.md and their .local variants). Fires automatically when these files are opened. Enforces on-demand loading patterns, proper @-reference syntax and lean context structure.
Split large CLAUDE.md into child files. Use when context files exceed word limits, are too verbose, or cover multiple distinct topics that should be separate.
Validate CLAUDE.md structure, formatting, and quality. Use when checking context files for compliance, ensuring proper structure, or verifying before commits.
| name | finalize |
| description | End-of-branch workflow. Dispatches the design-doc, context-doc, and user-docs agents to update every documentation layer, then creates a changeset, squashes commits, pushes, and opens a PR. Use when finishing work on a branch before merge. |
| when_to_use | Trigger phrases — "finalize", "finalize this branch", "wrap up", "wrap up this branch", "ship it", "ship this branch", "close out this branch", "end-of-branch workflow", "I'm done with this work, prep it for merge", "ready to merge — run the prep", "update docs and open a PR for this branch". Do NOT trigger for: mid-task WIP commits (use a normal commit), addressing PR review comments (use /design-docs:review), or the final post-approval squash (use /design-docs:merge-prep). |
| allowed-tools | Skill, Agent, Read, Glob, Grep, Bash(git *), Bash(gh *), Bash(bun *), Bash(ls *), Write, Edit, TaskCreate, TaskUpdate |
| argument-hint | [--no-push] [--no-pr] [--no-squash] [--split-docs] [--no-context-docs] [--no-user-docs] [--dry-run] |
Orchestrates the end-of-branch workflow: analyze what changed, dispatch each documentation agent to update its domain, create a changeset, squash commits into a single clean commit, push, and open a PR.
Parse $ARGUMENTS for flags:
--no-push — skip pushing to the remote in step 8 (implies no PR, since a PR requires a pushed branch)--no-pr — push the branch in step 8 but skip PR creation (useful when the PR will be opened separately, e.g. by CI)--no-squash — skip the squash step (step 7), commit docs/changeset normally--split-docs — in step 7, squash into two commits instead of one: functional code changes (review-focus: primary) and ancillary docs/changeset changes (review-focus: ancillary), as a review-time focus signal for agent reviewers. Opt-in; default is a single commit. Ignored when --no-squash is set (nothing is squashed, so there is nothing to split).--no-context-docs — skip step 4 (Update CLAUDE.md Files / design-docs:context-doc-agent dispatch)--no-user-docs — skip step 5 (Update User Docs / design-docs:user-docs agent dispatch)--dry-run — preview what each step would do without modifying any filesIf no arguments are provided, run the full workflow.
Before starting Step 1, use TaskCreate to add one task per step below. Omit any step that the parsed flags disable so the user sees the real plan, not a list with skipped items still on it.
Default task list (no flags):
Use TaskUpdate to flip each task to in_progress when you start the step and completed when the step finishes successfully. If a step fails or is aborted, leave the task in its current state and stop — do not flip it to completed.
In --dry-run mode, still create the task list so the user sees the plan, but only the first two tasks will run.
Steps 3-6 dispatch domain agents via the Agent tool rather than invoking individual sub-skills. Each agent has its full domain skill suite wired (including the matching *-docs-style or changesets:style skill that enforces project conventions), so the work stays inside an isolated context with the right toolset and rules already in scope.
When dispatching a documentation agent (Steps 3-5), pass a prompt that includes:
When dispatching the changeset-manager (Step 6), pass a prompt that includes:
Do not enumerate which specific skills the agent should run — the agent decides based on its skill suite.
Run these checks before any work. If any check fails, stop and report.
Every gh invocation in this workflow must be prefixed with:
GH_TOKEN="${DESIGN_DOCS_GH_TOKEN:-}" GH_PAGER=cat gh …
Why: the session-start hook sets DESIGN_DOCS_GH_TOKEN from GITHUB_PERSONAL_ACCESS_TOKEN. If it's set, that token authenticates the call. If it's unset, the empty assignment scrubs any inherited GH_TOKEN in the shell so gh falls back to the keyring credentials that gh auth status reports — keeping the auth check and the writes on the same identity. GH_PAGER=cat prevents gh from blocking on a pager.
Verify you are NOT on the default branch:
!git rev-parse --abbrev-ref HEAD
If on the default branch, stop:
"You are on the default branch. Finalize is for feature branches only."
Run git status --porcelain. If there are uncommitted changes, list them and ask the user:
"There are uncommitted changes in your working tree: [list files]. These will be included in the finalize commit. Continue or abort so you can commit/stash first?"
Wait for the user's response. If they say abort, stop the workflow.
Detect the default branch:
!GH_TOKEN="${DESIGN_DOCS_GH_TOKEN:-}" GH_PAGER=cat gh repo view --json defaultBranchRef -q '.defaultBranchRef.name' 2>/dev/null || git rev-parse --verify main 2>/dev/null && echo main || echo master
Store the result as BASE_BRANCH for use in subsequent steps.
Run git log $BASE_BRANCH..HEAD --oneline. The branch is empty only when there are no commits ahead of the base branch AND the working tree is clean — an all-uncommitted branch still has work to finalize (the dirty-tree check above already staged it for the finalize commit). So:
Commits ahead, or a dirty working tree (per the dirty-tree check above): there is work — proceed.
Zero commits ahead AND git status --porcelain is empty: report and stop:
"No changes detected on this branch compared to $BASE_BRANCH (no commits ahead, clean working tree). Nothing to finalize."
When the only changes are uncommitted, Step 7's soft reset to the merge base is a no-op and the staged working tree becomes the finalize commit(s) directly.
Check if the session/start tag exists:
git rev-parse session/start 2>/dev/null
If it does not exist, create it at the merge-base:
git tag session/start $(git merge-base HEAD $BASE_BRANCH)
Report: "Created session/start tag at merge-base."
Run the auth check using the same env hygiene as every other gh call in this workflow — the check site and the use sites in step 8 must agree on which credential is in play, otherwise the probe passes while the write later fails or posts to the wrong account:
GH_TOKEN="${DESIGN_DOCS_GH_TOKEN:-}" GH_PAGER=cat gh auth status
If not authenticated, warn the user:
"GitHub CLI is not authenticated. PR creation and the existing-PR check will fail without it. Run
gh auth loginto fix this, continue with--no-pr(push the branch but skip PR creation —git pushuses git's own credentials, not gh), or continue with--no-pushto skip the remote entirely."
If the user wants to continue with --no-pr, treat the rest of the workflow as if --no-pr were set. Same for --no-push.
Build a summary of what changed on this branch:
git diff $BASE_BRANCH...HEAD --stat
git log $BASE_BRANCH..HEAD --oneline
Present a brief summary to the user:
"This branch has N commits ahead of $BASE_BRANCH, touching N files. Key changes: [summarize from the diff stat]"
This summary is passed as the context payload to every agent dispatch in Steps 3-5.
In --dry-run mode: Show the summary and describe what each subsequent step would do, then stop.
Dispatch the design-docs:design-doc-agent via the Agent tool. Pass a prompt containing the Step 2 branch summary and the list of changed files. Tell the agent to review design docs in .claude/design/ against the branch changes and update or create design docs where the architecture, data flows, design decisions, or implementation-plan outcomes have changed. The agent has its full design skill suite wired — let it decide which skills apply.
When the agent returns, capture its report (which files it modified, or "no changes needed") for the Step 4 dispatch context.
No-op handling: If the agent reports no design doc updates are needed, that is success. Report "No design doc updates needed" and proceed to step 4.
On failure: Report what the agent reported and stop. Tell the user which files the agent modified so they can review or revert.
Skip if --no-context-docs flag is set. Proceed to step 5.
Dispatch the design-docs:context-doc-agent via the Agent tool. Pass a prompt containing the Step 2 branch summary plus whatever the design-docs:design-doc-agent reported in Step 3 — the context agent needs to know which design docs were touched so it can update @ pointers, references, and CLAUDE.md sections that index those docs. The agent also re-records pointer content hashes in .claude/design/refs.json, so any design doc edited in Step 3 leaves its pointers drift-clean.
When the agent returns, capture its report for the Step 5 dispatch context.
No-op handling: Same as step 3.
On failure: Report and stop.
Skip if --no-user-docs flag is set. Proceed to step 6.
Dispatch the design-docs:user-docs agent via the Agent tool. Pass a prompt containing the Step 2 branch summary plus the Step 3 design doc updates and the Step 4 CLAUDE.md updates — the user-docs agent needs the full picture to decide whether READMEs, contributing docs, security docs, or other user-facing pages should be touched.
No-op handling: Same as step 3.
On failure: Report and stop.
Dispatch the changesets:changeset-manager agent via the Agent tool. Pass a prompt following the Agent Dispatch Convention for Step 6 — the branch change summary, a concise description of what changed in shipped surface, the Step 3-5 reports, and a bump-type recommendation. The agent has the full changesets skill suite wired (changesets:create, changesets:update, changesets:delete, changesets:merge, changesets:style, changesets:status, changesets:dependencies, changesets:config) and decides whether to create a new changeset, update an existing one, or report that the diff has no changelog-worthy items.
If the Agent call fails because the changesets:changeset-manager agent type is unknown (the changesets plugin is not installed), fall back to creating the changeset manually:
package.json (or the plugin's package.json).changeset/ in the standard format:---
"package-name": patch
---
User's description here
Generate a random changeset filename (lowercase adjective-noun pattern).
On failure: Report and stop.
Skip if --no-squash flag is set. Proceed directly to step 8 with a normal commit of just the docs/changeset changes. (When --no-squash is set, --split-docs has no effect — there is no squash to split.)
This project squash-merges into the default branch and uses agent reviewers. Squash cleanly into a single commit (or two, with --split-docs below) — do not editorialize for keeping granular history. The arguments for preserving per-commit history do not apply to this pipeline:
base...head "Files changed" view.--no-squash is the escape hatch for the rare case where granular commits genuinely need to survive. Keep the confirmation gate below regardless.
Stage everything including doc updates and changeset from previous steps:
git add -A
Show the user what will be squashed:
git log $(git merge-base HEAD $BASE_BRANCH)..HEAD --oneline
"Squashing N commits into {one commit | two commits: functional + ancillary}. [list commits]. Continue? (yes/no)"
Wait for confirmation. If the user says no, stop.
git reset --soft $(git merge-base HEAD $BASE_BRANCH)
All branch changes are now staged at the merge base. Commit them per the mode below.
Generate one conventional commit message from:
Present the generated message to the user for review/editing.
Format:
type(scope): subject
[Description from changeset and branch changes]
Signed-off-by: [from git config]
git commit -m "<generated message>"
--split-docs: two commits)When --split-docs is set, produce two commits so agent reviewers can focus on the functional surface and treat doc churn as ancillary. Both are collapsed into one at squash-merge — this is purely a review-time signal. Recognizing the review-focus: trailer is the reviewer's job and is out of scope here; finalize only emits it.
Classify the staged paths. Read path roots from .claude/design/design.config.json (paths.designDocs, paths.plans, paths.context, paths.localContext, userDocs.readme, userDocs.repoDocs). A file is ancillary if it matches any of those, any package-level CLAUDE.md / CLAUDE.local.md, any README.md, or lives under .changeset/. Everything else is functional.
git diff --cached --name-only
Commit the functional changes first (git reset HEAD <ancillary-paths> to unstage ancillary, then commit what remains). Use the conventional message from the default mode, with a review-focus: primary trailer:
type(scope): subject
[Description of the functional changes]
review-focus: primary
Signed-off-by: [from git config]
Commit the ancillary changes second (git add <ancillary-paths>) with a docs-type message and a review-focus: ancillary trailer:
docs(scope): update design docs, context, and changeset
review-focus: ancillary
Signed-off-by: [from git config]
One bucket empty: if the branch has no functional changes (docs-only) or no ancillary changes, produce a single commit for the non-empty bucket with its matching review-focus: trailer. Never create an empty commit.
The review-focus: value is always the canonical lowercase form (primary / ancillary). Place it in the commit footer alongside Signed-off-by.
Move the session tag to the new squashed commit (the last commit created above):
git tag -f session/start HEAD
On failure: Report the git error. The user can recover with git reflog to find the pre-squash state.
Skip entirely if --no-push flag is set. Report: "Changes committed locally on $BRANCH. Not pushed (--no-push). Run git push -u origin HEAD to push manually."
GH_TOKEN="${DESIGN_DOCS_GH_TOKEN:-}" GH_PAGER=cat gh pr view --json number,url 2>/dev/null
If a PR already exists, report:
"A PR already exists for this branch: [url]. Pushing latest changes."
Push and stop (don't create a duplicate PR).
git push -u origin HEAD
Stop here if --no-pr flag is set. Report: "Pushed to origin/$BRANCH. No PR opened (--no-pr). Open one manually via gh pr create or your CI workflow."
Generate a PR title from the changeset content or branch name. Generate the body from the branch diff summary and changeset description.
GH_TOKEN="${DESIGN_DOCS_GH_TOKEN:-}" GH_PAGER=cat gh pr create --title "[title]" --body "[body]"
Report the PR URL to the user.
Between each step, mark the matching task completed via TaskUpdate and report a brief status update:
--split-docs: "Squashed 8 commits into 2 (functional + ancillary)"If any step fails:
TaskUpdate)git diff, revert with git checkout -- ., or fix the issue and re-run /design-docs:finalize"git reflog to find the pre-squash stateSteps 3-5 are idempotent — re-running against already-updated docs produces no changes. Steps 6-8 are not idempotent — the skill should detect existing changesets and PRs before creating duplicates.