agentleFS
snovak7snovak7/bmad-github-zoho-pipeline/.claude/skills/gzp-pipeline/SKILL.md

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".

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
  1. Very specific:

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

    line 22
  2. Very specific:

    Load config: Read gzp_tracker, gzp_zoho_mcp_name, gzp_zoho_project_name, gzp_default_bill_status, gzp_windshift_mcp_name, …

    line 28
  3. Very specific:

    Resume session-state: Run uv run scripts/session_state.py init --path {project-root}/_bmad/memory/gzp-pipeline/session-state.json (no-op if …

    line 37

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  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_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 tracker values may only proceed tracker-free if an installer config explicitly set gzp_tracker: none (or the legacy gzp_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.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_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_pr from {project-root}/_bmad/config.yaml (gzp section) 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_name in config.user.yaml;
    • gzp_github_mcp_name (before 1.5.0) → gzp_forge_mcp_name in config.user.yaml;
    • gzp_github_issue_first (before 1.5.0) → gzp_issue_first in the gzp section of config.yaml;
    • gzp_zoho_workflow (before 1.6.0) → gzp_tracker in the gzp section of config.yaml: false becomes none, true becomes zoho.

    Only the selected option's settings count. Read the Zoho keys (gzp_zoho_*, gzp_default_bill_status) only when gzp_tracker is zoho, and the Windshift keys (gzp_windshift_*) only when it's windshift. With none, read neither. Likewise, read gzp_forge_mcp_name only when gzp_forge_tool is mcp (or the legacy auto). 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 next configure removes it.

    Required tracker values: with gzp_tracker: zoho, gzp_zoho_mcp_name and gzp_zoho_project_name; with gzp_tracker: windshift, gzp_windshift_mcp_name and gzp_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 → the gzp section of config.yaml — so it isn't re-asked next session. Don't block on full setup having been run. With gzp_tracker: none, none of them is needed. The same goes for gzp_forge_mcp_name when gzp_forge_tool is mcp and 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 in gzp_forge_mcp_name when connected, else the CLI — only ever a fallback for configs that predate the option; setup always writes mcp or cli), 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.

  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.
    • The init call 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 write resolved.forge, resolved.forge_tool, resolved.forge_cli, and resolved.repo_host with set. If the configured tool isn't usable, see the forge-tooling invariant.
    • Resolve resolved.repo_host/repo_owner/repo_name from git remote -v if they're null.
    • Tracker: when a tracker is configured and its resolved fields are null, or resolved.tracker differs from gzp_tracker, resolve them now per references/tracker-tooling.md (Resolve at activation) and write them back with set. 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). With gzp_tracker: none, leave the tracker fields null.
    • If the tracker changed (turned off, or switched between Zoho and Windshift) while open_time_logs still holds entries, or current_task still 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_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.issue_number 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:

  • 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_forge picks the forge (github or forgejo) and gzp_forge_tool picks how to reach it — mcp (the server named by gzp_forge_mcp_name, using that server's own tool names) or cli (gh for GitHub, fj for Forgejo, installed and authenticated). references/forge-tooling.md holds the availability checks and the per-operation command map; read it before the first forge-side step of a session. Record the result in session-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 switch gzp_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_tool unset → 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 (skip references/time-log-session.md entirely). Everything forge-side still runs — the tracking issue (when gzp_issue_first is on) becomes the work item of record, and session-state plus the TodoWrite mirror 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_first is enabled, each code-change task additionally opens a tracking issue before branching (see references/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_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 forge tool (gh pr merge / fj pr merge with 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 (--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, 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: 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 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_user on Zoho, resolved.windshift_user_id on Windshift (see references/tracker-tooling.md). Every PR (and tracking issue) gets assigned to the caller on the forge too (already covered in references/task-loop.md).

Capabilities

CapabilityWhenLocation
Start a new phaseUser describes a new chunk of work to plan/break downreferences/planning-phase.md
Work a taskUser names a task, says "next"/"continue", or work is already in progress per session-statereferences/task-loop.md
Report an issueSomething goes wrong mid-task and needs standalone trackingreferences/issue-report.md
Tracker toolingActivation, and before the first tracker call of a sessionreferences/tracker-tooling.md
Forge toolingActivation, and before the first forge-side call of a sessionreferences/forge-tooling.md
Ad hoc requestA request too small/unplanned to belong to an open task listreferences/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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.