ace-assign 0.37.0

checksums.yaml

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

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

@@ -0,0 +1,211 @@
+# Composition rules for ace-assign step ordering and pairing.
+# Used by the compose-assignment workflow to validate and suggest step sequences.
+
+ordering:
+  - rule: onboard-first
+    step: onboard
+    position: first
+
+  - rule: pr-before-review
+    before: create-pr
+    after: review-pr
+
+  - rule: review-before-apply
+    before: review-pr
+    after: apply-feedback
+
+  - rule: onboard-before-plan
+    before: onboard
+    after: plan-task
+    note: "Planning requires project context from onboarding"
+
+  - rule: plan-before-implementation
+    before: plan-task
+    after: work-on-task
+    note: "JIT planning should precede implementation"
+
+  - rule: implementation-before-pr
+    before: work-on-task
+    after: create-pr
+
+  - rule: mark-done-after-implementation
+    before: work-on-task
+    after: mark-task-done
+    note: "Mark task done after successful implementation"
+
+  - rule: release-after-implementation
+    before: work-on-task
+    after: release
+    note: "Release should follow implementation"
+
+  - rule: reorganize-before-push
+    before: reorganize-commits
+    after: push-to-remote
+    note: "Reorganize rewrites history, so must come before push"
+
+  - rule: squash-before-rebase
+    before: squash-changelog
+    after: rebase-with-main
+    note: "Consolidate changelog entries before rebasing to reduce conflict churn"
+
+  - rule: rebase-before-push
+    before: rebase-with-main
+    after: push-to-remote
+    note: "Rebase should happen before publishing commits to remote"
+
+  - rule: rebase-before-update-pr
+    before: rebase-with-main
+    after: update-pr-desc
+    note: "PR description should reflect post-rebase branch state"
+
+  - rule: push-before-update-pr
+    before: push-to-remote
+    after: update-pr-desc
+    note: "PR description should reflect pushed state"
+
+  - rule: release-before-pr
+    before: release
+    after: create-pr
+    note: "Initial release should happen before PR creation"
+
+  - rule: reflect-after-verify
+    before: verify-test-suite
+    after: reflect-and-refactor
+    note: "Reflection requires passing tests as baseline. The reflect-verify-cycle pair adds a second verify instance after refactoring — these are distinct step instances, not a cycle."
+
+  - rule: reflect-before-mark-done
+    before: reflect-and-refactor
+    after: mark-task-done
+    note: "Refactoring should complete before marking task done"
+
+  - rule: reflect-before-release
+    before: reflect-and-refactor
+    after: release
+    note: "Refactoring should complete before version release"
+
+  - rule: reflect-before-retro
+    before: reflect-and-refactor
+    after: create-retro
+    note: "Findings report feeds into retrospective as structured input"
+
+  - rule: retro-after-release
+    before: release
+    after: create-retro
+    note: "Retro captures learnings after all implementation and release work is complete"
+
+  - rule: retro-after-apply-feedback
+    before: apply-feedback
+    after: create-retro
+    note: "Retro should follow all feedback application in review cycles"
+
+  - rule: e2e-before-release
+    before: verify-e2e
+    after: release
+    note: "E2E must pass before bumping version — catch failures early"
+
+  - rule: update-docs-after-release
+    before: release
+    after: update-docs
+    note: "Docs should reference the new version number"
+
+  - rule: update-docs-before-pr
+    before: update-docs
+    after: create-pr
+    note: "Updated docs should be visible to PR reviewers"
+
+  - rule: e2e-after-verify
+    before: verify-test-suite
+    after: verify-e2e
+    note: "Unit tests should pass before E2E runs"
+
+pairs:
+  - name: review-apply-cycle
+    steps: [review-pr, apply-feedback]
+    pattern: sequential
+    note: "Reviews should be followed by feedback application"
+
+  - name: test-fix-cycle
+    steps: [verify-test-suite, fix-tests]
+    pattern: conditional
+    trigger: "test failures detected"
+
+  - name: reorganize-push-sequence
+    steps: [reorganize-commits, push-to-remote]
+    pattern: sequential
+    note: "Reorganize then push for clean remote history"
+
+  - name: apply-release-cycle
+    steps: [apply-feedback, release]
+    pattern: sequential
+    note: "Patch release after applying review feedback"
+
+  - name: reflect-verify-cycle
+    steps: [reflect-and-refactor, verify-test-suite]
+    pattern: conditional
+    trigger: "reflect-and-refactor produced refactoring commits"
+    note: "Re-verify after refactoring to catch regressions"
+
+  - name: reflect-fix-cycle
+    steps: [reflect-and-refactor, fix-tests]
+    pattern: conditional
+    trigger: "re-verification after refactoring finds failures"
+
+  - name: reflect-replan-cycle
+    steps: [reflect-and-refactor, work-on-task]
+    pattern: conditional
+    trigger: "demo validation failure or fundamental architectural misalignment"
+    cap: 1
+    note: "Re-plan produces 1-2 sub-tasks, then reflect runs once more (no further re-plan)"
+
+  - name: e2e-review-run-pair
+    steps: [verify-e2e]
+    pattern: sequential
+    note: "E2E review (coverage matrix) and targeted run are a single step with two steps"
+
+  - name: docs-update-validate-pair
+    steps: [update-docs]
+    pattern: sequential
+    note: "Doc update followed by validation in same step"
+
+conditional:
+  - when: "assignment includes work-on-task"
+    suggest: [plan-task, mark-task-done, reflect-and-refactor]
+    strength: recommended
+    overrides:
+      reflect-and-refactor: { strength: optional }
+    note: "JIT planning before, task completion after, and optional architecture reflection before shipping"
+
+  - when: "assignment includes work-on-task or fix-bug"
+    suggest: [verify-test-suite]
+    strength: required
+    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]
+    strength: recommended
+    note: "Public contract changes require E2E verification and doc updates"
+
+  - when: "task involves auth, security, or data handling"
+    suggest: [security-audit]
+    strength: optional
+
+  - when: "assignment includes review-pr and apply-feedback"
+    suggest: [release]
+    strength: recommended
+    note: "Patch release after each review cycle captures fixes"
+
+fork_context:
+  onboard_required: true
+  note: "Steps with fork context should include onboard instruction as first step"
+
+review_cycles:
+  default_count: 3
+  max_count: 5
+  preset_progression:
+    1: code-valid
+    2: code-fit
+    3: code-shine
+  focus_progression:
+    1: "Correctness: bugs, logic errors, missing functionality, broken contracts"
+    2: "Quality: performance, architecture, standards, test coverage"
+    3: "Polish: simplification, naming, documentation (non-blocking suggestions)"

data/.ace-defaults/assign/catalog/recipes/batch-tasks.recipe.yml

@@ -0,0 +1,44 @@
+name: batch-tasks
+description: Work on multiple tasks with PR, review cycles, and releases
+
+matches:
+  - "work on tasks *"
+  - "batch implement *"
+  - "multiple tasks"
+
+parameters:
+  taskrefs: { required: true, type: array }
+  review_cycles: { required: false, default: 3 }
+
+steps:
+  - name: onboard
+    required: true
+  - name: batch-parent
+    required: true
+    expansion:
+      foreach: taskrefs
+      child_step: work-on-task
+      child_context: fork
+    note: "Each child marks its task done after implementation"
+  - name: release
+    required: true
+    note: "Initial version bump (usually minor)"
+  - name: create-pr
+    required: true
+  - name: review-cycle
+    repeat: "{{review_cycles}}"
+    context: fork
+    sub_steps: [review-pr, apply-feedback, release, create-retro]
+    note: "Each cycle includes patch release after applying feedback"
+  - name: reorganize-commits
+    required: false
+  - name: push-to-remote
+    required: true
+  - name: update-pr-desc
+    required: false
+
+customization_hints:
+  - "Add create-pr after batch for consolidated review"
+  - "Add review cycles if changes need review"
+  - "Reduce batch size for complex tasks"
+  - "Skip reorganize-commits if history is already clean"

data/.ace-defaults/assign/catalog/recipes/documentation.recipe.yml

@@ -0,0 +1,35 @@
+name: documentation
+description: Create or update documentation with research and commit
+
+matches:
+  - "document *"
+  - "write docs for *"
+  - "update documentation"
+  - "documentation for *"
+
+parameters:
+  scope:
+    required: true
+    description: "Package, directory, or topic to document"
+  create_pr:
+    required: false
+    default: false
+    description: "Whether to create a PR for the documentation changes"
+
+steps:
+  - name: onboard
+    required: true
+  - name: research
+    required: true
+    instructions_template: "Research documentation gaps for {{scope}}. Identify outdated, missing, or incorrect documentation."
+  - name: work-on-task
+    required: true
+    instructions_template: "Create or update documentation for {{scope}}. Focus on clarity, accuracy, and completeness."
+  - name: commit
+    required: true
+
+customization_hints:
+  - "Add create-pr step if create_pr=true for documentation PRs"
+  - "Add lint step for markdown linting"
+  - "Add review-cycle for critical documentation"
+  - "Skip onboard if already in context"

data/.ace-defaults/assign/catalog/recipes/fix-and-review.recipe.yml

@@ -0,0 +1,32 @@
+name: fix-and-review
+description: Fix an issue, verify tests, and create a reviewed PR
+
+matches:
+  - "fix * and review"
+  - "bug fix with PR"
+  - "fix issue *"
+
+parameters:
+  taskref: { required: true }
+  review_cycles: { required: false, default: 1 }
+
+steps:
+  - name: onboard
+    required: true
+  - name: work-on-task
+    required: true
+    instructions_template: "Fix the issue described in task {{taskref}}."
+  - name: mark-task-done
+    required: false
+  - name: verify-test-suite
+    required: true
+  - name: create-pr
+    required: true
+  - name: review-cycle
+    repeat: "{{review_cycles}}"
+    sub_steps: [review-pr, apply-feedback]
+
+customization_hints:
+  - "Add fix-tests after verify-test-suite if failures found"
+  - "Add security-audit for security-related fixes"
+  - "Increase review cycles for critical fixes"

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

@@ -0,0 +1,29 @@
+name: implement-simple
+description: Implement a task with commit, no PR or review
+
+matches:
+  - "work on task *"
+  - "implement * simple"
+  - "quick task"
+
+parameters:
+  taskref: { required: true }
+
+steps:
+  - name: onboard
+    required: true
+  - name: plan-task
+    required: false
+    note: "JIT planning — can be skipped for trivial tasks"
+  - name: work-on-task
+    required: true
+    instructions_template: "Work on task {{taskref}}."
+  - name: mark-task-done
+    required: false
+  - name: commit
+    required: true
+
+customization_hints:
+  - "Skip onboard if already onboarded"
+  - "Add verify-test-suite before commit for complex changes"
+  - "Add lint after work-on-task for style enforcement"

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

@@ -0,0 +1,48 @@
+name: implement-with-pr
+description: Implement a task, create PR, and iterate through review cycles with releases
+
+matches:
+  - "work on task * and create PR"
+  - "implement * with review"
+  - "full task workflow"
+
+parameters:
+  taskref: { required: true }
+  review_cycles: { required: false, default: 3 }
+
+steps:
+  - name: onboard
+    required: true
+  - name: plan-task
+    required: false
+    note: "JIT planning — can be skipped for trivial tasks"
+  - name: work-on-task
+    required: true
+    instructions_template: "Work on task {{taskref}}."
+  - name: reflect-and-refactor
+    required: false
+    note: "Architecture reflection — skip for trivial tasks"
+  - name: mark-task-done
+    required: false
+  - name: release
+    required: true
+    note: "Initial version bump (usually minor)"
+  - name: create-pr
+    required: true
+  - name: review-cycle
+    repeat: "{{review_cycles}}"
+    context: fork
+    sub_steps: [review-pr, apply-feedback, release, create-retro]
+    note: "Each cycle uses preset_progression from composition rules (1: code-valid, 2: code-fit, 3: code-shine)"
+  - name: reorganize-commits
+    required: false
+  - name: push-to-remote
+    required: true
+  - name: update-pr-desc
+    required: false
+
+customization_hints:
+  - "Skip onboard if already onboarded in a previous assignment"
+  - "Add security-audit for security-sensitive changes"
+  - "Reduce review cycles to 1 for simple changes"
+  - "Skip reorganize-commits if commit history is already clean"

data/.ace-defaults/assign/catalog/recipes/release-only.recipe.yml

@@ -0,0 +1,34 @@
+name: release-only
+description: Version bump and changelog update without code changes
+
+matches:
+  - "release *"
+  - "bump version"
+  - "changelog update"
+  - "version bump"
+
+parameters:
+  version_type:
+    required: false
+    default: "patch"
+    description: "Version bump type (major, minor, or patch)"
+  push:
+    required: false
+    default: false
+    description: "Whether to push changes to remote"
+
+steps:
+  - name: onboard
+    required: false
+  - name: release
+    required: true
+    instructions_template: "Bump {{version_type}} version and update CHANGELOGs."
+  - name: commit
+    required: true
+
+customization_hints:
+  - "Skip onboard if already in context"
+  - "Add push-to-remote for immediate push after commit"
+  - "Use minor version for new features"
+  - "Use patch version for bug fixes"
+  - "Use major version for breaking changes"

data/.ace-defaults/assign/catalog/steps/apply-feedback.step.yml

@@ -0,0 +1,22 @@
+name: apply-feedback
+skill: as-review-apply-feedback
+description: Apply review feedback and commit improvements
+
+prerequisites:
+  - name: review-pr
+    strength: required
+    reason: "Must have review feedback to apply"
+
+produces: [code-changes, commits]
+consumes: [review-feedback]
+
+context:
+  default: null
+  reason: "Applying feedback needs access to working tree"
+
+when_to_skip:
+  - "Review found no actionable issues"
+  - "All feedback items are deferred"
+
+effort: light
+tags: [implementation, review-response]

data/.ace-defaults/assign/catalog/steps/commit.step.yml

@@ -0,0 +1,22 @@
+name: commit
+skill: as-git-commit
+description: Generate and create a commit with a descriptive message
+
+prerequisites:
+  - name: work-on-task
+    strength: recommended
+    reason: "Should have code changes to commit"
+
+produces: [commits]
+consumes: [code-changes]
+
+context:
+  default: null
+  reason: "Commit needs access to git state in main context"
+
+when_to_skip:
+  - "No uncommitted changes"
+  - "Changes were already committed by a previous step"
+
+effort: trivial
+tags: [git, versioning]

data/.ace-defaults/assign/catalog/steps/create-pr.step.yml

@@ -0,0 +1,28 @@
+name: create-pr
+skill: as-github-pr-create
+description: Create a pull request for the implemented changes
+intent:
+  phrases:
+    - "create pr"
+    - "create a pr"
+    - "open pr"
+    - "open pull request"
+
+prerequisites:
+  - name: work-on-task
+    strength: required
+    reason: "Must have code changes to create a PR"
+
+produces: [pull-request]
+consumes: [code-changes, commits]
+
+context:
+  default: null
+  reason: "PR creation needs access to git state in main context"
+
+when_to_skip:
+  - "PR already exists for this branch"
+  - "Changes don't warrant a PR (e.g., direct push allowed)"
+
+effort: light
+tags: [git, pr, publishing]

data/.ace-defaults/assign/catalog/steps/create-retro.step.yml

@@ -0,0 +1,22 @@
+name: create-retro
+skill: null
+description: Create a retrospective summarizing what was accomplished and lessons learned
+
+prerequisites:
+  - name: reflect-and-refactor
+    strength: recommended
+    reason: "Findings report enriches retrospective with architectural observations"
+
+produces: [retrospective]
+consumes: [findings-report, review-sessions]
+
+context:
+  default: null
+  reason: "Retro needs access to full assignment history"
+
+when_to_skip:
+  - "Assignment was trivial"
+  - "No significant learnings to capture"
+
+effort: trivial
+tags: [documentation, reflection]

data/.ace-defaults/assign/catalog/steps/fix-tests.step.yml

@@ -0,0 +1,22 @@
+name: fix-tests
+skill: null
+description: Fix failing tests identified during verification
+
+prerequisites:
+  - name: verify-test-suite
+    strength: recommended
+    reason: "Should know which tests are failing"
+
+produces: [code-changes, commits]
+consumes: [test-results]
+
+context:
+  default: null
+  reason: "Test fixing needs access to working tree and test runner"
+
+when_to_skip:
+  - "All tests are passing"
+  - "Failures are in unrelated tests"
+
+effort: medium
+tags: [testing, bug-fix]

data/.ace-defaults/assign/catalog/steps/lint.step.yml

@@ -0,0 +1,22 @@
+name: lint
+skill: null
+description: Run linters and fix style issues in changed files
+
+prerequisites:
+  - name: work-on-task
+    strength: recommended
+    reason: "Should have code changes to lint"
+
+produces: [code-changes]
+consumes: [code-changes]
+
+context:
+  default: null
+  reason: "Linting needs access to working tree"
+
+when_to_skip:
+  - "No code changes to lint"
+  - "Linting is handled by pre-commit hooks"
+
+effort: trivial
+tags: [quality, style]

data/.ace-defaults/assign/catalog/steps/mark-task-done.step.yml

@@ -0,0 +1,57 @@
+name: mark-task-done
+skill: null
+description: Mark task as done in ace-task after successful implementation
+workflow: wfi://task/update
+
+prerequisites:
+  - name: work-on-task
+    strength: required
+    reason: "Task must be implemented before marking done"
+
+produces: [task-status-update]
+consumes: [code-changes]
+
+context:
+  default: null
+  reason: "Needs access to ace-task CLI in main context"
+
+instructions: |
+  After completing implementation work, mark the task as done:
+
+  1. Run the status update command:
+     ```bash
+     ace-task update {{taskref}} --set status=done --move-to archive
+     ```
+
+  2. **VERIFY the status change** (do not skip):
+     ```bash
+     ace-task show {{taskref}}
+     ```
+     Confirm the output shows `status: done`. If it shows `in-progress` or another status, the update did not persist — investigate and retry.
+
+  **Why verification matters:** Skipping this step causes status drift where the orchestrator progress no longer matches ace-task's record. This creates confusion in future sessions and breaks progress reporting.
+
+  3. **Close parent tasks when all children are done:**
+     If the task has a parent (visible in `ace-task show` output), check whether all sibling subtasks are now done:
+     ```bash
+     ace-task show {{parent_taskref}}
+     ```
+     If all subtasks show `✓` (done), mark the parent done too:
+     ```bash
+     ace-task update {{parent_taskref}} --set status=done --move-to archive
+     ace-task show {{parent_taskref}}
+     ```
+     Repeat upward if the parent itself has a parent.
+
+  4. **Commit the task file moves:**
+     ```bash
+     ace-git-commit .ace-tasks/ -i "archive completed tasks"
+     ```
+     The `--move-to archive` flag relocates task files. This commit captures those moves.
+
+when_to_skip:
+  - "Task was already marked done (verified via ace-task show)"
+  - "Implementation was not completed"
+
+effort: trivial
+tags: [task-management, post-implementation]

data/.ace-defaults/assign/catalog/steps/onboard-base.step.yml

@@ -0,0 +1,19 @@
+name: onboard-base
+skill: null
+description: "Load base project context: run `ace-bundle project-base`"
+
+prerequisites: []
+
+produces: [project-base-context]
+consumes: []
+
+context:
+  default: null
+  reason: "Base onboarding needs access to the main conversation context"
+
+when_to_skip:
+  - "Already onboarded in a previous assignment"
+  - "Working in a context where project-base is already loaded"
+
+effort: light
+tags: [setup, context-loading]

data/.ace-defaults/assign/catalog/steps/onboard.step.yml

@@ -0,0 +1,19 @@
+name: onboard
+skill: as-onboard
+description: Load project context and understand the codebase
+
+prerequisites: []
+
+produces: [project-context]
+consumes: []
+
+context:
+  default: null
+  reason: "Onboarding needs access to the main conversation context"
+
+when_to_skip:
+  - "Already onboarded in a previous assignment"
+  - "Working in a context where project is already loaded"
+
+effort: light
+tags: [setup, context-loading]