Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 71 additions & 44 deletions meta/resources/planning-readme.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion meta/techniques/knowledge-base-search/load-domain-index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ metadata:

## Capability

Read the matching domain index file from `.engineering/resources/`.
Read the domain knowledge index matching a domain hint.

## Inputs

Expand Down
2 changes: 1 addition & 1 deletion meta/techniques/workflow-engine/TECHNIQUE.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Client walks use per-activity disposable workers via [dispatch-activity](./dispa

### resource-loading-via-tool

Resource refs returned in operation bodies (e.g., [planning-readme](../../resources/planning-readme.md)) are lightweight pointers. When `get_activity` includes a sibling `resources` map, reuse those bodies (or unchanged markers). Otherwise load via `get_resource { session_index, resource_id }`.
Resource refs returned in operation bodies (e.g. `planning-readme`) are lightweight pointers. When `get_activity` includes a sibling `resources` map, reuse those bodies (or unchanged markers). Otherwise load via `get_resource { session_index, resource_id }`.

### resource-section-or-whole

Expand Down
8 changes: 4 additions & 4 deletions meta/techniques/workflow-engine/create-readme.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
metadata:
version: 3.0.0
version: 3.1.0
---

## Capability
Expand Down Expand Up @@ -39,10 +39,10 @@ Full path to the created `README.md`

## Protocol

1. Load [Template](../../resources/planning-readme.md#template) from [planning-readme](../../resources/planning-readme.md).
1. Load [Template](../../resources/planning-readme.md#template).
2. Load the readme-seed profile named by `{seed_profile}`.
3. Populate the header (title, classifier from seed + `{entity_context}`, date, lifecycle Status), Executive Summary placeholder, and Links table (seed defaults merged with `{entity_context}` URLs when present).
4. Replace the Progress table body with the seed profile's Progress inventory (icons from [Status vocabulary](../../resources/planning-readme.md#status-vocabulary)). Insert any seed-declared append H2 sections after Solution Overview and before Progress.
3. Populate the header (title, classifier from seed + `{entity_context}`, date, lifecycle Status), Executive Summary placeholder, and Links table (seed defaults merged with `{entity_context}` URLs when present), each per its entry in [Rules](../../resources/planning-readme.md#rules).
4. Replace the Progress table body with the seed profile's Progress inventory rows as authored (icons from [Status vocabulary](../../resources/planning-readme.md#status-vocabulary)). Insert any seed-declared append H2 sections after Solution Overview and before Progress.
5. Apply the seed profile's mode-exclusion map using `{is_review_mode}` and/or `{operation_type}` when bound (else implement/create defaults on the profile), per [Status transition policy](../../resources/planning-readme.md#status-transition-policy).
6. Write the populated `README.md` to `{planning_folder_path}/README.md`, and return that location as `{created_readme}`.

Expand Down
32 changes: 22 additions & 10 deletions meta/techniques/workflow-engine/dispatch-activity.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
metadata:
version: 1.8.1
version: 1.10.0
---

## Capability
Expand Down Expand Up @@ -38,23 +38,38 @@ Opaque HMAC-signed trace token from the `next_activity` response `_meta.trace_to
## Protocol

1. **Progress in-progress:** When `{planning_folder_path}` is set, apply [sync-progress-status](./sync-progress-status.md) for the dispatch moment in [Progress Status call sites](../../resources/planning-readme.md#progress-status-call-sites) (`activity_id={activity_id}`; `{target_status}` from that row / [Status vocabulary](../../resources/planning-readme.md#status-vocabulary)). Transitions follow [Status transition policy](../../resources/planning-readme.md#status-transition-policy). Skip when no planning folder exists yet.
2. Call `next_activity { session_index, activity_id, step_manifest, usage? }`; capture `_meta.trace_token`.
- **`step_manifest`:** include a `step_manifest` array. Each entry is an object with two string fields: `step_id` (the literal step id from the activity definition's `steps[]`) and `output` (a short summary of what was produced). Omit `step_manifest` entirely if no steps were executed; do not pass an empty array or empty string.
- **`usage` (optional):** relay the harness-reported token usage for the activity the worker just completed — the figure the orchestrator reads from the worker's completion result (e.g. subagent token counts and cache/model fields when the harness surfaces them). Pass it on this transition call, keyed to the activity being exited. When the harness does not surface per-sub-agent usage, omit the param entirely — the run still completes and nothing is fabricated. The worker cannot self-measure; this populate step is orchestrator-only.
2. Call `next_activity { session_index, activity_id, step_manifest }`; capture `_meta.trace_token`.
- **`step_manifest`:** a dispatch whose activity ran steps carries one manifest entry per completed step — the server validates step completion against it, and reports a gap when it is absent.
- **Trace accumulate (required):** when `_meta.trace_token` is present, append it to `trace_tokens[]`. Tokens stay opaque — no routine per-activity `get_trace`. Live `_meta.validation` self-correct remains; do not resolve tokens mid-run (close-out resolve is [resolve-trace-at-close-out](#resolve-trace-at-close-out)).
3. Apply [compose-prompt](./compose-prompt.md) with `{agent_technique}` and `{state}` as substitutions (include `session_index`, `workflow_id`, `activity_id`, and worker `agent_id`).
4. Apply [harness-compat](../harness-compat/TECHNIQUE.md)::[spawn-agent](../harness-compat/spawn-agent.md) with the composed prompt; await the worker's envelope and return it unchanged as `{worker_result}`.
- If the worker does not return within the expected time, apply [harness-compat](../harness-compat/TECHNIQUE.md)::[continue-agent](../harness-compat/continue-agent.md) if it is still running; otherwise dispatch a fresh worker for the same `{activity_id}`.
5. On `activity_complete`, read `{worker_result.next_activity_id}` (and optionally `{worker_result.evaluated_condition}`) as the authoritative next-activity routing — the worker evaluated transitions via [finalize-activity](./finalize-activity.md).
- Before an orchestrator decision depends on a critical routing or path variable, apply [distrust-then-reconcile](#distrust-then-reconcile) (same stance as [worker-bag-takes-precedence](#worker-bag-takes-precedence)).
- Before an orchestrator decision depends on a critical routing or path variable, apply [distrust-then-reconcile](#distrust-then-reconcile).
- When the orchestrator observes **blocked** (worker/harness signal), apply [sync-progress-status](./sync-progress-status.md) for the blocked moment in [Progress Status call sites](../../resources/planning-readme.md#progress-status-call-sites) for `{activity_id}` before surfacing or retrying.
- When the path **skips / cancels** an activity without running it, apply [sync-progress-status](./sync-progress-status.md) for the path-skip / cancel moment in [Progress Status call sites](../../resources/planning-readme.md#progress-status-call-sites) for that activity's activity-prefix field.
- When the path **skips / cancels** an activity without running it, apply [sync-progress-status](./sync-progress-status.md) for the path-skip / cancel moment in [Progress Status call sites](../../resources/planning-readme.md#progress-status-call-sites) for that activity's rows.

## Rules

### account-every-dispatch

Every dispatch's harness-reported usage is recorded as it completes, with
`record_usage { session_index, activity, usage }` — one call per dispatch. That
covers the first worker, each `continue-agent`, each fresh worker dispatched after
a timeout, each resume after a checkpoint yield, and any dispatch made out of band.

Cost travels on its own call, so coverage follows the dispatches rather than the
graph: the terminal activity's own dispatches and anything after the final
transition are recorded like any other.

When the harness surfaces no figure, omit the call. A worker cannot self-measure,
so a missing entry must stay distinguishable from a measured zero; the client's
close-out cost path reconciles the entry count against the run's actual dispatch
count and reports any shortfall rather than hiding it.

### distrust-then-reconcile

Critical routing/path state read from `inspect_session` is cross-checked against the worker's own `activity_complete` envelope (`variables_changed` and related fields) and, when still uncertain, planning-folder evidence, before an orchestrator decision depends on it. On disagreement, the envelope governs; log the discrepancy.
Critical routing/path state read from `inspect_session` is cross-checked against the worker's own `activity_complete` envelope (`variables_changed` and related fields) and, when still uncertain, planning-folder evidence, before an orchestrator decision depends on it. On disagreement the envelope governs the worker holds ground truth from its own user interaction — and the discrepancy is logged.

### resolve-trace-at-close-out

Expand All @@ -76,6 +91,3 @@ Dispatched workers are fresh contexts with no prior deliveries. Leave a worker-d

If the worker reports fewer steps than the activity defines, or required checkpoints have no response, do NOT accept the partial result — resume the worker with explicit instructions to complete the missing items.

### worker-bag-takes-precedence

If the worker reports variable changes that conflict with orchestrator state, the worker values take precedence (the worker has ground truth from user interaction).
2 changes: 1 addition & 1 deletion meta/techniques/workflow-engine/finalize-activity.md
Original file line number Diff line number Diff line change
Expand Up @@ -69,4 +69,4 @@ One-line summary from evaluate-transition of which transition matched (`transiti

### no-readme-persist-on-worker

Planning-folder `README.md` Progress/Status sync and engineering commit/push are **not** worker duties. The orchestrator applies [commit-and-persist](./commit-and-persist.md) after `activity_complete`. Workers still report `{artifacts_produced}` in the envelope for activity evidence; Progress Status writes go through [sync-progress-status](./sync-progress-status.md) by activity-prefix field, not per envelope artifact entry.
Planning-folder `README.md` Progress/Status sync and engineering commit/push are **not** worker duties. The orchestrator applies [commit-and-persist](./commit-and-persist.md) after `activity_complete`. Workers still report `{artifacts_produced}` in the envelope for activity evidence; Progress Status writes go through [sync-progress-status](./sync-progress-status.md) by owning activity, not per envelope artifact entry.
7 changes: 2 additions & 5 deletions meta/techniques/workflow-engine/present-checkpoint-to-user.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
metadata:
version: 1.1.0
version: 1.2.0
---

## Capability
Expand All @@ -25,6 +25,7 @@ Load the active checkpoint's details and present them to the user.
2. Apply [verify-auto-advance-capability](#verify-auto-advance-capability) against the `present_checkpoint` payload (and the activity definition when needed) before treating the checkpoint as auto-advanceable.
3. Call `AskQuestion` with the checkpoint's message and `options[]`. This is the user's only opportunity to respond — it is MANDATORY for every checkpoint, including those with `autoAdvanceMs` set. If `autoAdvanceMs` is set (verified in step 2), configure `AskQuestion`'s timeout to that value with `defaultOption` as the timeout fallback; if the user does not respond within the timer, capture that as `auto_advance: true`. If the user responds, capture their `option_id`. When `autoAdvanceMs` / `defaultOption` are absent, do not auto-advance — wait for an explicit selection.
4. Record the resolved `{user_selection}` — the user's `option_id` and its `effects` (or `auto_advance` / `condition_not_met`).
5. Apply the effects carried on `{user_selection}` to internal state, then pass `{user_selection}` down to the orchestrator or worker awaiting the resolution.

## Rules

Expand All @@ -35,7 +36,3 @@ Load the active checkpoint's details and present them to the user.
### verify-auto-advance-capability

Before treating a checkpoint as auto-advanceable, confirm whether `defaultOption` and `autoAdvanceMs` are actually present on the `present_checkpoint` payload (or the checkpoint definition it mirrors). Do not assert auto-advance from memory, prior runs, or prose alone when those fields are absent. Capability is verified, not assumed.

### apply-effects-immediately

Apply the resolved effects to internal state on receipt, then pass them down to the orchestrator/worker.
2 changes: 1 addition & 1 deletion meta/techniques/workflow-engine/scan-saved-sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ metadata:

## Capability

Find saved client sessions matching a target workflow under `.engineering/artifacts/planning/`.
Find saved client sessions matching a target workflow, as resumable candidates.

## Inputs

Expand Down
24 changes: 17 additions & 7 deletions meta/techniques/workflow-engine/sync-progress-status.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
metadata:
version: 1.4.0
version: 1.5.0
---

## Capability
Expand All @@ -25,10 +25,18 @@ Status value to write — a canonical icon from [Status vocabulary](../../resour

*(optional)* Activity `artifactPrefix` (two-digit identity, e.g. `08`). When unbound, resolve from `{activity_id}` via the activity definition / filename. Required (directly or via `{activity_id}`) unless `{item_match}` alone uniquely identifies rows.

### seed_profile

Resource id of the workflow's readme-seed profile, which carries the [row-ownership map](../../resources/planning-readme.md#row-ownership-map) selection resolves through.

### item_match

*(optional)* Substring or bare filename matched against the Progress **item** field when only some rows for an activity should change. When unbound, all rows for `{artifact_prefix}` are candidates — selection per [Matching](../../resources/planning-readme.md#matching).

### delivered_artifact

*(optional)* Bare filename the selected rows' deliverable actually landed in, when it landed somewhere other than the row's seeded target. Unset when the deliverable is at the seeded target or does not exist.

### allow_overwrite_na

*(optional)* When true, permit writing `{target_status}` onto cells that [Status transition policy](../../resources/planning-readme.md#status-transition-policy) treats as overwrite-N/A eligible. Defaults follow that section.
Expand All @@ -43,12 +51,14 @@ Count of Progress status fields changed this apply.

1. Open `{planning_folder_path}/README.md` and locate the Progress surface per [Progress table](../../resources/planning-readme.md#progress-table).
2. Resolve `{artifact_prefix}`: use the bound value, else derive from `{activity_id}`'s server `artifactPrefix` (activity filename index).
3. Select candidate rows per [Matching](../../resources/planning-readme.md#matching) using `{artifact_prefix}` and, when bound, `{item_match}`.
4. For each candidate, set the status field to `{target_status}` per [Status transition policy](../../resources/planning-readme.md#status-transition-policy) (honour `{allow_overwrite_na}` when bound; otherwise use that section's defaults). Skip candidates the policy forbids.
5. Write status fields per [Status column](../../resources/planning-readme.md#status-column).
6. Ensure Progress chrome required by the resource is present per [Icon key](../../resources/planning-readme.md#icon-key).
7. Do not mutate the README lifecycle Status line — ownership per [Progress table](../../resources/planning-readme.md#progress-table).
8. Return `{rows_updated}`.
3. Load `{seed_profile}` and read the Item labels `{artifact_prefix}` owns from its [row-ownership map](../../resources/planning-readme.md#row-ownership-map).
4. Select candidate rows per [Matching](../../resources/planning-readme.md#matching) using those labels and, when bound, `{item_match}`.
5. For each candidate, set the status field to `{target_status}` per [Status transition policy](../../resources/planning-readme.md#status-transition-policy) (honour `{allow_overwrite_na}` when bound; otherwise use that section's defaults). Skip candidates the policy forbids.
6. Write status fields as icons from [Status vocabulary](../../resources/planning-readme.md#status-vocabulary).
7. Bring each written row's item field into line with what its status now asserts, per the same policy section: a cancelled/N/A write strips the item link to plain text; a complete write with `{delivered_artifact}` bound repoints the item link at that artifact. Leave the item label either way.
8. Ensure Progress chrome required by the resource is present per [Icon key](../../resources/planning-readme.md#icon-key).
9. Do not mutate the README lifecycle Status line — ownership per [Progress table](../../resources/planning-readme.md#progress-table).
10. Return `{rows_updated}`.

## Rules

Expand Down
2 changes: 1 addition & 1 deletion meta/techniques/workflow-engine/workflow-orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ Pass `{session_index}` on every authenticated tool call ([session-index-passes-o

### orchestrator-worker-boundaries

Honor [no-get-activity-from-orchestrator](./dispatch-activity.md#no-get-activity-from-orchestrator), [no-pre-load-techniques](./dispatch-activity.md#no-pre-load-techniques), [workers-need-full-delivery](./dispatch-activity.md#workers-need-full-delivery), [reject-partial-worker-result](./dispatch-activity.md#reject-partial-worker-result), and [worker-bag-takes-precedence](./dispatch-activity.md#worker-bag-takes-precedence).
Honor [no-get-activity-from-orchestrator](./dispatch-activity.md#no-get-activity-from-orchestrator), [no-pre-load-techniques](./dispatch-activity.md#no-pre-load-techniques), [workers-need-full-delivery](./dispatch-activity.md#workers-need-full-delivery), [reject-partial-worker-result](./dispatch-activity.md#reject-partial-worker-result), and [distrust-then-reconcile](./dispatch-activity.md#distrust-then-reconcile).

### resolve-trace-at-close-out

Expand Down
2 changes: 1 addition & 1 deletion requirements-refinement/techniques/analyze-source.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ Absolute path to the written analysis report.

### 5. Compile Analysis Report

- Write `{requirements_analysis}` to `{planning_folder_path}` using the [requirements-analysis-report](../resources/requirements-analysis-report.md) structure: source reference, new / updated / deprecated requirements, the [source coverage matrix](../resources/requirements-analysis-report.md#source-coverage-matrix), document updates required, quality issues, and implementation notes; capture its written location as `{requirements_analysis_path}`.
- Write `{requirements_analysis}` to `{planning_folder_path}` using the [Template](../resources/requirements-analysis-report.md#template) and its [Conventions](../resources/requirements-analysis-report.md#conventions): source reference, new / updated / deprecated requirements, the [source coverage matrix](../resources/requirements-analysis-report.md#source-coverage-matrix), document updates required, quality issues, and implementation notes; capture its written location as `{requirements_analysis_path}`.

## Rules

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
id: sub-crate-review
version: 1.10.0
version: 1.11.0
name: "Sub-Agent: Crate Deep Review"
description: Structured crate review for Group A sub-agents.
required: false
Expand All @@ -12,7 +12,10 @@ steps:
technique: extract-invariants
- kind: technique
id: apply-checklist
technique: apply-checklist
technique:
name: apply-checklist
inputs:
checklist_source: audit-template-reference#3-systematic-manual-review-strategies
- kind: technique
id: cross-function-comparison
technique:
Expand Down
Loading