software-development-lifecycle

The full skill.

Original instructions from the publisher’s SKILL.md

# Binwak Software-Development-Lifecycle Strategy Skill

Strategy: dispatch a single `binwak/engineer` worker; on success, fan out to parallel `binwak/reviewer` (MODE: code) + `binwak/designer` reviewers; if both verdicts come back clean (APPROVE with at most minor findings), sync-poll `gh pr checks` as a CI quality gate — all green → finish succeeded; any red → next engineer iteration with CI context; pending → dispatch a `ci-waiter` (reviewer in MODE: ci) that blocks until CI terminal. Else (any reviewer blocker / major) dispatch the next `binwak/engineer` iteration with prior verdicts available, and loop. Loaded by the `binwak/coordinator` agent alongside the generic `official/workflow-coordination` skill at every coord wake-up.

---

## Case bank

Match own direct parents against these cases — exactly one matches per wake-up (the case bank is total over expected shapes; see "Failure-mode coverage"). Unexpected shapes (3 parents, an unknown agent FQN, etc.) are bugs in workflow construction; terminate with `workflow finish --outcome failed --message "coord saw unexpected DAG shape under binwak/software-development-lifecycle: <describe>"`.

```
CASE "no parents" (initial coord node):
  addSubgraph:
    dev (worker, agent=binwak/engineer, brief=<template-dev-iter-1>)
       parents = [self]
    next-coord (coordinator, agent=binwak/coordinator)
       parents = [dev]
  exit

CASE "one parent, worker, agent=binwak/engineer, status=succeeded":
  addSubgraph:
    review   (worker, agent=binwak/reviewer, brief=<template-review>)
       parents = [self]
    designer (worker, agent=binwak/designer, brief=<template-designer>)
       parents = [self]
    next-coord (coordinator, agent=binwak/coordinator)
       parents = [review, designer]
  exit

CASE "one parent, worker, agent=binwak/engineer, status in (failed, cancelled)":
  finishWorkflow(failed, "dev iteration ended in {status}")
  exit

CASE "two parents, both worker, agents in {binwak/reviewer, binwak/designer}":
  for each parent:
    resolve run:   TID = glyph task list --origin workflow --origin-id <parent node id> --json | jq -r '.[0].id'
    fetch task:    glyph task show <TID> --json
    fetch verdict: read <workdir>/artifact/verdict.json (parse per §C of generic skill)
  blockers_and_majors = [
    f for v in verdicts for f in v.findings if f.severity in ('blocker', 'major')
  ]
  if blockers_and_majors is not empty:
    addSubgraph:
      dev (worker, agent=binwak/engineer, brief=<template-dev-iter-2-plus>)
         parents = [self]
      next-coord (coordinator)
         parents = [dev]
    exit

  # Both reviewers APPROVE — run CI quality gate before declaring success.
  prior_dev = most recent (highest-phase) agent=binwak/engineer worker node in the DAG
  prior_dev_task = glyph task list --origin workflow --origin-id <prior_dev node id> --json | jq -r '.[0].id'
  pr_number = derive from glyph task show <prior_dev_task> --json
              (the engineer's success.output and/or activity log carry the
              `gh pr create` URL; parse the PR number from the URL —
              no new engineer contract required)
  ci = `gh pr checks <pr_number> --json name,state,bucket,link`
       # `bucket` is gh's normalised category for each check, one of
       # `pass | fail | pending | skipping | cancel`. `link` is the
       # per-check URL (GitHub Actions form:
       # https://github.com/<owner>/<repo>/actions/runs/<runId>/job/<jobId>).
  if every check.bucket in ("pass", "skipping"):
       # `skipping` is terminal-OK (the job was deliberately skipped, e.g.
       #  conditional `if:` evaluated false); treat as pass for gating.
    addSubgraph:
      approval (human, spec={
        prompt: "<assembled from workflow brief + iteration count + reviewer summary + PR link>",
        choices: [
          { id: "approve", label: "Approve & merge" },
          { id: "changes", label: "Request more changes" },
          { id: "cancel", label: "Cancel workflow" }
        ]
      })
         parents = [self]
      next-coord (coordinator)
         parents = [approval]
    exit
  elif any check.bucket in ("fail", "cancel"):
    addSubgraph:
      dev (worker, agent=binwak/engineer, brief=<template-dev-iter-2-plus>)
         parents = [self]
      next-coord (coordinator)
         parents = [dev]
    # The dev brief instructs the worker to fetch `gh pr checks --json`
    # itself so the failing-job context flows in without coord pre-digestion.
    exit
  else:  # at least one check.bucket == "pending" — dispatch a ci-waiter
    addSubgraph:
      ci-waiter (worker, agent=binwak/reviewer, brief=<template-review-ci>)
         parents = [self]
      next-coord (coordinator)
         parents = [ci-waiter]
    exit

CASE "one parent, worker, agent=binwak/reviewer, status=succeeded" (the ci-waiter terminal):
  # Topologically distinguished from the normal reviewer-in-pair case
  # by single-parent shape: the review + designer pair always lands as
  # two parents on the next coord. A lone reviewer parent is therefore
  # always a ci-waiter dispatched via template-review-ci.
  fetch verdict: read <workdir>/artifact/verdict.json (parse per §C of generic skill)
  if verdict == "APPROVE" and (findings == [] or all minor):
    addSubgraph:
      approval (human, spec={
        prompt: "<assembled from workflow brief + iteration count + reviewer summary + PR link + CI waited>",
        choices: [
          { id: "approve", label: "Approve & merge" },
          { id: "changes", label: "Request more changes" },
          { id: "cancel", label: "Cancel workflow" }
        ]
      })
         parents = [self]
      next-coord (coordinator)
         parents = [approval]
    exit
  else:  # REQUEST_CHANGES — CI ended red
    addSubgraph:
      dev (worker, agent=binwak/engineer, brief=<template-dev-iter-2-plus>)
         parents = [self]
      next-coord (coordinator)
         parents = [dev]
    exit

CASE "one parent, worker, agent=binwak/reviewer, status in (failed, cancelled)" (ci-waiter failed):
  finishWorkflow(failed, "ci-waiter iteration ended in {status}; coord cannot decide CI state without verdict")
  exit

CASE "two parents, both worker, any status in (failed, cancelled)":
  finishWorkflow(failed, "reviewer iteration ended in {status}; coord cannot decide without verdict")
  exit

CASE "one parent, human, status=succeeded":
  read metadata.response from parent node via:
    glyph workflow node-show $WF <parent-node-id> --json
  if response.choiceId == "approve":
    # The "& merge" half of the choice label is a contract, not aspirational
    # text. Auto-merge fires only on the explicit "approve" path; humans who
    # want approval without merge use the freeform input branch instead.
    pr_number, repo = parse from prior dev task's success.output
      (PR URL captured per §Brief inputs table: matches
       https://github.com/<owner>/<repo>/pull/<N>)
    merge_result = sh: gh pr merge <pr_number> --repo <repo> --squash --delete-branch
    if merge_result.exitCode != 0:
      finishWorkflow(failed,
        "human approved but auto-merge failed (exit <code>): <stderr>. " +
        "PR #<pr_number> remains open for manual triage.")
      exit
    merge_commit_sha = sh: gh pr view <pr_number> --repo <repo> --json mergeCommit -q '.mergeCommit.oid'
    finishWorkflow(succeeded, summary={
      "iterations": <count of dev nodes in DAG>,
      "minor_findings_remaining": <count if any>,
      "ci": "all green",
      "approved_by": "human",
      "merged": true,
      "merge_strategy": "squash",
      "merge_commit": "<merge_commit_sha>"
    })
  elif response.choiceId == "changes":
    addSubgraph:
      dev (worker, agent=binwak/engineer, brief=<assembled per brief guidance: dev iteration 2+>)
         parents = [self]
      next-coord (coordinator)
         parents = [dev]
    # brief should include the human's input text as additional guidance
    exit
  elif response.choiceId == "cancel":
    finishWorkflow(failed, "cancelled by human")
    exit
  else (freeform only, no choiceId):
    # interpret the input text as guidance, dispatch next dev iteration
    addSubgraph:
      dev (worker, agent=binwak/engineer, brief=<assembled per brief guidance: dev iteration 2+>)
         parents = [self]
      next-coord (coordinator)
         parents = [dev]
    exit

CASE (coord judgment): workflow is stuck or needs clarification
  # Triggered when coord detects ambiguity, repeated failures on same issue,
  # or design decisions that need human input
  addSubgraph:
    intervention (human, spec={
      prompt: "<describe the problem and what decision is needed>",
      choices: [<relevant options based on situation>]
    })
       parents = [self]
    next-coord (coordinator)
       parents = [intervention]
  exit
```

Use the §B "Batch-mutate the DAG atomically" `add-subgraph` payload shape from the generic skill; substitute `<self-node-id>` with the actual id from the DAG snapshot.

---

## Brief guidance

Coord assembles briefs based on workflow context, DAG state, and parent outputs. The following guidance describes what each brief type should convey — coord adapts emphasis, ordering, and phrasing to the current situation rather than filling rigid templates.

### Brief guidance: dev iteration (first)

The brief should convey:
- The workflow's original goal (from `workflow.brief` and `workflow.details`)
- That this is the first implementation attempt
- Output expectations (branch, PR, etc. — follow the worker's normal dev workflow)

### Brief guidance: dev iteration (2+)

The brief should convey:
- The workflow's original goal
- Which iteration this is and why another iteration is needed
- If from reviewer blockers: what needs fixing (point to where findings are via task ids and artifact paths — don't pre-digest the content)
- If from CI failure: that CI failed, instruct worker to check `gh pr checks`
- If from human feedback: include the human's response text as additional direction
- The branch name to continue on
- Where to find prior verdicts (task ids for fetch)
- CI state instructions: `gh pr checks <pr_number> --json name,state,bucket,link` — for any failing check, how to retrieve logs

### Brief guidance: reviewer

The brief should convey:
- The workflow's goal
- Which dev iteration to review (parent node's task)
- The review MODE (code or ci)
- If iteration 2+: where to find prior review verdict to check for regressions
- The `verdict.json` output protocol (always inline the full schema and validation rules from §C of the generic skill)
- Coord decision rule (so the reviewer understands impact of their verdict)

### Brief guidance: designer

The brief should convey:
- The workflow's goal
- Which dev iteration to review for UI/UX
- If iteration 2+: where to find prior designer verdict
- The `verdict.json` output protocol (same schema as reviewer)

### Brief guidance: ci-waiter

The brief should convey:
- The workflow's goal
- The PR number and repository
- MODE: ci — block on automated checks until terminal
- Detailed instructions for capturing per-job state and log tails
- The `verdict.json` output protocol with CI-specific mapping rules (pass/skipping → APPROVE, fail/cancel → REQUEST_CHANGES with blocker severity)

### Brief guidance: human approval

The prompt should include:
- Brief summary of what was implemented (assembled from workflow brief)
- Iteration count (how many rounds it took)
- PR link
- Reviewer verdict summary (both APPROVE, N minor findings remaining)
- CI status (all green / all green after waiting)

---

## Context sources for brief assembly

When assembling briefs, coord pulls context from these sources. The specific data included depends on the dispatch reason and worker role.

| Context | Source | Notes |
| --- | --- | --- |
| Workflow id | `workflow.id` from `glyph workflow show` | Always included |
| Workflow brief | `workflow.brief` | Always included; verbatim, no rewriting |
| Workflow details | `workflow.details` (may be `null`) | Include when non-empty |
| Iteration number | count of `binwak/engineer` worker nodes already in the DAG, +1 | Dev iteration 2+ briefs |
| Prior review task id | latest task id of the most recent `agent=binwak/reviewer` worker parent of the prior coord (the reviewer-in-pair, NOT a ci-waiter), resolved via `task list --origin workflow --origin-id <that node id>` | Dev iteration 2+ briefs — point worker to where findings live |
| Prior designer task id | latest task id of the most recent `agent=binwak/designer` worker parent of the prior coord, resolved via `task list --origin workflow --origin-id <that node id>` | Dev iteration 2+ briefs |
| Branch name | derived from the prior dev task: resolve its id via `task list --origin workflow --origin-id <prior dev node id>`, parse `pr_number` from `glyph task show <that id> --json`, then `gh pr view <pr_number> --json headRefName -q '.headRefName'` | Dev iteration 2+ briefs |
| PR number | derived from the prior dev task: resolve its id via `task list --origin workflow --origin-id <prior dev node id>`, parse PR number from `glyph task show <that id> --json` (its `success.output` carries the `gh pr create` URL) | Dev iteration 2+, ci-waiter, and human approval prompt |
| Human response | `metadata.response` from human parent node via `glyph workflow node-show` | Dev iteration briefs dispatched after human feedback |

Prior-iter lookups use the "Find prior-iter siblings" snippet from the generic skill §B (same agent FQN, lower phase). For prior review specifically, restrict the lookup to reviewer nodes that paired with a designer sibling — i.e. ignore `ci-waiter` reviewer nodes (single-parent shape per the case bank).

---

## Stop condition

Trigger PR merge (`gh pr merge <N> --repo <owner/repo> --squash --delete-branch`) followed by `finishWorkflow(succeeded, ...)` when a human approval node's response carries `choiceId == "approve"`. If the merge fails (non-zero exit), call `finishWorkflow(failed, "human approved but auto-merge failed: <reason>; PR remains open")` so the PR is visible for manual triage. The human approval gate is reached after: both reviewer verdicts parse cleanly per §C, the union of findings filtered to `severity in ('blocker', 'major')` is empty, AND the CI quality gate is green (either inline via `gh pr checks --json` or via a subsequent `ci-waiter` whose `verdict.json` is `APPROVE`). The success `summary` records `iterations` (count of `binwak/engineer` nodes in the final DAG), `minor_findings_remaining` (visibility — the work ships with them outstanding), `ci` (`"all green"` or `"all green (waited)"`), and `approved_by: "human"`.

No hard iteration cap is baked into this strategy; coord uses its judgment to call `finishWorkflow(failed, "convergence stalled — N iterations and still seeing the same finding category")` when iteration is no longer productive (e.g. the same blocker keeps reappearing, CI keeps flaking on the same job). Coord may also insert a human intervention node when it detects ambiguity or repeated failures requiring human judgment.

---

## Failure-mode coverage

Every `(parent role, parent terminal status)` cell on every expected parent role matches exactly one case in the case bank — verify here when editing.

| Coord wake-up shape | Parent role | Parent status | Matched case | Action |
| --- | --- | --- | --- | --- |
| 0 parents (initial coord node) | — | — | "no parents" | addSubgraph dev + next-coord |
| 1 parent | `binwak/engineer` worker | `succeeded` | "one parent, dev, succeeded" | addSubgraph review + designer + next-coord |
| 1 parent | `binwak/engineer` worker | `failed` | "one parent, dev, failed/cancelled" | finish(failed, "dev iteration ended in failed") |
| 1 parent | `binwak/engineer` worker | `cancelled` | "one parent, dev, failed/cancelled" | finish(failed, "dev iteration ended in cancelled") |
| 2 parents | both reviewers (review + designer) | both `succeeded`, both verdicts APPROVE w/ no blocker/major, every `gh pr checks` bucket in `("pass", "skipping")` | "two parents, both reviewers" → CI sub-case all-green | addSubgraph human approval + next-coord |
| 2 parents | both reviewers (review + designer) | both `succeeded`, both verdicts APPROVE w/ no blocker/major, any `gh pr checks` bucket in `("fail", "cancel")` | "two parents, both reviewers" → CI sub-case any-red | addSubgraph next dev iter |
| 2 parents | both reviewers (review + designer) | both `succeeded`, both verdicts APPROVE w/ no blocker/major, any `gh pr checks` bucket == `"pending"` | "two parents, both reviewers" → CI sub-case pending | addSubgraph ci-waiter + next-coord |
| 2 parents | both reviewers (review + designer) | both `succeeded`, any verdict carries blocker/major | "two parents, both reviewers" → blockers/majors path | addSubgraph next dev iter |
| 2 parents | reviewer | `failed` | "two parents, any failed/cancelled" | finish(failed, "reviewer iteration ended in failed") |
| 2 parents | reviewer | `cancelled` | "two parents, any failed/cancelled" | finish(failed, "reviewer iteration ended in cancelled") |
| 2 parents | reviewer | `succeeded` but `verdict.json` missing / unparseable | "two parents, both reviewers" → §C parse failure | finish(failed, "reviewer <agent> did not produce valid verdict.json") |
| 1 parent | `binwak/reviewer` worker (ci-waiter) | `succeeded`, verdict APPROVE | "one parent, reviewer, succeeded" (ci-waiter terminal) | addSubgraph human approval + next-coord |
| 1 parent | `binwak/reviewer` worker (ci-waiter) | `succeeded`, verdict REQUEST_CHANGES | "one parent, reviewer, succeeded" (ci-waiter terminal) | addSubgraph next dev iter |
| 1 parent | `binwak/reviewer` worker (ci-waiter) | `failed` | "one parent, reviewer, failed/cancelled" (ci-waiter failed) | finish(failed, "ci-waiter iteration ended in failed") |
| 1 parent | `binwak/reviewer` worker (ci-waiter) | `cancelled` | "one parent, reviewer, failed/cancelled" (ci-waiter failed) | finish(failed, "ci-waiter iteration ended in cancelled") |
| 1 parent | human node | `succeeded`, choiceId="approve" | "one parent, human, succeeded" | merge PR via `gh pr merge --squash --delete-branch`, then finish(succeeded) on merge success / finish(failed, "auto-merge failed") on merge failure |
| 1 parent | human node | `succeeded`, choiceId="changes" | "one parent, human, succeeded" | addSubgraph next dev iter + next-coord (include human input as guidance) |
| 1 parent | human node | `succeeded`, choiceId="cancel" | "one parent, human, succeeded" | finish(failed, "cancelled by human") |
| 1 parent | human node | `succeeded`, freeform only (no choiceId) | "one parent, human, succeeded" | addSubgraph next dev iter + next-coord (interpret input as guidance) |
| 1 parent | human node (intervention) | `succeeded` | "(coord judgment)" | interpret response, dispatch appropriate next step |

## Agent compatibility statement

The case bank and brief guidance above were validated against:

| Agent FQN | Minimum AGENTS.md version |
| --- | --- |
| `binwak/engineer` | 0.1.0 |
| `binwak/reviewer` | 0.1.0 |
| `binwak/designer` | 0.1.0 |
| `binwak/coordinator` | 0.1.0 |

Human node support requires coordinator ≥ 0.1.0 (human node awareness in wake-up loop + brief assembly approach).

When any of those agents publishes a new minor or major version, re-read its `AGENTS.md` and bump this strategy's version if any brief guidance needs updating (per `official/workflow-coordination` §E item 6). Coord uses this list at runtime pre-flight (per `official/workflow-coordination` §D) to decide whether the brief + agent are still in sync.