ace-assign 0.37.0 → 0.40.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 546f8d510f0767f994deba4c11c10019d4dc320781c5b242e0362431e5e91166
-  data.tar.gz: 52cf891a41c8f2f80ba9bfd7fd19db57b5691dda2e67774e16004d3b1358b543
+  metadata.gz: f23355862efe90eb831ccb84423985e43a6961c1b3dff79648984cf6d3012f56
+  data.tar.gz: 0be151272116e8104dcb1686f9759df2e12b321d86ae6e913b5d4189b8c6bf71
 SHA512:
-  metadata.gz: e02c6d947497dd2e8fe5c00825a303759994de830394eefe54506b93924b6c5e78ea21a7cc4a839e816aeeb2fd04c14b9c56958b0e6d7145622cb42049c82869
-  data.tar.gz: c014fc052851855bfe3f2144c9056a2ef18f1c25884e567f71f8d03cad1eed009981aacc755799b04a344ac323c929fb0f9841ba5e7e6273b7cda6885c1173aa
+  metadata.gz: 7737ef4fe083b8e758bb7cfa16fea1205bec8b7668504ca524a3bb48d1f802559a6837e60d1cf0c55594b99c8c04aae8f873732f945a3ee640dff665bf92fb40
+  data.tar.gz: ab02e5b7298297e0dfff4c2dc75a8c45b2c029ab7e8ae084df77970e90be1518e392f0575fc94d457e72059401ce3c7208071cebf6606981493fc9d88baac7c7

data/.ace-defaults/assign/catalog/composition-rules.yml

@@ -58,6 +58,16 @@ ordering:
     after: update-pr-desc
     note: "PR description should reflect post-rebase branch state"
 
+  - rule: push-before-record-demo
+    before: push-to-remote
+    after: record-demo
+    note: "Demo recording requires pushed code and existing PR"
+
+  - rule: record-demo-before-update-pr
+    before: record-demo
+    after: update-pr-desc
+    note: "PR description should reference attached demo if available"
+
   - rule: push-before-update-pr
     before: push-to-remote
     after: update-pr-desc
@@ -181,9 +191,9 @@ conditional:
     note: "Test suite verification with profiling catches slow tests and regressions before release. In explicit-step mode this remains advisory unless policy elevates it."
 
   - when: "assignment includes work-on-task and touches CLI commands or public API"
-    suggest: [verify-e2e, update-docs]
+    suggest: [verify-e2e, update-docs, record-demo]
     strength: recommended
-    note: "Public contract changes require E2E verification and doc updates"
+    note: "Public contract changes require E2E verification, doc updates, and demo recording"
 
   - when: "task involves auth, security, or data handling"
     suggest: [security-audit]

data/.ace-defaults/assign/catalog/recipes/implement-with-pr.recipe.yml

@@ -38,6 +38,9 @@ steps:
     required: false
   - name: push-to-remote
     required: true
+  - name: record-demo
+    required: false
+    note: "Record demos for modified packages with tapes; skip if no tapes or VHS unavailable"
   - name: update-pr-desc
     required: false
 
@@ -46,3 +49,4 @@ customization_hints:
   - "Add security-audit for security-sensitive changes"
   - "Reduce review cycles to 1 for simple changes"
   - "Skip reorganize-commits if commit history is already clean"
+  - "Skip record-demo if VHS is not available or no tape files exist"

data/.ace-defaults/assign/catalog/steps/record-demo.step.yml

@@ -0,0 +1,39 @@
+name: record-demo
+skill: as-demo-record
+description: Record terminal demos for modified packages and attach to PR
+intent:
+  phrases:
+    - "record demo"
+    - "record demos for pr"
+    - "attach demo to pr"
+    - "create demo recording"
+
+prerequisites:
+  - name: push-to-remote
+    strength: required
+    reason: "Code must be pushed so demo reflects what reviewers see"
+  - name: create-pr
+    strength: required
+    reason: "PR number needed for demo attachment"
+
+produces: [demo-recording, pr-comment]
+consumes: [pull-request, remote-sync]
+
+context:
+  default: null
+  reason: "Demo recording needs VHS and FFmpeg in the local environment"
+
+when_to_skip:
+  - "No modified packages have tape files at <package>/docs/demo/"
+  - "VHS is not available in the environment"
+  - "Changes are documentation-only (no runnable code changed)"
+  - "No user-facing CLI changes"
+
+effort: medium
+tags: [demo, pr, documentation, recording]
+decision_notes:
+  non_blocking_policy: >
+    "non-blocking" means do not block subsequent steps if truly unfixable.
+    It does NOT mean skip on first failure. Diagnose the error, check config
+    against known-good values (spike findings, test fixtures), fix environment
+    issues, and retry before reporting failure.

data/.ace-defaults/assign/presets/work-on-task.yml

@@ -113,6 +113,34 @@ steps:
       - "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
@@ -166,6 +194,15 @@ expansion:
     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}}.

data/CHANGELOG.md

@@ -7,6 +7,132 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.40.3] - 2026-03-27
+
+### Fixed
+- Corrected `ace-assign add` documentation examples to match the mutually exclusive add-mode contract (`--yaml`, `--step`, or `--task`).
+- Replaced invalid preset-step examples in docs with preset-backed step names that resolve under the current `--step` behavior.
+
+## [0.40.2] - 2026-03-27
+
+### Fixed
+- Validated preset names before file resolution to block invalid path-like preset inputs.
+- Added `ace-assign add --task` task-reference existence validation before mutating assignment queues.
+- Corrected `ace-assign add --task` insertion semantics to honor `--child`; explicit `--after` without `--child` now inserts as a sibling.
+- Added explicit preset-step resolver errors when presets define no usable `steps` array.
+
+### Technical
+- Added regression coverage for preset-name validation and empty-preset-step diagnostics.
+- Added `add --task` coverage for task-ref validation and sibling insertion with `--after` when `--child` is not set.
+- Added end-to-end CLI coverage for `ace-assign create --task` assignment and step-file materialization.
+
+## [0.40.1] - 2026-03-27
+
+### Fixed
+- Updated task-driven preset guard checks to evaluate active resolved refs after terminal filtering, preventing false single-task preset rejections on mixed terminal/non-terminal inputs.
+- Preserved parent refs during taskref expansion when all subtasks are terminal, preventing empty expansion results from valid parent-task inputs.
+- Normalized `detect_batch_parent` fallback return behavior to preserve nil semantics when no batch parent is found.
+
+### Technical
+- Made hidden task-driven job specs use unique filenames to preserve assignment source-config provenance across repeated create flows.
+- Updated command coverage for randomized hidden job filename generation.
+
+## [0.40.0] - 2026-03-27
+
+### Added
+- Added flags-only `ace-assign create --task ...` support for preset-based assignment creation from task refs, including multi-task input.
+- Added a shared `TaskAssignmentCreator` path so direct `create --task` and `ace-overseer` launch use the same preset expansion and hidden job generation behavior.
+
+### Changed
+- Replaced positional `ace-assign create CONFIG` with explicit `--yaml` and `--task` modes.
+- Updated `work-on-task` task-child expansion so generated `work-on-{{item}}` roots include the full `task/work` sub-step sequence, including `pre-commit-review`, `release-minor`, and `create-retro`.
+- Refreshed docs and workflow wording to use the explicit `ace-assign create --yaml ...` contract.
+
+### Technical
+- Added command coverage for create-mode validation and task-driven creation edge cases.
+- Added `ace-task` as a runtime dependency for task-ref-based creation.
+
+## [0.39.1] - 2026-03-27
+
+### Fixed
+- Updated the `as-assign-add-task` workflow and related docs to use the current `ace-assign add --yaml` contract instead of removed `--from` usage.
+- Refreshed preset step insertion name resolution to re-read queue names between insertions, preventing stale iteration-name collisions when canonical expansion adds additional steps.
+- Added debug-time warnings for unexpanded `{{token}}` placeholders in `--task` preset templates.
+
+### Technical
+- Added regression coverage for preset insertion name-refresh behavior across canonical subtree expansion.
+- Added regression coverage for unexpanded template-token warnings in debug `--task` mode.
+- Normalized `detect_batch_parent` return semantics to always return a string value.
+
+## [0.39.0] - 2026-03-27
+
+### Added
+- Added preset-aware `ace-assign add --step <name[,name...]>` mode with exact-first and base-name fallback resolution.
+- Added preset-aware `ace-assign add --task <ref>` mode using preset `expansion.child-template` with automatic batch-parent detection.
+- Added new preset insertion support modules: `PresetLoader`, `PresetStepResolver`, and `PresetInferrer`.
+
+### Changed
+- Replaced legacy `ace-assign add` insertion contract with exactly one required mode: `--yaml`, `--step`, or `--task`.
+- Renamed YAML file insertion flag from `--from` to canonical `--yaml`.
+- Removed positional `name` insertion mode in favor of explicit `--step`.
+
+### Technical
+- Expanded command and atom/molecule test coverage for mode validation, preset loading, step resolution, auto-iteration naming, and preset inference fallback behavior.
+
+## [0.38.3] - 2026-03-27
+
+### Added
+- Added `ace-assign add --from <file>` to insert multiple steps from YAML, including nested `sub_steps` expansion.
+- Added the `as-assign-add-task` skill and `wfi://assign/add-task` workflow for guided subtree insertion.
+
+### Fixed
+- Prevalidated full `add_batch` trees before mutating assignment queues, preventing partial insertion when later batch entries are invalid.
+- Normalized nested batch child-depth overflow handling by converting `StepNumbering` depth `ArgumentError` into `Ace::Assign::Error`.
+- Routed workflow/skill/sub-step batch insertions through canonical subtree expansion and materialization.
+- Reworded executor-level child insertion validation to domain language so non-CLI callers are not coupled to CLI flag syntax.
+- Removed stale add-task child-step hardcoding drift by relying on workflow `assign.sub-steps` resolution at insertion time.
+
+### Changed
+- Extended assignment insertion execution with batch insertion support and frontmatter passthrough for inserted steps.
+- Unified dynamic step default instructions under a single `AssignmentExecutor::DEFAULT_DYNAMIC_STEP_INSTRUCTIONS` source.
+- Limited canonical batch expansion to explicit `workflow`, `skill`, or declared `sub_steps` inputs, preserving prior numbering behavior for plain flat batch inserts.
+- Updated usage, getting-started, and handbook docs to cover the new `add --from` workflow.
+- Updated `record-demo` step instructions to require diagnosis before skipping on failure — agents must check config, available fonts, and spike findings before reporting a non-blocking skip.
+- Added `decision_notes.non_blocking_policy` to `record-demo` step catalog entry clarifying that "non-blocking" means "diagnose and retry before skipping," not "skip on first failure."
+
+### Technical
+- Expanded command and executor coverage for `--from` validation, child rebalance behavior, and metadata preservation.
+- Added regression tests for batch insertion validation, depth overflow, and workflow-backed inserts.
+- Renamed add-command local boolean flags to predicate-style names (`name_given`, `from_given`) for readability.
+
+## [0.38.2] - 2026-03-26
+
+### Changed
+- Updated `work-on-task` prepare/create filtering guidance to treat terminal task statuses (`done`, `skipped`, `cancelled`) as filtered refs and abort all-terminal requests before assignment creation.
+- Updated no-op messaging and edge-case language across prepare/create workflow instructions and usage docs to match the terminal-status contract.
+
+### Technical
+- Replaced fragile done-filter workflow contract assertions with stronger section-scoped terminal-contract checks.
+- Moved the contract test into the standard `test/organisms/` bucket and removed the nonstandard `test/workflows/` location.
+
+## [0.38.1] - 2026-03-26
+
+### Technical
+- Added regression coverage for `work-on-task` done-task filtering contracts, including mixed done/non-done handling, all-done no-op behavior, and create-flow no hidden-spec/`ace-assign create` guard assertions.
+
+## [0.38.0] - 2026-03-26
+
+### Added
+- Added explicit done-task filtering rules to `assign/prepare` so `work-on-task` requests resolve refs first, skip `status: done` refs, continue mixed sets, and abort all-done sets before queue generation.
+- Added `record-demo` step to the assignment step catalog for recording and attaching terminal demos to PRs.
+- Added composition rules positioning `record-demo` between `push-to-remote` and `update-pr-desc`.
+- Added `record-demo` to the `implement-with-pr` recipe as an optional step.
+
+### Changed
+- Updated `assign/create` workflow guidance so Path B respects filtered taskrefs from prepare and skips hidden-spec render/`ace-assign create` when all requested refs are already done.
+- Updated usage docs with `work-on-task` prepare/create filtering behavior and no-assignment outcomes for all-done inputs.
+- Updated `work-on-task` preset with step 145 (`record-demo`) that reads demo scenarios from task specs, validates with dry-run, and records with proper fixture/sandbox patterns.
+
 ## [0.37.0] - 2026-03-23
 
 ### Changed

data/README.md

@@ -3,7 +3,8 @@
 
   Multi-step assignment execution with nesting, fork delegation, and inspectable traces.
 
-  <img src="../docs/brand/AgenticCodingEnvironment.Logo.S.png" alt="ACE Logo" width="480">
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
 
   <a href="https://rubygems.org/gems/ace-assign"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-assign.svg" /></a>
   <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
@@ -75,7 +76,7 @@ The easiest way to start is through [ace-overseer](../ace-overseer) -- define a
 
 ## Use Cases
 
-**Define assignments from presets** - pick a [preset](.ace-defaults/assign/presets/) like [`work-on-task`](.ace-defaults/assign/presets/work-on-task.yml) or `release-only`, pass parameters (task refs, packages), and [`ace-assign create`](docs/usage.md) expands it into a concrete step queue. Steps are defined in the [catalog](.ace-defaults/assign/catalog/steps/) (e.g., [`work-on-task.step.yml`](.ace-defaults/assign/catalog/steps/work-on-task.step.yml)) and ordered by [composition rules](.ace-defaults/assign/catalog/composition-rules.yml). Compose custom assignments with `/as-assign-compose`.
+**Define assignments from presets** - pick a [preset](.ace-defaults/assign/presets/) like [`work-on-task`](.ace-defaults/assign/presets/work-on-task.yml) or `release-only`, pass parameters (task refs, packages), and run `ace-assign create --task ...` or [`ace-assign create --yaml ...`](docs/usage.md) to expand them into a concrete step queue. Steps are defined in the [catalog](.ace-defaults/assign/catalog/steps/) (e.g., [`work-on-task.step.yml`](.ace-defaults/assign/catalog/steps/work-on-task.step.yml)) and ordered by [composition rules](.ace-defaults/assign/catalog/composition-rules.yml). Compose custom assignments with `/as-assign-compose`.
 
 **Run with orchestrator and fork agents** - use `/as-assign-drive` to walk through steps, forking long-running work (implementation, review, release) to isolated agent subprocesses with configurable [execution defaults](.ace-defaults/assign/config.yml). Forks can run sequentially or as parallel batches, each producing inspectable traces and session reports under `.ace-local/assign/`.
 

data/docs/getting-started.md

@@ -52,7 +52,14 @@ Create the assignment:
 
 
 ```bash
-ace-assign create job.yaml
+ace-assign create --yaml job.yaml
+```
+
+Or create directly from task refs with the default `work-on-task` preset:
+
+```bash
+ace-assign create --task t.xyz
+ace-assign create --task t.100,t.101 --preset work-on-task
 ```
 
 ## 2) Check status and execute work
@@ -70,11 +77,14 @@ Use `--message <file>` to keep reports explicit and reusable.
 
 
 ```bash
-ace-assign add fix-links --instructions "Fix broken docs links"
-ace-assign add verify-links --after 020 --child -i "Check all markdown links"
+ace-assign add --task t.xyz
+ace-assign add --step update-docs --after 020
+ace-assign add --step review-pr --after 100 --child
+ace-assign add --yaml .ace-local/assign/jobs/add-task-t.xyz.yml --after 010 --child
 ```
 
 Use `--child` to insert nested steps under a parent step.
+Use `--yaml` to insert multiple steps (including subtree expansions via `sub_steps`) from YAML.
 
 ## 4) Work with hierarchical steps
 
@@ -104,12 +114,13 @@ ace-assign finish --message report.md --assignment abc123@010.01
 
 | Command | Purpose |
 |---------|---------|
-| `ace-assign create job.yaml` | Create assignment from YAML |
+| `ace-assign create --yaml job.yaml` | Create assignment from YAML |
+| `ace-assign create --task t.xyz` | Create assignment from task refs |
 | `ace-assign status` | Show current queue |
 | `ace-assign start` | Start next workable step |
 | `ace-assign finish --message done.md` | Complete in-progress step |
 | `ace-assign fail --message "error"` | Mark current step failed |
-| `ace-assign add NAME -i "..."` | Insert new step dynamically |
+| `ace-assign add --step NAME` | Insert preset step dynamically |
 | `ace-assign retry 040` | Retry failed step as linked work |
 | `ace-assign fork-run --root 010.01` | Execute a subtree in forked context |
 

data/docs/handbook.md

@@ -15,6 +15,7 @@ Canonical skills and workflow instructions bundled with `ace-assign`.
 
 | Skill | What it does |
 |-------|---------------|
+| `as-assign-add-task` | Add a work-on-task subtree into a running assignment batch parent |
 | `as-assign-compose` | Compose a tailored assignment from catalog steps and composition rules |
 | `as-assign-create` | Create assignments from public workflow, with optional handoff to drive |
 | `as-assign-drive` | Drive active assignment execution step-by-step |
@@ -26,6 +27,7 @@ Canonical skills and workflow instructions bundled with `ace-assign`.
 
 | Protocol Path | Purpose | Invoked by |
 |---------------|---------|------------|
+| `wfi://assign/add-task` | Insert a task subtree into a running assignment using `ace-assign add --yaml` | `as-assign-add-task` |
 | `wfi://assign/compose` | Compose assignment definitions from cataloged steps | `as-assign-compose` |
 | `wfi://assign/create` | Create assignment and initialize queue from config | `as-assign-create` |
 | `wfi://assign/drive` | Execute active assignment loop with status/finish/fail transitions | `as-assign-drive` |

data/docs/usage.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-assign Usage Guide
 purpose: Complete command reference for ace-assign queue orchestration, hierarchy, and fork execution.
 ace-docs:
-  last-updated: 2026-03-22
-  last-checked: 2026-03-22
+  last-updated: 2026-03-26
+  last-checked: 2026-03-26
 ---
 
 # ace-assign Usage Guide
@@ -26,7 +26,7 @@ ace-assign finish --message report.md
 
 
 ```bash
-ace-assign create job.yaml
+ace-assign create --yaml job.yaml
 ace-assign status
 ace-assign finish --message step-010.md
 ace-assign status
@@ -58,21 +58,27 @@ Create child/sibling steps:
 
 
 ```bash
-ace-assign add setup-db --after 010 --child -i "Set up DB"
-ace-assign add hotfix --after 010 -i "Urgent fix"
+ace-assign add --step update-docs --after 020
+ace-assign add --step review-pr --after 100 --child
+ace-assign add --yaml .ace-local/assign/jobs/add-task.yml --after 010 --child
 ```
 
 ## Commands
 
-### `ace-assign create CONFIG`
+### `ace-assign create`
 
-Create a new assignment from a YAML file.
+Create a new assignment from YAML or from task refs expanded through an assignment preset.
 
 Options:
 
+- `--yaml FILE`
+- `--task, -t <taskref[,taskref...]>` (repeatable)
+- `--preset, -p NAME`
 - `--quiet, -q`
 - `--debug, -d`
 
+Exactly one mode is required: `--yaml` or `--task`.
+
 ### `ace-assign status`
 
 Show queue status for active or explicitly targeted assignment.
@@ -123,19 +129,24 @@ Options:
 - `--quiet, -q`
 - `--debug, -d`
 
-### `ace-assign add NAME`
+### `ace-assign add`
 
-Insert a new step dynamically.
+Insert new step(s) dynamically.
 
 Options:
 
-- `--instructions, -i TEXT`
+- `--yaml FILE`
+- `--step NAME[,NAME...]`
+- `--task TASKREF`
+- `--preset NAME`
 - `--after, -a NUMBER`
 - `--child, -c`
 - `--assignment <id>`
 - `--quiet, -q`
 - `--debug, -d`
 
+Exactly one mode is required: `--yaml`, `--step`, or `--task`.
+
 ### `ace-assign retry STEP_REF`
 
 Create a linked retry step for a failed step.
@@ -185,6 +196,17 @@ Options:
 
 ## Workflow Patterns
 
+### `work-on-task` Input Filtering (Prepare/Create Workflows)
+
+When using preset-backed assignment creation (`ace-assign create --task ...`, `/as-assign-prepare`, or `/as-assign-create`):
+
+- Requested refs are resolved first (single, comma list, range, pattern).
+- Terminal refs (`done`, `skipped`, `cancelled`) are skipped before queue expansion.
+- Mixed sets continue with remaining non-terminal refs and report skipped terminal refs.
+- If all requested refs are terminal, assignment creation stops with:
+  - `All requested tasks are already terminal (done/skipped/cancelled): <refs>`
+  - `No assignment created.`
+
 ### Scoped Subtree Execution
 
 

data/handbook/skills/as-assign-add-task/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: as-assign-add-task
+description: Add a work-on-task subtree into a running assignment batch parent
+# bundle: wfi://assign/add-task
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+- Bash(ace-assign:*)
+- Bash(ace-bundle:*)
+- Bash(ace-task:*)
+- Read
+- Write
+- AskUserQuestion
+argument-hint: "taskref [--parent STEP] [--assignment ID]"
+last_modified: 2026-03-26
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/add-task
+
+---
+
+Load and run `ace-bundle wfi://assign/add-task` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/workflow-instructions/assign/add-task.wf.md

@@ -0,0 +1,146 @@
+---
+doc-type: workflow
+title: Add Task To Assignment Workflow
+purpose: Insert a work-on-task subtree into a running assignment batch parent using ace-assign add --yaml
+ace-docs:
+  last-updated: 2026-03-26
+  last-checked: 2026-03-26
+---
+
+# Add Task To Assignment Workflow
+
+## Purpose
+
+Add one new task subtree to an existing assignment without editing step files manually.
+
+This workflow:
+1. Resolves the target assignment and parent step
+2. Validates task reference exists
+3. Renders a hidden YAML file under `.ace-local/assign/jobs/`
+4. Calls `ace-assign add --yaml <file> --after <parent> --child`
+
+## Supported Inputs
+
+```bash
+/as-assign-add-task t.xyz
+/as-assign-add-task t.xyz --parent 010
+/as-assign-add-task t.xyz --assignment abc123
+/as-assign-add-task t.xyz --assignment abc123 --parent 010
+```
+
+## Process
+
+### 1. Parse Input
+
+Required:
+- task reference (first positional argument)
+
+Optional:
+- `--assignment <id>`: explicit assignment target
+- `--parent <step-number>`: explicit parent step for insertion
+
+If task reference is missing, fail with usage guidance.
+
+### 2. Resolve Assignment
+
+- If `--assignment` is provided, use it for all assignment commands.
+- Otherwise use active assignment context.
+
+Run status to capture current queue state:
+
+```bash
+ace-assign status [--assignment <id>] --format json
+```
+
+### 3. Resolve Parent Step
+
+If `--parent` is provided:
+- Use it directly
+- Ensure it exists in assignment status output
+
+If `--parent` is not provided:
+1. Prefer a top-level step named `batch-tasks`
+2. Otherwise, choose a top-level step that has direct children where at least one child name starts with `work-on-`
+3. If no match exists, fail and instruct user to pass `--parent`
+
+### 4. Validate Task Reference
+
+Confirm task exists and is readable:
+
+```bash
+ace-task show <taskref>
+```
+
+If task lookup fails, stop and surface the CLI error.
+
+### 5. Render Hidden Batch Spec
+
+Create the hidden jobs directory if missing:
+
+```bash
+mkdir -p .ace-local/assign/jobs
+```
+
+Write a temporary YAML file:
+
+```bash
+.ace-local/assign/jobs/<timestamp>-add-task-<taskref>.yml
+```
+
+Template:
+
+```yaml
+steps:
+  - name: work-on-<taskref>
+    context: fork
+    workflow: wfi://task/work
+    instructions: |
+      Implement task <taskref> following project conventions.
+      When complete, mark the task as done.
+```
+
+Notes:
+- Do not hardcode `sub_steps` here.
+- `ace-assign add --yaml` resolves canonical child steps from `wfi://task/work` assign metadata at insertion time.
+- This keeps the inserted subtree aligned with workflow contract updates.
+
+### 6. Insert Subtree
+
+Run batch insertion:
+
+```bash
+ace-assign add --yaml .ace-local/assign/jobs/<timestamp>-add-task-<taskref>.yml --after <parent> --child [--assignment <id>]
+```
+
+### 7. Report Result
+
+Report:
+- Assignment ID
+- Parent step used
+- Hidden YAML path
+- Inserted step numbers from CLI output
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| Missing taskref | Fail with usage and example invocation |
+| No target assignment | Surface `ace-assign status` error |
+| Parent not found | Fail with "step not found" and suggest `--parent` |
+| Parent auto-detection failed | Fail with actionable message to pass `--parent` |
+| Task not found | Surface `ace-task show` error unchanged |
+| YAML render/write failure | Fail with concrete filesystem error |
+| `ace-assign add --yaml` fails | Surface CLI error unchanged |
+
+## Success Criteria
+
+- Workflow inserts a new work-on-task subtree under the selected parent in one command
+- Hidden YAML artifact is written under `.ace-local/assign/jobs/`
+- Parent selection is deterministic with clear fallback to explicit `--parent`
+- Output includes assignment, parent, and inserted step confirmation
+
+## Verification
+
+```bash
+ace-bundle wfi://assign/add-task
+```