@plainconceptsplatform/workflows 0.19.2 → 0.20.0

package/loops/workflows/agent-refine.md

@@ -24,6 +24,7 @@ env:
   # re-running a decision produces the same decision. Created idempotently where it is applied.
   STALLED_LABEL: stalled
   REFINE_MARKER: "<!-- agent-refine -->"
+  DRAFT_MARKER: "<!-- agent-refine-draft -->"
   INITIAL_MODE: first
   RESPONSE_MODE: rerefine
   MAX_SELF_QUESTIONS: "5"
@@ -46,6 +47,10 @@ description: |
   Refines an issue into a user story, on a first pass or after the author has answered the
   bot's questions. Replaces .loops/recipes/refine-loop.yaml.
 
+  The refined story is wrapped in the repository's own issue template when one matches.
+  When questions remain, the worker leaves that template-wrapped temporal draft on the
+  issue and asks every remaining question in a single batched comment.
+
   Before writing the story, the agent explores the codebase per work unit (each bullet in a
   bullet-list issue is its own unit), answering its own questions where the code can and
   escalating only genuine business decisions to the author.
@@ -173,6 +178,7 @@ jobs:
         with:
           output-file: ${{ steps.output.outputs.output-file }}
           marker: ${{ env.REFINE_MARKER }}
+          draft-marker: ${{ env.DRAFT_MARKER }}
           comment-prefix: ${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}
           issue-number: ${{ inputs.issue-number }}
   conclude:
@@ -472,7 +478,9 @@ timeout-minutes: 90
 
    - On a `${{ env.INITIAL_MODE }}` pass, refine from scratch.
    - On a `${{ env.RESPONSE_MODE }}` pass, incorporate only the supplied answers from the issue author or an
-     assignee. Do not use answers from other commenters.
+     assignee. Do not use answers from other commenters. The body may already hold the
+     temporal draft from the earlier pass: reuse what still holds, and resolve its pending
+     marks with the author's answers.
 
 3. Explore before you write. Call skill("pc-plan-explore"); it owns the stance for this step.
 
@@ -516,8 +524,8 @@ timeout-minutes: 90
    No "As a / I want / so that" form. No Given/When/Then. No Mermaid. Just the marker,
    the summary, and the checklist.
 
-   Load `@humanizer` and prepare the replacement issue body, then go directly to step 7
-   (estimate). Skip steps 5 and 6.
+   Load `@humanizer` and prepare the replacement issue body, then go directly to step 8
+   (estimate). Skip steps 5-7.
 
 5. Before writing the story, verify coverage: list every work unit and confirm each one has
    exploration findings concrete enough for acceptance criteria. If any unit is missing, go back
@@ -531,9 +539,36 @@ timeout-minutes: 90
      Apply repository documentation and established conventions before finalizing the story.
      Adhere to ${{ env.REPO_RULES }}.
 
-6. Load `@humanizer` and prepare the complete replacement issue body as valid Markdown.
+6. **Wrap the story in the repository's issue form.** The body people read must follow the
+   repository's own issue template when one exists; the story is the content, the template
+   is the shape.
+
+   Find the form first:
+
+   - List the YAML and Markdown forms under `.github/ISSUE_TEMPLATE/`, plus a legacy
+     `.github/issue_template.md` or a root `template.yml`. `config.yml` there only declares
+     contact links, which are not forms: ignore it.
+   - When a form filters by labels and the issue carries one of those labels, that form
+     wins. Otherwise use the repository's default form.
+   - When the repository has no form at all, keep the free-form story shape from step 5:
+     there is nothing to wrap around.
+
+   Then fill it:
+
+   - Draw every field's content from your exploration findings. Required fields always get
+     real content; optional fields only when you genuinely have something for them.
+   - The story narrative lands in the field that asks for it — proposal, description, or
+     what-happened, depending on the form.
+   - The Given/When/Then scenarios go into the form's acceptance-criteria field when it has
+     one; otherwise they stay a section of their own. The Mermaid diagram goes where it
+     reads best inside the filled form.
+   - The machine-readable lines the later steps add — split markers in step 9, estimate
+     lines in step 10 — always sit at the very top of the body, above the form's first
+     heading, so the workflow can read them whatever the form's shape.
 
-7. **Estimate the story in points.** Use the Fibonacci scale, where one point is roughly one
+7. Load `@humanizer` and prepare the complete replacement issue body as valid Markdown.
+
+8. **Estimate the story in points.** Use the Fibonacci scale, where one point is roughly one
    human day of work for a developer who knows this codebase. Estimate the whole story: code,
    tests, and the edge cases the acceptance criteria imply.
 
@@ -546,7 +581,7 @@ timeout-minutes: 90
    Elapsed clock time is not evidence. A large change can land in minutes and a small one can
    wait days for a human, so never reason from how long anything took.
 
-8. **Split when the estimate is ${{ env.SPLIT_THRESHOLD }} or more.** An oversized story is the
+9. **Split when the estimate is ${{ env.SPLIT_THRESHOLD }} or more.** An oversized story is the
    single best predictor of a pull request that never lands.
 
    First test whether it *can* split. A story splits when it contains slices that are each
@@ -555,7 +590,7 @@ timeout-minutes: 90
    on its own cannot be verified.
 
    **If it splits:** write between two and ${{ env.MAX_SPLIT_CHILDREN }} children. Each child is
-   a complete refined story in the same format you would have written for the whole, with its own
+   a complete refined story wrapped in the same issue form, with its own
    acceptance criteria, its own tests section, and its own estimate of 5 or less. Never write a
    child estimated at 1: that is a fragment, so fold it into a sibling. Call `create_issue` once
    per child, and in each child body include:
@@ -571,7 +606,7 @@ timeout-minutes: 90
    single story and say so in one sentence in the body, under the estimate. An honest 8 is more
    useful than three fake threes that each break the build.
 
-9. **Record the estimate in every body you write**, parent and children alike, immediately below
+10. **Record the estimate in every body you write**, parent and children alike, immediately below
    the title line, as exactly these two lines:
 
    ```
@@ -582,12 +617,22 @@ timeout-minutes: 90
    The visible line is for people and the marker is read by the workflow, which turns it into the
    `sp-N` label. A body without the marker gets no estimate label at all.
 
-10. Decide exactly one outcome:
+11. Decide exactly one outcome:
 
     Labels are workflow-owned state. Do not call `add_labels` or `remove_labels`.
 
     **Questions remain.** You set aside one or more questions for the author that the codebase
-    could not answer. Leave the body unchanged. Call `add_comment` once with:
+    could not answer. Leave the partial work visible: first call `update_issue` with a
+    temporal draft, then call `add_comment` once with the questions.
+
+    The temporal draft is the replacement body your path would have written — the filled
+    issue form from step 6 on the standard path, the marker, summary and checklist from
+    step 4a on the trivial path — holding everything you already established, with every
+    part the questions leave open marked `_pending — see questions below_`. Its very
+    first line is `${{ env.DRAFT_MARKER }}`; the next run replaces the draft wholesale
+    with the final body.
+
+    The comment carries:
    1. `${{ env.REFINE_MARKER }}`
    2. `${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}`
    3. `I have some questions about this issue. Please reply in one comment and I'll process your answers.`
@@ -597,10 +642,9 @@ timeout-minutes: 90
    them is a domain expert, not an engineer.
 
     **The story is complete.** You answered every exploration question yourself and none remain
-    for the author.
-
-    Call `update_issue` first, with the replacement body, and wait for it to come back. Send
-    the whole body in that one call: it is the only thing this step has to get right.
+    for the author. Call `update_issue` first, with the wrapped replacement body, and wait
+    for it to come back. Send the whole body in that one call: it is the only thing this
+    step has to get right.
 
     Only once that call has succeeded, call `add_comment`
     with `${{ env.REFINE_MARKER }}`, then `${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}`,
@@ -618,5 +662,5 @@ timeout-minutes: 90
     seams. Call `create_issue` once per child, then `update_issue` on the parent with the
     summary and the checklist, then `add_comment` with `${{ env.REFINE_MARKER }}`, then
     `${{ env.SAFE_OUTPUT_COMMENT_PREFIX }}`, then one sentence naming the estimate you gave the
-    whole and how many children you wrote. The children carry the work forward; the parent stays
-    open as their tracker and is never implemented directly.
+   whole and how many children you wrote. The children carry the work forward; the parent stays
+   open as their tracker and is never implemented directly.

package/loops/workflows/authorize-bot-work.yml

@@ -1,105 +1,105 @@
-# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
-# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
-# This ensures the bot is the actor for all agentic workflows.
-#
-# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
-# it adds bot-working itself, so authorize-bot-work must not fire again.
-name: "Authorize Bot Work"
-
-run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
-
-on:
-  issues:
-    types: [labeled]
-
-permissions:
-  contents: read
-
-jobs:
-  authorize:
-    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
-    # already own the issue.
-    #
-    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
-    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
-    # to a parked issue got no run, no comment and no error anywhere. Triage's own
-    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
-    #
-    # A person adding a work label IS the human review the label was waiting for, so this
-    # workflow clears it below before handing the issue to the bot. The classifier's own guard
-    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
-    # bot-working is added `review` is already gone.
-    if: >
-      (github.event.label.name == 'implement' ||
-       github.event.label.name == 'refine') &&
-      !contains(github.event.issue.labels.*.name, 'bot-working') &&
-      !endsWith(github.actor, '[bot]')
-    runs-on: ubuntu-latest
-    timeout-minutes: 5
-    concurrency:
-      group: authorize-${{ github.event.issue.number }}
-      cancel-in-progress: false
-    permissions:
-      contents: read
-      issues: write
-    steps:
-      - name: Check actor permission
-        id: check
-        env:
-          GH_TOKEN: ${{ github.token }}
-          ACTOR: ${{ github.actor }}
-        run: |
-          set -euo pipefail
-          
-          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
-            --jq '.permission' 2>/dev/null || echo "none")
-          
-          case "$permission" in
-            admin | maintain | write)
-              echo "authorized=true" >> "$GITHUB_OUTPUT"
-              echo "::notice::$ACTOR has $permission permission - authorized"
-              ;;
-            *)
-              echo "authorized=false" >> "$GITHUB_OUTPUT"
-              echo "::warning::$ACTOR has '$permission' permission - not authorized"
-              ;;
-          esac
-
-      - name: Checkout for App token action
-        if: steps.check.outputs.authorized == 'true'
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
-
-      - name: Generate App token
-        if: steps.check.outputs.authorized == 'true'
-        id: app-token
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
-        with:
-          app-id: ${{ secrets.BOT_APP_ID }}
-          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
-
-      - name: Bot takes the issue over
-        if: steps.check.outputs.authorized == 'true'
-        env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-          ISSUE_NUMBER: ${{ github.event.issue.number }}
-          LABEL: ${{ github.event.label.name }}
-        run: |
-          set -euo pipefail
-
-          # Clear review FIRST. A person adding a work label is the human review the label was
-          # waiting for, and the classifier refuses to route an issue that still carries it, so
-          # removing it here is what makes the hand-off work at all. It also has to happen
-          # before bot-working, because that is the event the classifier reads: adding
-          # bot-working first would raise an event whose payload still shows review.
-          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
-          # `stalled` goes with it: a person taking the issue on restarts the work, so the
-          # marker the janitor retries on must not survive into the new run.
-          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
-            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
-
-          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
-          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
-
-          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"
+# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/authorize-bot-work.yml. Update with `workflows update --force`; consumer edits may be overwritten.
+# Human adds implement/refine/direct/feature label → validates permission → bot adds bot-working
+# This ensures the bot is the actor for all agentic workflows.
+#
+# IMPORTANT: Only triggers for HUMAN actors. When the bot transitions refine→implement,
+# it adds bot-working itself, so authorize-bot-work must not fire again.
+name: "Authorize Bot Work"
+
+run-name: "Authorizing: ${{ github.event.issue.title }} (#${{ github.event.issue.number }})"
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  contents: read
+
+jobs:
+  authorize:
+    # Only trigger for work labels from HUMANS (not bots), and only if another bot run does not
+    # already own the issue.
+    #
+    # `review` is deliberately NOT excluded. It used to be, and that made the label a one-way
+    # door: the classifier refuses to route while `review` is set, so a person adding `refine`
+    # to a parked issue got no run, no comment and no error anywhere. Triage's own
+    # needs-maintainer verdict tells the maintainer to add `refine`, which could not work.
+    #
+    # A person adding a work label IS the human review the label was waiting for, so this
+    # workflow clears it below before handing the issue to the bot. The classifier's own guard
+    # stays as it is: it exists to stop the *bot* re-triggering itself, and by the time
+    # bot-working is added `review` is already gone.
+    if: >
+      (github.event.label.name == 'implement' ||
+       github.event.label.name == 'refine') &&
+      !contains(github.event.issue.labels.*.name, 'bot-working') &&
+      !endsWith(github.actor, '[bot]')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    concurrency:
+      group: authorize-${{ github.event.issue.number }}
+      cancel-in-progress: false
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      - name: Check actor permission
+        id: check
+        env:
+          GH_TOKEN: ${{ github.token }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          set -euo pipefail
+          
+          permission=$(gh api "repos/$GITHUB_REPOSITORY/collaborators/$ACTOR/permission" \
+            --jq '.permission' 2>/dev/null || echo "none")
+          
+          case "$permission" in
+            admin | maintain | write)
+              echo "authorized=true" >> "$GITHUB_OUTPUT"
+              echo "::notice::$ACTOR has $permission permission - authorized"
+              ;;
+            *)
+              echo "authorized=false" >> "$GITHUB_OUTPUT"
+              echo "::warning::$ACTOR has '$permission' permission - not authorized"
+              ;;
+          esac
+
+      - name: Checkout for App token action
+        if: steps.check.outputs.authorized == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Generate App token
+        if: steps.check.outputs.authorized == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ secrets.BOT_APP_ID }}
+          private-key: ${{ secrets.BOT_PRIVATE_KEY }}
+
+      - name: Bot takes the issue over
+        if: steps.check.outputs.authorized == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          LABEL: ${{ github.event.label.name }}
+        run: |
+          set -euo pipefail
+
+          # Clear review FIRST. A person adding a work label is the human review the label was
+          # waiting for, and the classifier refuses to route an issue that still carries it, so
+          # removing it here is what makes the hand-off work at all. It also has to happen
+          # before bot-working, because that is the event the classifier reads: adding
+          # bot-working first would raise an event whose payload still shows review.
+          # --remove-label on an absent label is a no-op, so this is safe on a fresh issue.
+          # `stalled` goes with it: a person taking the issue on restarts the work, so the
+          # marker the janitor retries on must not survive into the new run.
+          gh issue edit "$ISSUE_NUMBER" --remove-label "review" --remove-label "stalled" 2>/dev/null ||
+            echo "::notice::no review or stalled label to clear on #$ISSUE_NUMBER"
+
+          echo "Adding bot-working label to issue #$ISSUE_NUMBER (triggered by $LABEL)"
+          gh issue edit "$ISSUE_NUMBER" --add-label "bot-working"
+
+          echo "::notice::bot-working label added - bot will now own the $LABEL workflow"