WIP Banzai Codes: add handoff, candidate-summary and PRD actions

banzai-codes/README.md

@@ -0,0 +1,120 @@
+# Banzai pipeline actions
+
+Three composite actions that connect the [Banzai Codes](https://github.com/framna-dk/banzai-codes) refinement flow to the
+[harness](../harness) execution loop and back:
+
+| Action | Trigger | What it does |
+|--------|---------|--------------|
+| [handoff-work-orders](handoff-work-orders) | Scheduled scan | Work orders that reach **In Progress** on the Product board are added to the harness (Development) board at **Todo**, where the orchestrator picks them up. No LLM involved. |
+| [post-candidate-summary](post-candidate-summary) | Scheduled scan | Work orders that reach **Human Review** on the harness board get a Product-Manager-facing summary (generated by Codex from the issue conversation and the pull request, with PR images as proof of work) posted on the issue, and their Product-board status moved to **Acceptance**. |
+| [generate-prd](generate-prd) | Manual dispatch | Generates or incrementally updates a Product Requirements Document — a folder of markdown files describing how the app currently works — and opens a PR. Used to ground Banzai Codes' define flow. |
+
+## One issue, two boards
+
+A work order is a single GitHub issue that sits on two Projects v2 boards at once,
+matching the banzai-codes contracts:
+
+- the **Product board** tracks the user-facing lifecycle: `Define → In Progress →
+  Acceptance → Done`;
+- the **Development (harness) board** tracks the build pipeline: `Ready / Todo /
+  In Progress / Human Review / Merging / Rework / Done`.
+
+No issues are duplicated anywhere; the actions only move board memberships, statuses
+and comments on the one issue.
+
+```
+Banzai Codes (define flow)          grounded by docs/prd (generate-prd)
+        │ publish → Product board "In Progress"
+        ▼
+handoff-work-orders ──▶ issue added to harness board at "Todo"
+        │
+        ▼
+banzai-codes-worker dispatches the coding agent, which opens a PR
+and moves the harness status to "Human Review"
+        │
+        ▼
+post-candidate-summary ──▶ candidate summary comment on the issue
+        │                  + Product board "In Progress" → "Acceptance"
+        ▼
+Banzai Codes review gate (accept / reject)
+```
+
+GitHub Actions cannot trigger on Projects v2 status changes, so `handoff-work-orders` and
+`post-candidate-summary` are **idempotent one-shot scans**: each invocation looks at the
+board, does whatever is missing, and exits. Wire them to a `schedule:` cron (plus
+`workflow_dispatch:` for manual runs) in the app repository:
+
+```yml
+name: Banzai Pipeline
+on:
+  schedule:
+    - cron: "*/15 * * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: banzai-pipeline-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  handoff:
+    runs-on: framna-dk-macos-default
+    steps:
+      - name: Mint App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ vars.PROJECTS_APP_ID }}
+          private-key: ${{ secrets.PROJECTS_APP_PEM }}
+          owner: framna-dk
+          repositories: my-app
+      - uses: framna-dk/actions/banzai-codes/handoff-work-orders@main
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          work-order-project-owner: framna-dk
+          work-order-project-number: 42
+          harness-project-owner: framna-dk
+          harness-project-number: 23
+
+  candidate-summary:
+    runs-on: framna-dk-macos-default
+    needs: handoff
+    steps:
+      - name: Mint App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ vars.PROJECTS_APP_ID }}
+          private-key: ${{ secrets.PROJECTS_APP_PEM }}
+          owner: framna-dk
+          repositories: my-app
+      - uses: framna-dk/actions/banzai-codes/post-candidate-summary@main
+        with:
+          github-token: ${{ steps.app-token.outputs.token }}
+          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+          harness-project-owner: framna-dk
+          harness-project-number: 23
+          work-order-project-number: 42
+```
+
+## Tokens
+
+The board-scanning actions cannot use the default `github.token` — it has no organization
+Projects access. Mint a GitHub App installation token
+(`actions/create-github-app-token@v3`) whose installation grants:
+
+- **Organization → Projects: Read & write** (board scans; the handoff writes the harness
+  board, the summary writes the Product board)
+- **Repository → Issues: Read & write** on the repository holding the work-order issues
+  (the summary action comments on them)
+- For `generate-prd` only (when not using `github.token`): **Contents: Read & write** and
+  **Pull requests: Read & write**
+
+`post-candidate-summary` and `generate-prd` additionally need an `OPENAI_API_KEY` secret for Codex.
+
+## Status name contract
+
+Defaults follow the banzai-codes contracts and the banzai-codes-worker: the worker treats
+`Todo`, `In Progress` and `Rework` as active states, the coding agent parks finished work
+in `Human Review`, and Banzai Codes opens its review gate when the Product board reaches
+`Acceptance`. All status names are inputs, so boards with different vocabularies can
+override them.

banzai-codes/generate-prd/README.md

@@ -0,0 +1,81 @@
+## [Banzai generate PRD](action.yml)
+
+Generates — or incrementally updates — a Product Requirements Document for the
+checked-out application and opens a pull request with the result. The PRD is a folder of
+markdown files (default `docs/prd/`): an `index.md` product overview plus one file per
+feature area, written for LLM readability. Banzai Codes uses it to ground the define
+flow, so new feature requests are refined against how the application actually works
+today.
+
+Codex explores the codebase and writes the documentation; the action then verifies that
+nothing outside the PRD folder was touched, commits to a fixed branch (force-pushed, so
+re-runs update rather than stack), and creates or updates the pull request.
+
+When the PRD folder already exists, the prompt switches to incremental mode: existing
+files are read first, structure and file names are preserved, and only statements the
+codebase contradicts (or gaps it reveals) are changed. The PRD deliberately contains no
+file paths or code snippets — behavior, not implementation — so it stays valid across
+refactors.
+
+### Inputs
+
+| Name | Description | Required | Default |
+|------|-------------|----------|---------|
+| `github-token` | Token with Contents read/write and Pull requests read/write on the repository. | Yes | — |
+| `openai-api-key` | OpenAI API key used by Codex. | Yes | — |
+| `output-directory` | PRD folder, relative to the repository root. | No | `docs/prd` |
+| `base-branch` | Base branch for the pull request. | No | currently checked-out branch |
+| `branch-name` | Working branch the PRD is pushed to (fixed name = idempotent re-runs). | No | `banzai/prd-update` |
+| `codex-model` | Model used by Codex. | No | `gpt-5.4` |
+| `codex-effort` | Reasoning effort used by Codex. | No | — |
+| `codex-sandbox` | Sandbox mode for Codex. | No | `workspace-write` |
+| `codex-safety-strategy` | Safety strategy passed to codex-action. | No | `unsafe` |
+| `extra-instructions` | Additional instructions appended to the PRD prompt. | No | — |
+| `pr-title` | Title for the PRD pull request. | No | `Update product requirements documentation` |
+
+### Outputs
+
+| Name | Description |
+|------|-------------|
+| `changed` | Whether the PRD changed in this run. |
+| `pr-url` | URL of the created or updated pull request (empty when unchanged). |
+| `pr-number` | Number of the created or updated pull request (empty when unchanged). |
+
+### Usage
+
+```yml
+name: Generate PRD
+on:
+  workflow_dispatch:
+    inputs:
+      extra-instructions:
+        description: Optional focus areas for this PRD pass.
+        required: false
+
+jobs:
+  prd:
+    runs-on: framna-dk-macos-default
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: framna-dk/actions/banzai-codes/generate-prd@main
+        with:
+          github-token: ${{ github.token }}
+          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
+          extra-instructions: ${{ inputs.extra-instructions }}
+```
+
+### Notes
+
+- The repository **must be checked out** before this action runs; it fails fast otherwise.
+- The branch push uses the credentials persisted by `actions/checkout`; the
+  `github-token` input is only used for the pull-request API calls. If your organization
+  blocks `github.token` from creating pull requests, mint a GitHub App token with
+  Contents + Pull requests write and pass it to both `actions/checkout` and this action.
+- If Codex modifies anything outside `output-directory`, the run fails before committing
+  (scope guard), so a bad generation can never reach the repository.