git-workflow
Sets up and changes this team's git workflow rules in .paqad/configs/git-workflow/ (ticket sources and key patterns, branch types and naming, base branches, commit message format, PR title, body, labels and reviewers, ticket status moves, and how strictly agents and people are held to them) through scripts that read git and gh, propose with evidence, validate and write, and it records every answer as a decision. Use when create documentation reaches its git workflow step, when a new project needs its starter rules, and whenever someone asks to change how branches, commits, PRs or tickets work, even if they don't mention the config. It is the only way these files change.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- git-workflow
- metadata
- { "cacheable": "false", "max_lines": "300", "model_tier": "medium", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
- description
- Sets up and changes this team's git workflow rules in .paqad/configs/git-workflow/ (ticket sources and key patterns, branch types and naming, base branches, commit message format, PR title, body, labels and reviewers, ticket status moves, and how strictly agents and people are held to them) through scripts that read git and gh, propose with evidence, validate and write, and it records every answer as a decision. Use when create documentation reaches its git workflow step, when a new project needs its starter rules, and whenever someone asks to change how branches, commits, PRs or tickets work, even if they don't mention the config. It is the only way these files change.
02 资源文件 13
- 参考文档agents/openai.yaml249 B
- 资产文件assets/answers.template.json69 B
- 资产文件assets/change.template.json114 B
- 资产文件assets/final-message.txt197 B
- 参考文档references/questions.md2.5 KB
- 参考文档references/settings.md14.2 KB
- 参考文档references/signals.md3.5 KB
- 参考文档references/summaries.md1.2 KB
- 脚本scripts/apply.mjs2.1 KB
- 脚本scripts/change.mjs1.9 KB
- 脚本scripts/check.mjs1.8 KB
- 脚本scripts/propose.mjs1.6 KB
- 参考文档skill.meta.yaml380 B
03 SKILL.md 正文
Rules
- Change .paqad/configs/git-workflow/ only through this skill's scripts. Never edit those files with Edit, Write or a shell command: paqad blocks direct edits, and a change that skips the scripts is never checked or recorded.
- Base every proposal on what the scripts found. When history is mixed, ask the team; don't pick for them. When something can't be read, say it's unknown, never that it doesn't exist.
- Record every answer as a decision, so the team can see later why each rule exists.
What It Does
One skill is in charge of .paqad/configs/git-workflow/, the six files that hold this
team's rules for tickets, branches, commits, pull requests and how strictly they're
checked (tickets.yaml, branches.yaml, commits.yaml, pull-requests.yaml,
enforcement.yaml, design-sign-off.yaml). It handles three cases:
- first setup from the repo's history, during
create documentation - a new project with no history
- any later change the team asks for
The scripts read git and gh, propose with evidence, validate and write. Your job is
only to ask the team and explain.
Use This When
create documentationreaches its git workflow step (first setup).- The repo has no remote, fewer than 20 main-line commits, or no branches besides the
base (the scripts report
mode: new-project). - Someone asks to change how branches are named, where changes start, how commits or PR titles are written, which labels or reviewers a PR gets, which tickets a change links, how ticket statuses move, or how strictly any of that is checked. This applies whatever workflow the request routed to, and even when the request doesn't mention the config.
Inputs
project_root(path, optional): defaults to cwd.flow(string, optional):first-setup,new-projectorchange. Picked from the request when not given.
Procedure
Every script prints JSON on stdout, never prompts, and exits 0 on success, 1 on invalid
input or config, and 2 when git or gh failed.
First setup
- [ ] 1. Run
scripts/check.mjs. If it reports errors orchanged_outside, show them and stop until the team says how to handle them. - [ ] 2. Run
scripts/propose.mjs. Ifmodeisnew-project, switch to the new-project procedure. - [ ] 3. Show the team a short summary: one line for each evidence item that decided a value, plus every
unknownline. - [ ] 4. Ask every
choicein one round with your host's question tool. Use up to 4 questions per call, back to back. Put the recommended option first, and put the evidence counts and examples in each option's preview. - [ ] 5. For each answered choice, record a decision:
paqad-ai decision create --category workflow-or-tool --title "<question>" --context "<evidence lines>" --option <id>=<label> ... --recommendation <recommended>- then
paqad-ai decision resolve <id> <chosen> "<the team's reason>"
- [ ] 6. Write the answers to a temporary
answers.jsonoutside the repo, starting fromassets/answers.template.json. Runscripts/apply.mjs <answers.json> --overwrite --dry-runand show the diff. Then run it again without--dry-run. - [ ] 7. Report using
assets/final-message.txt: the files written, each choice and its answer, anythingnot confirmed, and theunknownlines. The files and the resolved decisions ship with the documentation change.
New project
The same steps 1 to 7. propose returns the starter questions from
references/questions.md as its choices, and the package defaults as its files. Never
propose a long-lived develop branch for a new project.
Change
- [ ] 1. Run
scripts/check.mjs. The same rule as step 1 above applies. - [ ] 2. Turn the request into
change.jsonedits, starting fromassets/change.template.json. Use only settings listed inreferences/settings.md. If the request is unclear, ask one question first. - [ ] 3. Run
scripts/change.mjs --plan <change.json>. Explain the diff in plain words, for example: "Hotfix branches will start from main and use ServiceNow tickets." - [ ] 4. Ask the team to confirm with your host's question tool. Record the answer as a decision, as in step 5 above.
- [ ] 5. Run
scripts/change.mjs --apply <change.json>. - [ ] 6. Ship it like any change, so the team reviews it as a PR:
paqad-ai deliveron its own branch, with the resolved decision committed. Use the branch typechoreif the team has one; otherwise itsdefault_type.
In change.json, value: null removes a branch type or a ticket source. It is an error
for any other key, because settings are never removed.
Output Contract
- The six files under
.paqad/configs/git-workflow/, valid, written only by the scripts, and stamped in.paqad/configs/git-workflow/.last-applied.json. - One resolved decision per answered choice.
- A final message in the shape of
assets/final-message.txt.
Escalate / Stop Conditions
- the result is invalid
- the team declines
- a script exits 2 (git or
ghfailed): report the error and stop, don't guess
Gotchas
- The scripts are thin wrappers around
paqad-ai git-workflow. Whenpaqad-aiisn't on the PATH they trynpx --no-install paqad-ai, and they exit 2 if neither starts. Report that; don't fall back to editing the files. checkreports a file someone edited by hand inchanged_outside. Never accept it with--accepton your own; ask the team first, because accepting makes that edit the new baseline.apply.mjsrefuses to replace existing files without--overwrite. Always look at the--dry-rundiff first.- A
nullvalue inchange.jsononly removes a branch type or a ticket source. Any other key can't be removed, so change it to the value the team wants instead.
Resources
scripts/check.mjs:paqad-ai git-workflow check [--accept]scripts/propose.mjs:paqad-ai git-workflow setupscripts/apply.mjs:paqad-ai git-workflow setup --apply <answers.json> [--overwrite] [--dry-run]scripts/change.mjs:paqad-ai git-workflow change --plan|--apply <change.json>references/settings.md: every setting, with its file, key, type, default and meaningreferences/signals.md: what each history signal means, and the thresholdsreferences/questions.md: the starter questions for a new projectreferences/summaries.md: how to write a plain-language summaryassets/answers.template.json,assets/change.template.json,assets/final-message.txt
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.