File	Read at	Holds
`../../assets/writing.md`	before writing any commit body or PR text	the writing rules for every text a person reads
`references/commits.md`	phase 2	staging, subject and body rules, trailers
`references/pr-description.md`	phase 5	the glance block, the structure, visualization, justification
`references/screenshots.md`	phase 5, when the branch changes anything rendered	mandatory screenshots, hosting images from the CLI
`references/rationalizations.md`	when tempted to skip a phase	why each shortcut fails

Consent

Invoking /submit is consent for the full workflow: commit, push, create or edit a draft PR, and push CI-fix commits. A narrower request such as "just commit" or "just push" is consent for exactly that. Confirm before stepping past it. Three actions always need fresh, explicit consent: pushing to the default branch, force-pushing, and marking a draft PR ready for review.

Workflow

Each phase meets its exit condition before the next one starts. A re-invocation re-enters at phase 0 and skips the phases already satisfied, never 5b or 6 while a PR exists.

Orient. Run touch "$(git rev-parse --git-dir)/swd-submit". The plugin's guard refuses gh pr create without this fresh marker. Then gather the facts: git status, the current branch, git log @{u}..HEAD, and gh pr view --json number,title,body,state,isDraft,baseRefName. State what you found in a sentence or two. A merged or closed PR means new work starts from a fresh branch off the updated default branch.
Branch. Never commit to the default branch. Follow the repo's branch naming when one is documented or visible. Otherwise use <author>-<slug>: the git user's first name in lowercase, and a slug from the change.
Commit, if phase 0 found uncommitted changes. Read references/commits.md and ../../assets/writing.md now. Stage by filename, and give each unrelated change its own commit. Lint each message with <plugin root>/scripts/prose-lint.py --commit before you commit.
Pre-push checks. Format, lint, and test every area the branch touches, with the repo's own commands from its agent docs, task runner, or package scripts. Fix failures at the root before pushing.
Push. The first push is git push -u origin <branch>, then plain git push. Exit: local HEAD matches origin/<branch>.
PR. Read references/pr-description.md and ../../assets/writing.md now.
- 5a, no PR exists. Draft the title and the body. When the branch changes anything rendered, read references/screenshots.md: screenshots are mandatory, or the body declares the gap. Lint the body with prose-lint.py and fix every finding. Create the PR with gh pr create --draft.
- 5b, a PR exists. Mandatory even when the user only said "push", and even with nothing new pushed. Fetch the live title and body and git log <base>..HEAD. Check that the title still covers all the work. Check that every claim in the body is still true. That covers the scope, statements such as "no new dependencies", the glance-block numbers and side effects, and the screenshots. Stale: edit with gh pr edit and say what changed. Not stale: state "title and body still match the branch".
CI. Run gh pr checks and wait out pending checks. Never declare success with checks in flight. On failure, read the failing logs, find the root cause, fix it, and re-enter at phase 3. Never disable a check or skip a test. Flag a failure that is clearly flaky or on the infra side to the user instead of retrying it. Close with the status: "all N required checks green", or what failed and which commit fixed it. Then run rm -f "$(git rev-parse --git-dir)/swd-submit".

Definition of done

Related skills

/blueprint plans the change. /examine reviews the PR once it exists. /rebase moves it when the base branch moved underneath it.

submit

Submit: from working tree to reviewable PR

Required references