work-on-task.yml

# Unified task workflow: single or multi-task implement → release → PR → review cycles → reorganize → push
# Usage: /as-assign-prepare work-on-task --taskref 123
#        /as-assign-prepare work-on-task --taskrefs 148,149,150
#        /as-assign-prepare work-on-task --taskrefs 148-152
#        /as-assign-prepare work-on-task --taskrefs "240.*"

name: work-on-task
description: Work on one or more tasks with PR, review cycles, release, and clean history

parameters:
  taskrefs:
    required: true
    type: array
    description: Task references (comma-separated, range, or pattern)

steps:
  - name: onboard
    number: "000"
    workflow: wfi://onboard
    instructions:
      - "Load project context for the task batch: {{taskrefs}}."

  - name: verify-test-suite
    number: "012"
    workflow: wfi://assign/verify-test-suite
    instructions:
      - "Verify test coverage and performance across batch tasks: {{taskrefs}}."
      - "First run `ace-test <package> all --profile 6` for each package modified by this batch."
      - "Then run `ace-test-suite --target all`."
      - "If the batch is documentation-only or otherwise does not affect runnable code, mark this step skipped with a clear reason."

  - name: release-minor
    number: "020"
    instructions:
      - Release all modified packages touched by this batch.
      - Auto-detect modified packages from the current diff, bump version (minor or patch, usually minor), and update both package and root CHANGELOGs.
      - This is the initial release for new functionality.
      - Follow semantic versioning conventions.

  - name: update-docs
    number: "025"
    workflow: wfi://docs/update
    instructions:
      - "Update docs for public contract changes introduced across batch tasks: {{taskrefs}}."
      - "Limit updates to packages whose CLI commands, flags, outputs, or public APIs changed across the batch."
      - "Validate updated docs before completing the step."
      - "Skip if the batch introduced no public-facing contract change."

  - name: create-pr
    number: "030"
    workflow: wfi://github/pr/create
    instructions:
      - "Create a pull request summarizing batch tasks: {{taskrefs}}."
      - "Capture the PR number for the downstream review and PR-update steps."

  - name: review-valid-1
    number: "040"
    context: fork
    sub_steps: [review-pr, apply-feedback, release]
    instructions:
      - Execute the valid review cycle via child steps.
      - "Child review-pr: use preset code-valid."
      - "Focus: correctness — bugs, logic errors, missing functionality, broken contracts."
      - "Child apply-feedback: apply medium+ priority review findings and commit."
      - "Child release: follow `ace-bundle wfi://release/publish` to publish patch-level updates for modified packages touched by valid-cycle fixes and update both package and root CHANGELOGs."

  - name: review-fit-1
    number: "070"
    context: fork
    sub_steps: [review-pr, apply-feedback, release]
    instructions:
      - Execute the fit review cycle via child steps.
      - "Child review-pr: use preset code-fit."
      - "Focus: quality — performance, architecture, standards, test coverage."
      - "Child apply-feedback: apply fit-cycle findings and commit."
      - "Child release: follow `ace-bundle wfi://release/publish` to publish patch-level updates for modified packages touched by fit-cycle fixes and update both package and root CHANGELOGs."

  - name: review-shine-1
    number: "100"
    context: fork
    sub_steps: [review-pr, apply-feedback, release]
    instructions:
      - Execute the shine review cycle via child steps.
      - "Child review-pr: use preset code-shine."
      - "Focus: polish — simplification, naming, documentation (non-blocking suggestions)."
      - "Child apply-feedback: apply worthwhile shine-cycle findings and commit."
      - "Child release: follow `ace-bundle wfi://release/publish` to publish patch-level updates for modified packages touched by shine-cycle fixes and update both package and root CHANGELOGs."

  - name: reorganize-commits
    number: "130"
    workflow: wfi://git/reorganize-commits
    instructions:
      - "Reorganize commits for the batch work on: {{taskrefs}}."
      - "Group commits by concern where possible, such as structure, implementation, tests, docs, and release updates."

  - name: push-to-remote
    number: "140"
    instructions:
      - Push all changes to the remote repository.
      - "Run: git push --force-with-lease origin HEAD"
      - Force-with-lease needed because reorganize-commits rewrites history.

  - name: record-demo
    number: "145"
    instructions:
      - "Record a demo that shows the feature implemented in this PR and attach it."
      - "Find the demo scenario:"
      - "  1. Read the task spec's Demo Scenario section for scene definitions and fixture requirements"
      - "  2. Check `.ace-tasks/<taskref>/demo/*.tape.yml` for an existing tape"
      - "  3. Check `<package>/docs/demo/` for package-level tapes relevant to the changes"
      - "  4. If no tape or scenario exists, design one following the pattern: show input → run feature → verify result"
      - "Create the tape:"
      - "  - Create `fixtures/` directory next to the tape with all input data referenced in scenes"
      - "  - Use `copy-fixtures` in setup so fixtures are available in sandbox"
      - "  - Use relative paths only (fixtures get copied to sandbox root)"
      - "  - Set sleep times so viewer can read output: 3-5s for command output, 1s for clear"
      - "  - For commands that take time (recording, builds), set sleep to the expected duration + 5s buffer"
      - "  - Do NOT use playback_speed — record at normal speed for readability"
      - "Validate before recording:"
      - "  - Run `ace-demo record <tape> --dry-run` to verify no path errors"
      - "  - Ensure all fixtures exist and are referenced correctly"
      - "Record and attach: `cd <package> && ace-demo record <tape-path> --pr <PR_NUMBER>`."
      - "If VHS or FFmpeg is not installed (`which vhs` / `which asciinema` / `which agg` all fail), skip this step."
      - "Non-blocking policy — if recording fails, diagnose before skipping:"
      - "  1. Read the error message and identify the cause (missing font, missing tool, config mismatch, path error)"
      - "  2. Check config: `cat <package>/.ace-defaults/demo/config.yml` and compare `agg_font_family` against available fonts (`fc-list | grep -i nerd | head -5`)"
      - "  3. Check spike findings: search `.ace-tasks/` or `.ace-retros/` for spike docs that document working configurations"
      - "  4. Fix and retry: if the cause is a fixable config/env issue (wrong font, missing fixture, bad path), fix it and retry"
      - "  5. Only skip if the failure is truly unfixable (tool not installed, no tapes exist, hardware dependency)"

  - name: update-pr-desc
    number: "150"
    context: fork
    workflow: wfi://github/pr/update
    instructions:
      - "Update the PR description with the final batch summary for: {{taskrefs}}."
      - "CRITICAL: The File Changes section must contain the complete, untruncated grouped-stats output from `ace-git diff`. Paste it verbatim — never summarize or abbreviate."
      - "Include final release/version information and the key completed components when applicable."
      - "Make sure the PR description reflects the post-review final state."

  - name: mark-tasks-done
    number: "155"
    workflow: wfi://task/update
    instructions:
      - "Mark each top-level task in {{taskrefs}} as done and archive it."
      - |
        Run this loop for each task in the batch:
        - Parse and normalize:
          - `TASKREFS="{{taskrefs}}"`
          - `IFS=',' read -ra refs <<< "${TASKREFS// /}"`
        - For each `ref`:
          - `ace-task update "$ref" --set status=done --move-to archive --gc`

  - name: create-retro
    number: "160"
    skill: as-retro-create
    instructions:
      - "Create a retrospective for the batch work on: {{taskrefs}}."
      - "Capture what went well, what could improve, and action items across the batch."
      - "Focus on process learnings, not just task outcomes."

expansion:
  batch-parent:
    name: batch-tasks
    number: "010"
    batch_parent: true
    parallel: false
    fork_retry_limit: 1
    instructions: |
      Batch container for multiple task implementations.
      This step auto-completes when all child tasks are done.

      Tasks to implement: {{taskrefs}}

  foreach: taskrefs
  child-template:
    name: "work-on-{{item}}"
    parent: "010"
    context: fork
    workflow: wfi://task/work
    taskref: "{{item}}"
    sub_steps:
      - onboard-base
      - task-load
      - plan-task
      - work-on-task
      - pre-commit-review
      - verify-test
      - release-minor
      - create-retro
    instructions: |
      Use existing base and task context loaded by the batch workflow.
      Implement task {{item}}.

      **Prior sibling context** (for sequential batches):
      If this task has dependencies on earlier tasks in the batch, load their context before planning:
      1. Read completed sibling task specs: `ace-bundle task://<dependency-ref>` for each ref in the task's `dependencies` field
      2. Read completed sibling reports from `.ace-local/assign/<assignment-id>/reports/<sibling-step>.*` — especially `work-on-task` and `plan-task` reports
      3. Use this context during planning to identify existing implementations to refactor rather than reimplement

      When complete, mark the task as done: run `ace-task update {{item}} --set status=done --move-to archive`