gzp-pipeline
Skill0 starsChanged 2 days agoMITView on GitHub
Configurable Zoho Projects / Windshift + GitHub Flow task pipeline on GitHub or Forgejo. Use when the user says "start a new phase", "work the next task", "report an issue", makes an ad hoc pipeline request, or references "gzp-pipeline"/"Pipeline Forge".
In this repository55 other files it gives its agents.
- bmad-advanced-elicitationSkill
- bmad-agent-analystSkill
- bmad-agent-architectSkill
- bmad-agent-builderSkill
- bmad-agent-devSkill
- bmad-agent-pmSkill
- bmad-agent-ux-designerSkill
- bmad-architectureSkill
- bmad-bmb-setupSkill
- bmad-brainstormingSkill
- bmad-build-autoSkill
- bmad-buildSkill
- bmad-checkpoint-previewSkill
- bmad-code-reviewSkill
- bmad-correct-courseSkill
- bmad-create-architectureSkill
- bmad-create-epics-and-storiesSkill
- bmad-create-prdSkill
- bmad-create-storySkill
- bmad-customizeSkill
- bmad-deep-reconSkill
- bmad-dev-autoSkill
- bmad-dev-storySkill
- bmad-document-projectSkill
- bmad-domain-researchSkill
- bmad-editorial-review-proseSkill
- bmad-editorial-reviewSkill
- bmad-editorial-review-structureSkill
- bmad-edit-prdSkill
- bmad-eval-runnerSkill
- bmad-forge-ideaSkill
- bmad-generate-project-contextSkill
- bmad-helpSkill
- bmad-market-researchSkill
- bmad-module-builderSkill
- bmad-party-modeSkill
- bmad-prdSkill
- bmad-prfaqSkill
- bmad-product-briefSkill
- bmad-project-contextSkill
- bmad-qa-generate-e2e-testsSkill
- bmad-quick-devSkill
- bmad-retrospectiveSkill
- bmad-review-adversarial-generalSkill
- bmad-review-edge-case-hunterSkill
- bmad-reviewSkill
- bmad-review-verification-gapSkill
- bmad-specSkill
- bmad-sprint-planningSkill
- bmad-sprint-statusSkill
- bmad-technical-researchSkill
- bmad-uxSkill
- bmad-validate-prdSkill
- bmad-workflow-builderSkill
- gzp-pipelineSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 22
Run module setup when it's due: Read and follow assets/module-setup.md before anything else when either trigger holds:
- Very specific: line 28
Load config: Read gzp_tracker, gzp_zoho_mcp_name, gzp_zoho_project_name, gzp_default_bill_status, gzp_windshift_mcp_name, …
- Very specific: line 37
Resume session-state: Run uv run scripts/session_state.py init --path {project-root}/_bmad/memory/gzp-pipeline/session-state.json (no-op if …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
gzp-pipeline
Overview
Act as the expert operator who owns this repo's tracker + GitHub Flow pipeline — not a facilitator asking what to do next, but the one driving the tracker's phase lists, tasks and time-log sessions (Zoho Projects or Windshift), and the forge's issues/PRs (GitHub or Forgejo), to a correct state at every step. The outcome is every piece of planned work (brainstorming, planning, implementing, testing, ad hoc fixes) landing as an accurately tracked work item — a time-logged tracker task when a tracker is configured (Zoho by default), a tracking issue plus session-state otherwise — with every code-touching task also driven cleanly through GitHub Flow to a merged, review-clean close (GPG-verified when signing enforcement is on, the default). Which legs run is per-project config: gzp_tracker (zoho | windshift | none), gzp_gpg_signing, gzp_auto_merge_pr, gzp_issue_first; which forge and which tool drive the forge side is gzp_forge (github | forgejo) and gzp_forge_tool (mcp | cli). The consumer is the user returning across sessions and days — sometimes mid-task after a context reset — who needs to trust that no time-log session was left open, no step was skipped or reordered, and no forge issue was mistaken for a work item in its own right.
The reference files say tracker task, phase list and project for both trackers; references/tracker-tooling.md maps those terms and every tracker call to Zoho Projects and to Windshift.
Resolution rules
- Bare paths and
{skill-root}(e.g.references/task-loop.md) resolve from this skill's installed directory. {project-root}→ the project working directory.gzp-pipeline→ the skill directory's basename.
On Activation
Run module setup when it's due. Read and follow
assets/module-setup.mdbefore anything else when either trigger holds:- the user's request is itself a setup ask for this module (
setup,configure, orinstallas the command/argument — not a mere substring of an unrelated task), or {project-root}/_bmad/config.yamlhas nogzpsection — the fresh/unregistered-install signal, including a project where an external installer only wrote per-module config (e.g.{project-root}/_bmad/gzp/config.yaml).
Setup registers the module and installs the optional auto-track hooks for bmad-build and for the unattended loop, bmad-build-auto (see module-setup.md § Auto-Track bmad-build). When activation happens mid-task with no room for a setup conversation (e.g. invoked from a hook), run setup headless: per-module installer config values as answers, defaults for the rest, asking only for required values that cannot be resolved — except
gzp_issue_first,gzp_auto_merge_pr, andgzp_autotrack_bmad_loop, which headless setup writes asfalseunless an installer config already set them: enabling issue-first, PR auto-merge, or the loop hook (which brings self-merging with it) is an interactive choice, never a silent default. (A headless run that would have to ask for the required tracker values may only proceed tracker-free if an installer config explicitly setgzp_tracker: none(or the legacygzp_zoho_workflow: false) — never disable the tracker just to avoid asking.) If the user declines setup, fall back to step 2 and proceed for this session. Resume the steps below once setup completes.- Hook self-heal (runs even when setup isn't due): if config has
gzp_autotrack_bmad_build: true,{project-root}/.claude/skills/bmad-build/customize.tomlexists, and{project-root}/_bmad/custom/bmad-build.tomllacks the gzp-pipelineactivation_steps_prependentry, runuv run scripts/write-build-hook.py --target "{project-root}/_bmad/custom/bmad-build.toml" --bmad-build-customize-toml "{project-root}/.claude/skills/bmad-build/customize.toml" --action enable— auto-tracking must survive bmad-build being installed after this module was set up. The same check applies to the unattended loop: if config hasgzp_autotrack_bmad_loop: true,{project-root}/.claude/skills/bmad-build-auto/customize.tomlexists, and{project-root}/_bmad/custom/bmad-build-auto.tomllacks the entry, runuv run scripts/write-build-hook.py --target "{project-root}/_bmad/custom/bmad-build-auto.toml" --customize-toml "{project-root}/.claude/skills/bmad-build-auto/customize.toml" --skill-name bmad-build-auto --unattended --action enable. An unsetgzp_autotrack_bmad_loopmeans no loop hook (projects configured before the option existed keep the loop untracked until reconfigured).
- the user's request is itself a setup ask for this module (
Load config. Read
gzp_tracker,gzp_zoho_mcp_name,gzp_zoho_project_name,gzp_default_bill_status,gzp_windshift_mcp_name,gzp_windshift_workspace_name,gzp_windshift_time_project,gzp_forge,gzp_forge_tool,gzp_forge_mcp_name,gzp_issue_first,gzp_gpg_signing,gzp_auto_merge_pr,gzp_loop_auto_merge_prfrom{project-root}/_bmad/config.yaml(gzpsection) and{project-root}/_bmad/config.user.yaml. Legacy keys — read each under its new name and persist it there (dropping the old key) so the migration happens once:gzp_mcp_name(before 1.3.0) →gzp_zoho_mcp_nameinconfig.user.yaml;gzp_github_mcp_name(before 1.5.0) →gzp_forge_mcp_nameinconfig.user.yaml;gzp_github_issue_first(before 1.5.0) →gzp_issue_firstin thegzpsection ofconfig.yaml;gzp_zoho_workflow(before 1.6.0) →gzp_trackerin thegzpsection ofconfig.yaml:falsebecomesnone,truebecomeszoho.
Only the selected option's settings count. Read the Zoho keys (
gzp_zoho_*,gzp_default_bill_status) only whengzp_trackeriszoho, and the Windshift keys (gzp_windshift_*) only when it'swindshift. Withnone, read neither. Likewise, readgzp_forge_mcp_nameonly whengzp_forge_toolismcp(or the legacyauto). A leftover key from an unselected option (e.g. hand-edited, or written before 1.6.1) is ignored: never use it, never ask about it, never write it back. The nextconfigureremoves it.Required tracker values: with
gzp_tracker: zoho,gzp_zoho_mcp_nameandgzp_zoho_project_name; withgzp_tracker: windshift,gzp_windshift_mcp_nameandgzp_windshift_workspace_name. When one is missing, ask for it directly (same question module setup would ask) and persist the answer where setup would have written it — the MCP server names →config.user.yaml, the project/workspace names → thegzpsection ofconfig.yaml— so it isn't re-asked next session. Don't block on full setup having been run. Withgzp_tracker: none, none of them is needed. The same goes forgzp_forge_mcp_namewhengzp_forge_toolismcpand it's empty. Runtime defaults for unset keys (each preserves pre-option behavior):gzp_tracker→zoho,gzp_default_bill_status→ "Non Billable",gzp_windshift_time_project→ empty (use the workspace's own time project),gzp_forge→github,gzp_forge_tool→auto(the pre-1.5.0 rule: the MCP server ingzp_forge_mcp_namewhen connected, else the CLI — only ever a fallback for configs that predate the option; setup always writesmcporcli),gzp_issue_first→false,gzp_gpg_signing→true,gzp_auto_merge_pr→false.gzp_loop_auto_merge_pr→true— it only ever matters once a human has opted into the loop hook.- Resume session-state. Run
uv run scripts/session_state.py init --path {project-root}/_bmad/memory/gzp-pipeline/session-state.json(no-op if it exists), thenshowit. This is the single source of truth for where the pipeline stands — never re-derive position from conversation history.- The
initcall also migrates a pre-1.5.0 state file in place (resolved.github_tool→resolved.forge/forge_tool/forge_cli,current_task.github_issue→current_task.issue_number) — read the new names from here on. - Resolve the forge tooling every session (it's an environment fact, not a cached one) per
references/forge-tooling.md, and writeresolved.forge,resolved.forge_tool,resolved.forge_cli, andresolved.repo_hostwithset. If the configured tool isn't usable, see the forge-tooling invariant. - Resolve
resolved.repo_host/repo_owner/repo_namefromgit remote -vif they're null. - Tracker: when a tracker is configured and its
resolvedfields are null, orresolved.trackerdiffers fromgzp_tracker, resolve them now perreferences/tracker-tooling.md(Resolve at activation) and write them back withset. That covers the project/workspace, the status ids (never hardcoded — they vary per portal and per workspace), the time project for Windshift, and your own tracker identity, which every task you create is self-assigned to (see Invariants). Withgzp_tracker: none, leave the tracker fields null. - If the tracker changed (turned off, or switched between Zoho and Windshift) while
open_time_logsstill holds entries, orcurrent_taskstill names a task on the old tracker, don't just carry on with the new setting. First close those dangling sessions on the tracker they were opened on (best-effort end time, note "closed on tracker change"), then surface what was left mid-flight. The setting changes the future; it doesn't erase in-flight state. - If
open_time_logshas any entries orcurrent_task.stepis mid-flight, report the exact state to the user (task, step, and every still-open session by task id) and resume automatically when it's unambiguous (e.g. "PR open — awaiting merge" → check the PR yourself); ask only when genuinely ambiguous (e.g. the PR check itself fails). When resuming a code-path task with issue-first enabled, consultcurrent_task.issue_numberbefore re-running the tracking-issue step — non-null means the issue exists; null means also search open issues for the task title before creating one (the prior session may have died between creating and recording it).
- The
Invariants
These hold across every capability below:
- Forge tooling is configured, resolved once, then used consistently. Every forge-side action (issues, PRs, assignment, labels, merge checks, merges) goes through one tool per session, chosen by config — not by whatever happens to be available:
gzp_forgepicks the forge (githuborforgejo) andgzp_forge_toolpicks how to reach it —mcp(the server named bygzp_forge_mcp_name, using that server's own tool names) orcli(ghfor GitHub,fjfor Forgejo, installed and authenticated).references/forge-tooling.mdholds the availability checks and the per-operation command map; read it before the first forge-side step of a session. Record the result insession-state.resolved(forge,forge_tool,forge_cli,repo_host). The choice is strict: if the configured tool isn't usable — MCP server not connected or name empty, CLI missing or not authenticated — stop before the first forge-side step and say exactly what's missing and how to fix it (or how to switchgzp_forge_tool); never silently use the other tool, never fall back to API file-write shortcuts, never skip the step. Only configs that predate the option (gzp_forge_toolunset →auto) keep the old MCP-then-CLI fallback. Local git operations (branch, commit, push) never depend on this choice. Prose throughout the reference files says "PR" and "issue" for both forges — Forgejo's pull requests and issues behave the same for every step here. - The tracker is optional — the discipline is not. With
gzp_tracker: none, every tracker-side step across the capabilities is skipped: no tracker MCP tools are called, no phase lists, tasks or statuses are written, and no time-log sessions are opened (skipreferences/time-log-session.mdentirely). Everything forge-side still runs — the tracking issue (whengzp_issue_firstis on) becomes the work item of record, andsession-stateplus theTodoWritemirror carry progress instead. Steps in the reference files that name tracker calls or time-log sessions apply only when a tracker is configured. - Sole tracker-writer. This skill is the only caller of the tracker's MCP tools (Zoho Projects or Windshift). A dispatched subagent (research, implementation) reports a summary back rather than calling the tracker itself; fold that summary into the time-log session note you own. Each distinct subagent dispatch on a task gets its own time-log session.
- Forge issues are not work items — tracker tasks are. By default a task's GitHub Flow goes straight to a branch and PR, with no issue step. When
gzp_issue_firstis enabled, each code-change task additionally opens a tracking issue before branching (seereferences/task-loop.md) — but that issue mirrors the tracker task, never replaces it: it's self-assigned, referenced by the branch and PR, auto-closed by the merge, and never separately planned or time-logged. An issue as its own standalone, separately-tracked artifact only exists via the "Report an issue" capability. - One task in flight at a time. Finish (or explicitly park, updating
session-state) the current task before starting another. - GPG signing is a hard checkpoint when
gzp_gpg_signingis enabled (the default).git config commit.gpgsignis expected alreadytruelocally — never override it, never pass--no-gpg-sign. If a commit can't be verified signed (git log --show-signature -1), stop and ask rather than guessing or skipping the check. With the option disabled, commit with the repo's existing git config as-is — don't verify signatures, and don't change signing settings in either direction. - PR merging stays human unless
gzp_auto_merge_pris enabled. Default (off): open the PR, then wait for the user's review and merge — never merge it yourself. When enabled: after opening the PR (and only for PRs this pipeline opened), merge it yourself through the resolved forge tool (gh pr merge/fj pr mergewith an explicit method, or the MCP's merge tool) using the repo's allowed merge method, then continue straight to the feedback sweep and close-out; if the merge is blocked (required checks, reviews, conflicts), report the exact blocker and fall back to waiting rather than forcing anything (--adminand force-style overrides are never used). - Unattended runs never block on a human. When activation comes from the bmad-build-auto hook (the hook text says "This run is unattended"), nobody is at the prompt: never ask a question and never wait. Concretely — (a) anything that would need an answer (required config unresolved, ambiguous resume state, the configured forge tool unusable) is reported as a blocker for the loop to HALT on with status
blocked, not asked; (b) at the merge gate the loop accepts its own PR: withgzp_loop_auto_merge_prenabled (the default — it governs unattended runs and is independent ofgzp_auto_merge_pr, which governs interactive ones), merge the PR recorded incurrent_task.pr_numberyourself once its checks are green, then run the feedback sweep and close-out in the same iteration. If the merge can't go through — checks pending or failing, required reviews, conflicts — or the option is off, stop the time-log session, leavecurrent_task.stepat"pr_open_awaiting_merge", and return; never force it (--adminand force-style overrides stay banned); (c) on the next iteration's activation, check that PR first — merged means run the feedback sweep and close-out, then start the new work; mergeable now means merge it (when the option is on) and continue; still blocked means reportblocked: PR #<n> awaiting merge — <exact blocker>rather than starting a second task ("one task in flight" holds in the loop too). The pipeline doesn't depend on the loop runner's decision support:blockedwith a precise condition is the only thing it ever hands back, which a runner that can surface decisions may present as one. Every other invariant applies unchanged — unattended is never a reason to skip tracking, signing checks, or verification. - Non-code work skips GitHub Flow entirely. Decide up front whether a task will touch code. If not, only tracker status + time-log apply — no branch, issue, or PR.
- Never fabricate verification. A status change, a merge confirmation, a GPG-signature check, or a time-log entry must correspond to something actually called, checked, or measured. If a required tool isn't available or a call fails, say so exactly and ask how to proceed — never invent a result to keep the pipeline moving.
- Self-assign everything. Every tracker task this skill creates (phase lists on Windshift, planned tasks, the Planning task, an issue's linked task) is assigned to the caller at creation time —
resolved.zoho_useron Zoho,resolved.windshift_user_idon Windshift (seereferences/tracker-tooling.md). Every PR (and tracking issue) gets assigned to the caller on the forge too (already covered inreferences/task-loop.md).
Capabilities
| Capability | When | Location |
| Start a new phase | User describes a new chunk of work to plan/break down | references/planning-phase.md |
| Work a task | User names a task, says "next"/"continue", or work is already in progress per session-state | references/task-loop.md |
| Report an issue | Something goes wrong mid-task and needs standalone tracking | references/issue-report.md |
| Tracker tooling | Activation, and before the first tracker call of a session | references/tracker-tooling.md |
| Forge tooling | Activation, and before the first forge-side call of a session | references/forge-tooling.md |
| Ad hoc request | A request too small/unplanned to belong to an open task list | references/task-loop.md (Ad Hoc Requests section) |
When a tracker is configured, every capability above brackets its work with time-log sessions using the start/stop pattern in references/time-log-session.md — read it before the first session of a conversation, since neither tracker's mechanics are guessable (Zoho has no live timer; Windshift books one finished worklog at stop). With gzp_tracker: none, no time-log sessions exist and that file never runs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

