ace-assign 0.37.0

data/handbook/guides/fork-context.g.md

@@ -0,0 +1,231 @@
+---
+doc-type: guide
+title: Fork Context Guide
+purpose: Explain fork context execution model, boundaries, and recovery patterns for ace-assign subtree delegation.
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# Fork Context Guide
+
+## Overview
+
+Fork context enables step files to run in isolated agent contexts using the Task tool. When a step has `context: fork` in its frontmatter, ace-assign outputs instructions for the orchestrating agent to execute the step via a subagent.
+
+For hierarchical split workflows, use **parent-only** fork markers:
+- Split parent step: `context: fork`
+- Child steps (`onboard-base`, `task-load`, `plan-task`, `work-on-task`, `verify-test`, `release-minor`): no `context: fork`
+- Runtime execution scope is controlled explicitly with `--assignment <id>@<root>`
+
+## When to Use Fork Context
+
+Use fork context when:
+
+- **Isolation is needed** - The step requires a clean agent context without previous conversation state
+- **Complex multi-step work** - The step involves substantial implementation that benefits from focused agent attention
+- **Independent execution** - The work can proceed without real-time interaction with the orchestrator
+
+Do **not** use fork context for:
+
+- Simple instructions that the orchestrator can execute directly
+- Steps that require continuous orchestrator oversight
+- Verification steps (see Anti-patterns below)
+
+## Step File Structure
+
+Fork context steps can use a rich structure with distinct sections:
+
+```markdown
+---
+status: pending
+context: fork
+---
+
+## Onboard
+
+Load context before starting work:
+- `ace-bundle project`
+- `ace-task show {{taskref}}`
+
+## Work
+
+[Main instructions for the forked agent]
+
+Implement the feature following project conventions.
+Run tests after each significant change.
+
+## Report
+
+Return structured summary:
+- **Task**: task ID and title
+- **Status**: completed | partial | blocked
+- **Changes**: files modified and what changed
+- **Commits**: commit hashes and messages created
+- **Issues**: problems encountered or deferred decisions
+```
+
+### Section Purposes
+
+| Section | Purpose |
+|---------|---------|
+| **Onboard** | Context loading commands to run before work |
+| **Work** | Main implementation instructions |
+| **Report** | Expected output format from the forked agent |
+
+## Execution Flow
+
+When `ace:assign-drive` (or manual orchestration) encounters a fork-enabled subtree:
+
+1. Runs `ace-assign status`
+2. Detects `Fork subtree detected (root: ...)` in output (outside fork scope)
+3. Delegates with `ace-assign fork-run --assignment <id>@<root>`
+4. Fork launcher executes `/as-assign-drive <id>@<root>` in a scoped process
+5. Scoped process advances only inside subtree
+6. Parent process resumes after subtree completion
+
+```
+ace:assign-drive loop
+  |
+  +-- ace-assign status
+  +-- Detects "Fork subtree detected (root: ...)"
+  +-- ace-assign fork-run --assignment <id>@<root>
+  +-- Forked /as-assign-drive <id>@<root>
+  +-- Subtree completes
+  +-- Parent loop continues
+```
+
+## Context Isolation Model
+
+Fork context provides:
+
+- **Clean slate** - No prior conversation affecting the subagent
+- **Focused task** - Single step with clear boundaries
+- **Structured output** - Report format ensures consistent results
+
+The orchestrating agent:
+
+- Maintains workflow state
+- Coordinates between steps
+- Processes subagent reports
+- Handles failures and retries
+
+## Recovery From Failed Fork Subtrees
+
+When a forked subtree fails, use **adaptive minimal-safe replay**:
+
+- Do not automatically replay the whole subtree.
+- Replay only the minimum set of steps needed to restore context confidence.
+- Always review prior subtree reports before choosing replay depth.
+
+Typical recovery shape:
+
+```
+failed step
+  -> recovery onboarding/report review
+  -> verify-test
+  -> retry failed or nearest affected step
+  -> resume remaining subtree steps
+```
+
+Recovery steps are inserted between the failed step and the next pending step (or appended if the failure happened at subtree end). This keeps history intact while avoiding unnecessary rework.
+
+## Anti-Patterns
+
+### Do Not Combine Work and Verify
+
+**Wrong:** Worker verifies its own work
+
+```yaml
+steps:
+  - name: implement-and-verify
+    context: fork
+    instructions: |
+      Implement the feature.
+      Then verify it works correctly.  # BAD: self-verification
+```
+
+**Right:** Separate steps for work and verification
+
+```yaml
+steps:
+  - name: implement
+    context: fork
+    instructions: |
+      Implement the feature.
+
+  - name: verify
+    # No context: fork - orchestrator runs this
+    instructions: |
+      Run ace-test to verify implementation.
+```
+
+### Do Not Use Fork for Simple Commands
+
+**Wrong:** Forking for trivial work
+
+```yaml
+steps:
+  - name: run-tests
+    context: fork
+    instructions: Run ace-test
+```
+
+**Right:** Orchestrator handles simple commands directly
+
+```yaml
+steps:
+  - name: run-tests
+    instructions: Run ace-test and report results
+```
+
+## Example Preset
+
+A typical work-on-task preset with fork context:
+
+```yaml
+name: work-on-task
+description: Work on a task with forked implementation
+
+steps:
+  - name: prepare
+    instructions:
+      - Load task context
+      - Review requirements
+
+  - name: implement
+    context: fork
+    instructions: |
+      ## Onboard
+      - ace-bundle project
+      - ace-task show {{taskref}}
+
+      ## Work
+      Implement the task following the specification.
+
+      ## Report
+      Return: status, changes, commits, issues
+
+  - name: verify
+    instructions:
+      - Run ace-test
+      - Verify all acceptance criteria
+```
+
+## Debugging
+
+To see how fork steps are processed:
+
+```bash
+# Check current step and context
+ace-assign status
+
+# Enable debug output
+ACE_DEBUG=1 ace-assign status
+```
+
+## Related
+
+- [ace-assign README](../../README.md) - Main documentation
+- [Work Queue Model](../workflow-instructions/drive-assignment.wf.md) - Assignment management
+- `ace-assign fork-run --root <step> --assignment <id>` - Prepare subtree-scoped fork session

data/handbook/skills/as-assign-compose/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: as-assign-compose
+description: Compose a tailored assignment from ace-assign catalog steps and composition rules (catalog-only)
+# bundle: wfi://assign/compose
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Glob
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: '"description of what you need" [--taskref value] [--taskrefs values]'
+last_modified: 2026-02-13
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/compose
+
+---
+
+Load and run `ace-bundle wfi://assign/compose` 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/skills/as-assign-create/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: as-assign-create
+description: Public assignment creation workflow (create, optionally handoff to drive with --run)
+# bundle: wfi://assign/create
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: "[instructions|preset [params] [--run]]"
+last_modified: 2026-02-11
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/create
+
+---
+
+Load and run `ace-bundle wfi://assign/create` 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/skills/as-assign-drive/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: as-assign-drive
+description: Drive agent execution through an active assignment
+# bundle: wfi://assign/drive
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - AskUserQuestion
+  - Skill
+argument-hint: "[assignment[@scope]]"
+last_modified: 2026-02-11
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/drive
+
+---
+
+Load and run `ace-bundle wfi://assign/drive` 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/skills/as-assign-prepare/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: as-assign-prepare
+description: Legacy/internal helper to prepare job.yaml from preset or informal instructions
+# bundle: wfi://assign/prepare
+# agent: general-purpose
+user-invocable: false
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Glob
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: "[preset-name] [--taskref value | --taskrefs values] [--output path]"
+last_modified: 2026-02-11
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/prepare
+
+---
+
+Load and run `ace-bundle wfi://assign/prepare` 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/skills/as-assign-recover-fork/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: as-assign-recover-fork
+description: Recover from fork-run failures in assignment execution
+user-invocable: true
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Bash(git:*)
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: "<assignment-id>@<fork-root>"
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/recover-fork
+
+---
+
+Load and run `ace-bundle wfi://assign/recover-fork` 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/skills/as-assign-run-in-batches/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: as-assign-run-in-batches
+description: Create a generic repeated-item fan-out assignment from template + explicit items
+# bundle: wfi://assign/run-in-batches
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: "\"instruction template\" --items item1,item2 [--sequential] [--max-parallel N] [--run]"
+last_modified: 2026-03-08
+source: ace-assign
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://assign/run-in-batches
+
+---
+
+Load and run `ace-bundle wfi://assign/run-in-batches` 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/skills/as-assign-start/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: as-assign-start
+description: Legacy compatibility orchestration that routes assignment startup through create then drive
+# bundle: wfi://assign/start
+# context: no-fork
+# agent: general-purpose
+user-invocable: false
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - AskUserQuestion
+argument-hint: "[instructions|preset [params] [--run]]"
+last_modified: 2026-03-09
+source: ace-assign
+skill:
+  kind: orchestration
+  execution:
+    workflow: wfi://assign/start
+assign:
+  source: wfi://assign/start
+---
+
+Load and run `ace-bundle wfi://assign/start` 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/compose.wf.md

@@ -0,0 +1,256 @@
+---
+doc-type: workflow
+title: Compose Assignment Workflow
+purpose: LLM-driven composition of assignments using canonical assign-capable skill metadata, phrase hints, and hard ordering rules
+ace-docs:
+  last-updated: 2026-03-18
+  last-checked: 2026-03-21
+---
+
+# Compose Assignment Workflow
+
+## Purpose
+
+Compose a tailored assignment by selecting steps from assign-capable canonical skills, applying composition rules, and using recipes as optional starting points.
+
+Boundary:
+- Compose resolves intent from user input + assign-capable canonical step data.
+- Compose is allowed to use step-level intent metadata (phrase hints) from canonicalized step entries.
+- Compose keeps skill-backed steps high-level. Runtime `ace-assign create` performs `assign.source` sub-step expansion.
+
+## Input Formats
+
+### 1. Natural Description
+
+```bash
+/as-assign-compose "implement task 148 with PR and 2 reviews"
+```
+
+### 2. Explicit Step List
+
+```bash
+/as-assign-compose "run tests, reorganize commits, push to remote"
+```
+
+### 3. Recipe Reference
+
+```bash
+/as-assign-compose implement-with-pr --taskref 148
+```
+
+## Process
+
+### 1. Load Canonical Assign-Capable Catalog
+
+Load public skill-backed step entries from canonical skills:
+
+```
+Canonical source: skill://* (workflow/orchestration skills with explicit assign metadata)
+Read: ace-assign/.ace-defaults/assign/catalog/composition-rules.yml
+Glob: ace-assign/.ace-defaults/assign/catalog/recipes/*.recipe.yml
+```
+
+Internal helper step templates under `ace-assign/.ace-defaults/assign/catalog/steps/*.step.yml`
+remain runtime support data for non-skill steps such as subtree orchestration helpers. They are not the
+authoritative source for public skill-backed step composition.
+
+For each step, read:
+- `name`, `skill`, `description`
+- `prerequisites`
+- `context`
+- `tags`
+- `intent.phrases` (if present)
+
+### 2. Understand Intent
+
+Extract from user input:
+- Goal and requested actions
+- Explicit requested order
+- Task refs (`--taskref`, `--taskrefs`, or inline text)
+- Constraints (include/exclude specific steps)
+
+Classify request shape:
+- **Explicit-step mode**: user lists concrete steps (comma-separated or sequenced)
+- **Goal mode**: user states high-level outcome
+
+### 3. Resolve Explicit Phrases to Steps
+
+Apply deterministic matching per explicit phrase in order:
+
+1. Exact step-name match (`push-to-remote`)
+2. Exact/contains match against `intent.phrases`
+3. Token overlap against step `name` + `description` + `intent.phrases`
+
+Normalization rules:
+- Lowercase and trim punctuation before matching
+- Normalize duplicates to one step unless repetition is explicitly requested
+- Keep first match as canonical step selection
+
+Unmatched phrase handling:
+- Stop composition
+- Return unmatched phrase and closest candidates (step name + matching hint)
+
+### 4. Optional Recipe Match
+
+Recipe matching is optional and advisory:
+
+- If user provides an exact recipe name, use it as starting scaffold.
+- If request is explicit-step mode, explicit steps are primary and recipe steps are secondary defaults.
+- If both conflict, explicit user steps win unless hard ordering/prerequisite rules require correction.
+
+### 5. Compose Step Sequence
+
+Precedence policy:
+
+1. **Explicit user steps** (primary)
+2. **Required prerequisites** from selected steps
+3. **Hard ordering rules** from `composition-rules.yml`
+4. **Recommended conditionals/defaults** as suggestions (advisory)
+
+Hard-rule corrections must be explainable by rule name.
+
+Skill-backed steps (for example `work-on-task`) remain high-level in composed YAML.
+Do not manually inline sub-steps from external skill/workflow files in compose.
+
+### 6. Validate
+
+Validate composed sequence:
+
+- Hard ordering satisfied (`before/after` rules)
+- Required prerequisites present
+- Pair constraints honored where applicable
+- No unresolved placeholders in rendered instructions
+
+If reordering occurred, record:
+- original explicit order
+- final order
+- rule name(s) causing adjustment
+
+### 7. Present Plan
+
+Show user the composed assignment:
+
+```
+Proposed: <assignment-name>
+
+Steps:
+  010: verify-test-suite
+  020: reorganize-commits
+  030: push-to-remote
+
+Ordering adjustments:
+  - none
+
+Suggestions (advisory):
+  [optional] add update-pr-desc
+```
+
+Include:
+- Step number + name + brief description
+- Fork context markers where applicable
+- Hard-rule reorder explanations
+- Advisory suggestions (clearly labeled optional)
+
+### 8. Refine (Optional)
+
+Use AskUserQuestion when needed:
+- Accept as-is
+- Add/remove step
+- Adjust review cycles
+- Provide custom changes
+
+Re-validate after edits.
+
+### 9. Generate job.yaml
+
+Generate job configuration compatible with `ace-assign create`:
+
+```yaml
+session:
+  name: <assignment-name>
+  description: <composed description>
+
+steps:
+  - name: verify-test-suite
+    workflow: wfi://test/verify-suite
+    instructions:
+      - Run package test verification.
+```
+
+Step mapping source of truth:
+- `name` from canonicalized step catalog entry
+- `workflow` from canonicalized step catalog entry
+- `context` from canonicalized step catalog entry (if set)
+- `instructions` as assignment overlay from catalog description + request-specific context
+
+### 10. Output Result
+
+Write job.yaml to task jobs directory (or custom `--output`) and report:
+
+```
+Assignment composed: <assignment-name>
+Job configuration: <path-to-job.yaml>
+
+Steps: N total
+  010: ...
+
+Composition validated: no ordering violations
+```
+
+## Error Handling
+
+| Scenario | Action |
+|----------|--------|
+| No matching recipe | Compose directly from steps |
+| Unmatched explicit phrase | Fail with unmatched phrase + closest candidates |
+| Missing required prerequisite | Insert required prerequisite and report why |
+| Ordering violation | Reorder by hard rule and report rule name |
+| Missing required parameter | Prompt user |
+| Empty step selection | Suggest minimum viable assignment |
+
+## Examples
+
+### Example 1: Explicit Steps
+
+```bash
+/as-assign-compose "run tests, reorganize commits, push to remote"
+```
+
+Expected core steps:
+- `verify-test-suite`, `reorganize-commits`, `push-to-remote`
+
+### Example 2: Explicit + Mainline Maintenance
+
+```bash
+/as-assign-compose "squash changelog, rebase with origin main, update pr description"
+```
+
+Expected core steps:
+- `squash-changelog`, `rebase-with-main`, `update-pr-desc`
+
+### Example 3: High-level Task Intent
+
+```bash
+/as-assign-compose "work on task 123 and create a PR"
+```
+
+Expected composed steps include high-level `work-on-task` and `create-pr`; runtime create expands task sub-steps via `assign.source`.
+
+## Success Criteria
+
+- [ ] Canonical assign-capable phrase hints are used for explicit-step matching
+- [ ] Common explicit requests resolve to stable steps
+- [ ] Explicit ordering is preserved unless hard rules require changes
+- [ ] Any reorder is explainable by named rule
+- [ ] Skill-backed step expansion remains runtime responsibility
+- [ ] Output job.yaml stays compatible with `ace-assign create`
+
+## Next Steps
+
+After job.yaml is created:
+
+```bash
+/as-assign-create <job.yaml>
+# or
+/as-assign-create "...intent..." --run
+```