gzp-pipeline

Overview

Act as the expert operator who owns this repo's Zoho Projects + GitHub Flow pipeline — not a facilitator asking what to do next, but the one driving Zoho task lists, GitHub issues/PRs, and time-log sessions 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 Zoho task when the Zoho workflow is enabled (the 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_zoho_workflow, gzp_gpg_signing, gzp_auto_merge_pr, gzp_github_issue_first. 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 GitHub issue was mistaken for a work item in its own right.

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

1. Run module setup when it's due. Read and follow assets/module-setup.md before anything else when either trigger holds:

   • the user's request is itself a setup ask for this module (setup, configure, or install as the command/argument — not a mere substring of an unrelated task), or
   • {project-root}/_bmad/config.yaml has no gzp section — 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_github_issue_first, gzp_auto_merge_pr, and gzp_autotrack_bmad_loop, which headless setup writes as false unless 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 Zoho values may only proceed Zoho-free if an installer config explicitly set gzp_zoho_workflow: false — never disable the Zoho workflow 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.toml exists, and {project-root}/_bmad/custom/bmad-build.toml lacks the gzp-pipeline activation_steps_prepend entry, run uv 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 has gzp_autotrack_bmad_loop: true, {project-root}/.claude/skills/bmad-build-auto/customize.toml exists, and {project-root}/_bmad/custom/bmad-build-auto.toml lacks the entry, run uv 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 unset gzp_autotrack_bmad_loop means no loop hook (projects configured before the option existed keep the loop untracked until reconfigured).
2. Load config. Read gzp_zoho_mcp_name, gzp_zoho_project_name, gzp_default_bill_status, gzp_github_mcp_name, gzp_github_issue_first, gzp_zoho_workflow, gzp_gpg_signing, gzp_auto_merge_pr, gzp_loop_auto_merge_pr from {project-root}/_bmad/config.yaml (gzp section) and {project-root}/_bmad/config.user.yaml. Legacy key: a config written before 1.3.0 holds the Zoho server under gzp_mcp_name — read it as gzp_zoho_mcp_name and persist it under the new name in config.user.yaml (drop the old key) so the migration happens once. When gzp_zoho_workflow is enabled and either of the first two is missing, ask for it directly (same question module setup would ask) and persist the answer where setup would have written it (gzp_zoho_mcp_name → config.user.yaml; gzp_zoho_project_name → the gzp section of config.yaml) so it isn't re-asked next session — don't block on full setup having been run; with the Zoho workflow off, neither is needed. Runtime defaults for unset keys (each preserves pre-option behavior): gzp_default_bill_status → "Non Billable", gzp_github_issue_first → false, gzp_zoho_workflow → true, 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.
3. 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), then show it. This is the single source of truth for where the pipeline stands — never re-derive position from conversation history.
   • Resolve resolved.github_tool every session (it's an environment fact, not a cached one): "mcp" when gzp_github_mcp_name names a server that is connected in this session, else "gh" if the CLI is installed and gh auth status succeeds — see the GitHub-tooling invariant for the neither case.
   • If resolved.* fields are null and gzp_zoho_workflow is enabled, resolve them now and write them back with set (with the Zoho workflow off, leave the Zoho fields null and resolve only repo_owner/repo_name from git remote -v): call get_portals (single portal → use it, else ask), get_projects_list matched against gzp_zoho_project_name, the task-status field's option ids via get_options_list_for_a_field_in_module (never hardcode status ids — they vary per portal), owner/repo from git remote -v, and the caller's own Zoho identity (zuid/zpuid/name) via get_current_user_details — needed to self-assign every Zoho task created (see Invariants).
   • If gzp_zoho_workflow was turned off while open_time_logs still holds entries (or current_task still names a Zoho task), don't just proceed Zoho-free: close those dangling sessions first (best-effort end time, note "closed on Zoho-workflow disable") and surface what was left mid-flight — the toggle changes the future, it doesn't erase in-flight Zoho state.
   • If open_time_logs has any entries or current_task.step is 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, consult current_task.github_issue before 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).

Invariants

These hold across every capability below:

• GitHub tooling is resolved once, then used consistently. Every GitHub-side action (issues, PRs, assignment, labels, merge checks, merges) goes through one resolved tool per session: the MCP server named by gzp_github_mcp_name when it's connected (its create_pull_request, pull_request_read, merge_pull_request, get_me, issue tools, etc. — the MCP tool names used in the reference files are that server's); otherwise the gh CLI when it's installed and gh auth status succeeds. MCP comes first because it's the client's own authenticated connection — no separate CLI install or login to drift. Record the choice in session-state.resolved.github_tool ("mcp" or "gh") during activation. If neither works — gzp_github_mcp_name empty or its server not connected, and no working gh — stop before the first GitHub-side step and say exactly which one is missing; never fall back to GitHub API file-write shortcuts or skip the step silently. Local git operations (branch, commit, push) never depend on this choice.
• The Zoho workflow is optional — the discipline is not. When gzp_zoho_workflow is disabled, every Zoho-side step across the capabilities is skipped: no Zoho MCP tools are called, no task lists/tasks/statuses are written, and no time-log sessions are opened (skip references/time-log-session.md entirely). Everything GitHub-side still runs — the tracking issue (when gzp_github_issue_first is on) becomes the work item of record, and session-state plus the TodoWrite mirror carry progress instead of Zoho. Steps in the reference files that name Zoho calls or time-log sessions apply only when the Zoho workflow is enabled.
• Sole Zoho-writer. This skill is the only caller of Zoho Projects MCP tools. A dispatched subagent (research, implementation) reports a summary back rather than calling Zoho 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 pair.
• GitHub issues are not work items — Zoho tasks are. By default a task's GitHub Flow goes straight to a branch and PR, with no issue step. When gzp_github_issue_first is enabled, each code-change task additionally opens a tracking issue before branching (see references/task-loop.md) — but that issue mirrors the Zoho 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_signing is enabled (the default). git config commit.gpgsign is expected already true locally — 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_pr is 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 GitHub tool (gh pr merge with an explicit method, or the MCP's merge_pull_request) 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 (--admin and 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, no working GitHub tool) 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: with gzp_loop_auto_merge_pr enabled (the default — it governs unattended runs and is independent of gzp_auto_merge_pr, which governs interactive ones), merge the PR recorded in current_task.pr_number yourself 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, leave current_task.step at "pr_open_awaiting_merge", and return; never force it (--admin and 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 report blocked: 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: blocked with 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 Zoho 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 Zoho task this skill creates (planned tasks, the Planning task, an issue's linked task) gets owners_and_work.owners set to the caller (resolved.zoho_user) at creation time. Every GitHub PR gets assigned to the caller too (already covered in references/task-loop.md).

Capabilities

When the Zoho workflow is enabled, every capability above brackets its work with time-log sessions using the paired start/stop pattern in references/time-log-session.md — read it before the first add_time_log call of a session, since Zoho has no live timer and the mechanics aren't guessable. With gzp_zoho_workflow off, no time-log sessions exist and that file never runs.