feat(meta): operation-focused capability skills + skill_operations on activities#111
Open
feat(meta): operation-focused capability skills + skill_operations on activities#111
Conversation
… activities Migrate the meta workflow to the operation-focused model: - Add `workflow-engine` (capability) skill consolidating activity dispatch, transition evaluation, persistence hooks, and the full checkpoint flow (yield, present-to-user, respond, resume, bubble) as small linear operations. Replaces the role-based meta-orchestrator + workflow-orchestrator + activity-worker engine logic. - Refactor every cross-cutting meta skill to operation form: state-management (persist/restore), version-control (initialize-folder/commit-regular-files/ commit-submodule/identify-path-type), github-cli-protocol (per-PR/issue action), knowledge-base-search (catalog/chunks/broad), atlassian-operations (one operation per Atlassian MCP tool with inline tool refs — replaces the atlassian-tools resource), gitnexus-operations (per-tool ops with depth/risk table inline as operation prose). - Operation `tools` adopted Option-B layout: source name as key, array of tool names as value (e.g., workflow-server: [save_state, restore_state]). Provenance only — tool specs come from the MCP descriptions. - session-protocol becomes rules-only (every protocol bullet was an invariant, not a procedure). - agent-conduct gains `orchestrator-discipline` group as the canonical home for cross-orchestrator rules; legacy role skills retained for dual-support. - Renumber resources after deleting `04-atlassian-tools` (content inlined); `gitnexus-reference` retained at meta/03 for legacy work-package usage. - Activities switch from skills.primary/supporting to skill_operations[] (flat array of skill::op refs). Step-level operation references use the `operation` and `args` fields. Every operation ref string is quoted to keep TOON's `::` from being misparsed as key:value. - Meta workflow.toon migrates to skill_operations and bumps to v5.0.0; drops the legacy skills.primary (other workflows on legacy format keep theirs unchanged for dual-support). Test updates: get_skill / get_skills tests that asserted meta primary-skill behaviour now use work-package (which still has skills.primary) or assert the new no-body behaviour for migrated workflows. activity-loader test checks skill_operations on the migrated discover-session. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ss all workflows Per the operation-focused model, primary-skill definitions are no longer needed — get_workflow and get_activity bundle the resolved operations directly. Skill consolidation: - Merge state-management + session-protocol INTO workflow-engine (token mechanics, state persistence, engine traversal, transition evaluation, post-activity hooks, and the full checkpoint protocol all live in one capability skill). - Delete the legacy role-based skills (meta-orchestrator, activity-worker, workflow-orchestrator) — their content is now in workflow-engine + agent-conduct. - Final layout: 8 capability skills (workflow-engine, agent-conduct, version-control, github-cli-protocol, knowledge-base-search, atlassian-operations, gitnexus-operations, harness-compat) — monotonic 00-07. Schema-level rename: - activity.skill_operations → activity.operations - workflow.skill_operations → workflow.operations (symmetric naming with skill.operations; legacy skills.primary still valid). Client workflow migration: - Strip every `primary: meta/(meta-orchestrator|workflow-orchestrator|activity-worker)` reference across work-package, prism, prism-audit, prism-evaluate, prism-update, workflow-design, substrate-node-security-audit, cicd-pipeline-security-audit, work-packages, remediate-vuln (~95 files). - Activity skills blocks that had only this primary line are removed entirely; blocks with workflow-specific supporting skills retain just the supporting array. - Workflow.toon files drop their skills block when it referenced a meta role-based primary. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resources are scoped to the specific operations that need them: - workflow-engine top-level resources block removed. - workflow-engine::persist, ::restore, ::commit-and-persist declare resources: ["meta/workflow-state-format"] inline. - workflow-engine::dispatch-activity declares resources: ["meta/activity-worker-prompt"] inline. Resource refs now use the id form (meta/<id>) instead of the numeric index (meta/NN). Numeric indices still resolve for backward compatibility — the resource loader recognizes non-numeric refs and matches them against each resource's frontmatter `id:` field (or the filename's name segment after the NN- prefix). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…prose Drop redundant operation refs from activity operations[]: - agent-conduct::operational-discipline (auto-included via CORE_WORKER_OPS). - workflow-engine::dispatch-activity, present-checkpoint-to-user, respond-checkpoint, agent-conduct::checkpoint-discipline (in CORE_ORCHESTRATOR_OPS — already bundled at workflow level). - workflow-engine::token-is-opaque (a rule, auto-included when any workflow-engine op is touched). - Activity-level rules that duplicated workflow-engine rules. Split conditional logic out of step prose into formal `condition` constructs: - 00-discover-session: prepare-result split into record-match (when has_saved_state == true) and record-no-match (when false). - 01-initialize-session: start-or-adopt-session split into adopt-saved-session and create-fresh-session, mutually exclusive via has_saved_state condition. - 02-resolve-target: capture-target-path split — list-submodules and capture-submodule-target both gate on is_monorepo == true; the regular-repo branch is handled entirely by the repo-type-confirmed checkpoint's setVariable effects. - 03-dispatch-client-workflow: parse-orchestrator-result split into capture-checkpoint-yield (extract handle) and capture-workflow- complete (set client_workflow_completed). Both gate on client_workflow_completed == false (loop guard). Activity versions bumped (00→4.0.0, 01→2.0.0, 02→2.0.0, 03→2.0.0, 04→2.0.0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Add operations to absorb the logic that previously lived in step descriptions: workflow-engine (v3): - list-workflows: catalog retrieval (wraps list_workflows) - scan-saved-sessions: scan planning folders, filter by workflow id - adopt-session: start_session with a saved token - create-session: start_session with workflow_id + parent_session_token - compose-prompt: substitute placeholders in a prompt template resource - extract-checkpoint-handle: parse <checkpoint_yield> from agent output - handle-workflow-complete: apply final variables, set completion flag - verify-outcomes: compare outcome[] against state, return gaps - generate-summary: compose markdown session summary version-control (v4.2): - detect-repo-type: test -f .gitmodules → is_monorepo - list-submodules: read + parse .gitmodules Activity step descriptions now are short identifying labels — every step that wraps a discrete procedure carries an `operation:` reference plus `args`. Steps that remain prose-only (identify-target, match-session, record-match/no-match, detect-recovery, capture-submodule-target) describe agent reasoning that doesn't reduce to a single tool-driven operation. Activity versions bumped (00→5.0.0, 01→3.0.0, 02→3.0.0, 03→3.0.0, 04→3.0.0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Move the embedded reasoning logic out of the identify-target step's
prose and into three distinct workflow-engine operations:
- match-target-workflow(user_request, catalog) → { target_workflow_id, ambiguous }
- extract-identifying-context(user_request) → { context: { issue_number?, branch_name?, pr_number?, work_package? } }
- match-saved-session(context, candidates) → { match | null }
discover-session now invokes them as discrete steps:
1. list-available-workflows (catalog)
2. match-target (target_workflow_id, ambiguous)
3. extract-context (identifying context)
4. scan-planning-folders (candidates)
5. match-session (match | null)
6. record-match / record-no-match (variable bookkeeping; gated on has_saved_state)
Activity bumped to v6.0.0; workflow-engine bumped to v3.1.0.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ivities
Drop the structured operation/args/condition fields on steps in favour
of inline syntax embedded in description and a simple `when:` boolean
expression:
- description: "skill-id::operation-name(arg: {var}, arg: {var})"
- when: "var == value"
Step `name` is dropped — id + description are sufficient.
Activities now read line-by-line as imperative invocations:
- id: adopt-saved-session
description: "workflow-engine::adopt-session(saved_session_token: {saved_session_token})"
when: "has_saved_state == true"
vs. the prior structured form that took 6 lines for the same content.
All five meta activities migrated to the inline form. The structured
`condition` field stays for the doWhile loop guard (where the
ConditionSchema's structure is still useful) and for checkpoint-level
conditions.
Activity versions bumped (00→7.0.0, 01→4.0.0, 02→4.0.0, 03→4.0.0, 04→4.0.0).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The bootstrap protocol and the activity-worker / workflow-orchestrator prompt templates referenced the deprecated primary-skill flow and the old per-skill `_resources` array. Update each to match the current runtime: - bootstrap-protocol: get_workflow now returns a resolved operations bundle separated by `\n\n---\n\n`; agents follow operations and rules in the bundle. Add the activity schema to the pre-fetch list alongside workflow and skill. - activity-worker-prompt: get_activity carries the operations bundle ahead of the activity body. Per-operation `resources[]` arrays drive get_resource calls. Steps invoke operations via inline description syntax with optional `when:` guards. - workflow-orchestrator-prompt: same operations-bundle contract on get_workflow. Resume detection now relies on get_workflow_status's current_activity field plus start_session's `recovered: true` flag routing to workflow-engine::restore. Resource versions bumped (00→7.0.0, 01→3.0.0, 02→3.0.0). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirror the resources change: errors move from skill top-level to the specific operations they pertain to. Auto-included via the operation body when the operation is requested. - workflow-engine (v4): worker_timeout / worker_incomplete / state_desync → dispatch-activity; transition_ambiguous → evaluate-transition; invalid_checkpoint_handle → present-checkpoint-to-user + respond-checkpoint; stale_token → adopt-session. - version-control (v5): no_folder_path → initialize-folder; uncommitted_changes / destructive_operation → commit-regular-files; submodule-desync / stale-pointer → commit-submodule. - github-cli-protocol (v3): graphql-deprecation → update-pr-description. - knowledge-base-search (v3): no_index_for_domain → load-domain-index; no_mapping_for_term → broad-chunks-search; stale_index → chunks-search. - atlassian-operations (v3): missing_cloud_id / permission_denied → resolve-cloud-id; invalid_issue_type → create-jira-issue; transition_not_available → transition-jira-issue. - gitnexus-operations (v3): index_not_found / index_stale → verify-index; no_processes_found → query; symbol_ambiguous → context. Top-level skill.errors blocks deleted from each affected skill. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
"Worker-side:", "Workflow-orchestrator-side:", and "Meta-orchestrator- side:" prefixes added noise. The intended scope of each operation is already implicit from the activities that invoke it; descriptions read cleaner without the prefix tag. - yield-checkpoint: "Pause at a checkpoint and surface the handle" - resume-from-checkpoint: "Continue execution after the orchestrator resolves a checkpoint" - bubble-checkpoint-up: "Forward a worker's checkpoint to the parent (meta) orchestrator without resolving it" - present-checkpoint-to-user: "Load checkpoint details and present them to the user" - respond-checkpoint: "Send the user's selection back to the server" Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ates Scope: role-specific rules used to live at the workflow-engine skill top-level. Because resolveOperations auto-includes a touched skill's rules, a worker calling get_activity for an activity that uses yield-checkpoint would receive orchestrator-only rules (no-pre-load-skills, no-auto-resolution, etc.). Migrate role-specific rules per-operation so they only travel with the operations they constrain. workflow-engine (v5): - adopt-session: stale-token-recovery - dispatch-activity: step-manifest-required, reject-empty-checkpoints, no-get-activity-from-orchestrator, no-pre-load-skills, variable-mutation-source - commit-and-persist: persist-after-every-activity - yield-checkpoint: checkpoint-handle-distinct-from-session (no-continuation-after-yield removed — duplicates the procedure's STOP step) - resume-from-checkpoint: resume-checkpoint-uses-handle - bubble-checkpoint-up: no-direct-interaction - present-checkpoint-to-user: no-auto-resolution, apply-effects-immediately, checkpoint-handle-distinct-from-session - respond-checkpoint: no-option-hallucination - persist: no-direct-state-io Skill-level rules slimmed to truly universal ones: token-passes-on-each-call, use-most-recent-token, token-is-opaque, validation-warnings, resource-loading-via-tool. agent-conduct (v4): - operational-discipline updated for the new resource resolution model (per-operation resources, id-based refs, numeric refs as legacy backward-compat). Other meta skills (version-control, github-cli-protocol, knowledge-base-search, atlassian-operations, gitnexus-operations, harness-compat) audited — rules are accurate, not duplicates of operation prose, and not out of date. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
harness-compat had a different shape from the rest of the migrated meta skills — descriptions carried role/foreground prose, no procedure/output fields, and rules sat only at skill top-level. Restructured to match: - Each operation now has terse `description`, explicit `inputs`, `output`, and a one-line `procedure` that defers to the `harness` block for the implementation specifics. - Per-operation `rules`: foreground-always and token-in-prompt move onto spawn-agent and continue-agent (where they actually apply); resume-is-optimisation moves onto continue-agent; parallelism-is-optimisation moves onto spawn-concurrent. - Skill-level rules slimmed to the one truly skill-wide invariant: harness-independence (about how other skills reference these ops). - Verbose explanatory paragraphs in the original descriptions collapsed into the per-op rules. Bumped to v2.0.0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Drop the discrete `harness:` field from harness-compat operations. Per-harness implementation notes (cursor, cline, generic) now live in each operation's `prose` field as a small markdown table — the canonical home for structured-but-freeform reference content. The operation shape now matches the orthodox layout used elsewhere: description, inputs, output, procedure, rules, prose. Bumped to v3.0.0. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ove stale resource references Remove save_state/restore_state MCP tool references from workflow-engine operations (persist, restore) and replace with agent-managed file I/O. Delete resources 03 (gitnexus-reference) and 05 (workflow-state-format) which were inlined into skills or made obsolete by agent-managed persistence. Update resource README and docs to reflect current state. Made-with: Cursor
…ills These workflow-specific skills were referenced by step-level skill: annotations in design-philosophy, requirements-elicitation, research, implementation-analysis, plan-prepare, and implement activities but had no corresponding skill definition files. - reconcile-assumptions: iterative assumption classification and codebase-driven resolution with convergence tracking - classify-problem: problem classification, complexity assessment, and workflow path determination Made-with: Cursor
…supporting blocks Remove all legacy step-level skill: annotations from all 14 work-package activities and consolidate them into activity-level skills.supporting arrays. This eliminates 143 step-level references across: 01-start-work-package, 02-design-philosophy, 03-requirements-elicitation, 04-research, 05-implementation-analysis, 06-plan-prepare, 07-assumptions-review, 08-implement, 09-post-impl-review, 10-validate, 11-strategic-review, 12-submit-for-review, 13-complete, 14-codebase-comprehension. The skill loader now resolves supporting skills at the activity level rather than per-step. Made-with: Cursor
…oint resume After respond_checkpoint advances the token (clearing bcp), that fresh token was discarded — the operation only declared `effects` as output and the dispatch-client-workflow loop fed `client_session_token` (stale, captured at initialize-session) back into continue-agent. The resumed worker had only its own yield-time handle (bcp still set) and any subsequent get_activity / resume_checkpoint call hit either "Cannot resume: Checkpoint is still active" or HMAC mismatch when the agent reached for substitute tokens to recover. - respond-checkpoint now outputs both `effects` and `resumed_session_token` - resume-from-checkpoint input/rule/errors rewritten to point at the post-respond token (NOT the yield-time handle) - dispatch-client-workflow's respond-checkpoint step assigns resumed_session_token into client_session_token and threads it through the continue-orchestrator prompt with explicit guidance. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…resume
On resume, the orchestrator was executing activity steps in its own
context instead of dispatching workers — restored variables, prior
artifacts in the planning folder, and current_activity in the session
token created strong reasoning bias toward "I have everything; just
continue inline." The bootstrap step 4 wording ("do NOT restart from
initialActivity") reinforced that bias because it could be misread as
"don't go through dispatch logic" rather than the intended "use
current_activity instead of initialActivity."
- agent-conduct::orchestrator-discipline gains no-inline-on-resume,
making explicit that resume changes WHICH activity is dispatched, not
WHETHER one is dispatched.
- workflow-orchestrator-prompt step 4 rewritten to spell out that
dispatch-activity always runs, even on resume; the worker is
responsible for skipping already-completed steps based on artifact
presence.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The step-manifest-required rule said "completed step's id and output summary", which led orchestrators to build entries keyed by id instead of step_id (the actual schema field). Spell out the exact entry shape and tell orchestrators to omit the parameter — not pass [] or "" — when no steps ran. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-advance Orchestrators were observed calling present_checkpoint, narrating "I'll wait 30s for auto-advance," and then resolving without ever giving the user an interactive prompt. Root cause: the present-checkpoint-to-user procedure had a forked branch that told orchestrators to use Shell sleep instead of AskQuestion for autoAdvanceMs checkpoints — which gave the user no way to respond during the wait. Changes: - Procedure step 2 collapses to a single path: always call AskQuestion. When autoAdvanceMs is set, configure AskQuestion's timeout to that value with defaultOption as the timeout fallback. The auto-advance branch is a *fallback for an unanswered prompt*, not a substitute for presenting one. - no-auto-resolution rule rewritten to forbid sleep + auto_advance shortcuts and call out justifications based on prior user input or "obvious" defaults. - New present-before-any-resolution rule: every resolution path (option_id, auto_advance, condition_not_met) must be preceded by an AskQuestion. present_checkpoint returning data is not presenting. - Drop Shell from the operation's tool list — no longer used. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…fields
Saved state files were duplicating workflowId/workflowVersion/currentActivity/
agentId/parentWorkflow at the envelope level even though the session token
already carries all of them (wf, v, act, aid, psid/pwf/pact/pv). They were
also writing currentStep (= completedActivities.length) and updatedAt
(= savedAt) — both derivable.
Changes:
- persist: file is workflow-state.json (was vague .toon mention); fixes the
filename mismatch with what agents actually produce. Procedure spells out
the required envelope { stateVersion, savedAt, startedAt, sessionToken,
state } and the slim state shape, with an inline JSON example.
- restore: reads .json, explicitly defers workflowId/version/currentActivity/
agentId/parent context to the token decode rather than the envelope.
- New rules:
no-token-duplication: don't write fields already in the token
no-derived-fields: don't write currentStep / updatedAt
omit-empty-collections: skip empty maps/arrays
variables-canonical-home: domain state lives only in state.variables
- state-format rule tightened.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The ensure-changes-folder-entry step said only "(same issue/ticket id in
the name or clearly linked content)" — too loose to guarantee CI
check-changes passes. The matching skill rule asked the worker to
'gh search issues' for a matching issue even though issue_number,
issue_url, and issue_platform are already captured in start-work-package
and live in state.variables.
Both the activity step description and the changes-folder skill rule now:
- Use the captured variables (no re-search) when issue_platform=github
- Require a 'Closes: #{issue_number}' or 'Fixes: #{issue_number}' line
in the fragment body (or the full {issue_url} form when siblings use
that style)
- For issue_platform=jira, search for a paired GitHub tracker; warn the
user about CI check-changes if none exists.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…w-engine The "commit after each activity" rule was split across three skills with inconsistent scope: version-control declared it (engineering artifacts only), agent-conduct's automatic-transitions repeated the framing, and the commit-and-persist op only acted on engineering artifacts. Source-side changes under target_path had no orchestrator-level guarantee of being committed before transitioning. This consolidates the invariant in workflow-engine, where it belongs: - 00-workflow-engine.toon: commit-and-persist now takes target_path, runs version-control::commit-submodule first when target_path is dirty, then commit-regular-files for engineering artifacts, then persist. Canonical commit-after-activity rule covers both scopes. - 01-agent-conduct.toon: automatic-transitions stripped of the "and artifacts are committed" clause — purely behavioural now (no pause for user confirmation between activities). - 02-version-control.toon: commit-after-activity rule removed; skill description clarifies it owns commit mechanics/hygiene only, not activity-lifecycle invariants. - skills/README.md: rules table reflects the new ownership. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
PR creation now self-assigns to the current GitHub user and is followed by a new link-pr-to-ticket step that records the PR reference back on the issue via the platform's native PR linkage (Jira Development panel + comment fallback, or GitHub timeline cross-reference). The in-progress transition continues to be handled by activate-issue. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…rce budget
Cargo invocations from validate-build, implement-task, and
finalize-documentation could OOM/hang the host on memory-constrained
machines because they expanded to bare `cargo ...` with no parallelism
caps and no SKIP_WASM_BUILD. Substrate workspaces compounded this:
substrate-wasm-builder runs from build.rs even on `cargo check`, and
default rustc parallelism = nproc easily exceeds 30 GiB of RAM.
This adds skill 24 cargo-operations, an operation-oriented skill
modelled on meta/skills/06-gitnexus-operations and 03-github-cli-protocol.
One operation per cargo subcommand used by the workflow (check, test,
build-dev, build-release, clippy, fmt-check, fmt-fix, doc), each with
the resource budget inlined in the procedure:
- nice -n 19 (CPU yield)
- CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} (rustc parallelism cap)
- RUST_TEST_THREADS=${RUST_TEST_THREADS:-4} (test parallelism cap)
- SKIP_WASM_BUILD=1 for non-release commands (skip nested wasm rustc)
build-release deliberately omits SKIP_WASM_BUILD so the runtime wasm
artifact is still produced. Defaults assume <=32 GiB RAM and <=16 cores;
override caps via env on larger hosts.
Existing call sites now reference operations instead of inlining
wrappers:
- skills/16-validate-build.toon (1.2.0 -> 1.3.0): run-tests, verify-build,
check-format, check-lint route through cargo-operations.
- skills/10-implement-task.toon (2.0.0 -> 2.1.0): verify-locally uses
cargo-operations.check / .test with -p <crate> for the inner loop.
- skills/17-finalize-documentation.toon (1.1.0 -> 1.2.0): tool-usage
references cargo-operations.doc.
- activities/10-validate.toon (2.5.1 -> 2.5.2): check-format references
cargo-operations.fmt-check.
- skills/README.md: row 24 added, count bumped 24 -> 25.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…w cargo from delegation prose The previous commit (bbb4ca7) added cargo-operations and updated four sibling skills/activities to "invoke cargo-operations.X" — but the new skill was not listed in any activity's supporting[] block, so the runtime never loaded it. The agent had no awareness of the operations and continued spawning bare `cargo ...` shell commands, defeating the resource budget entirely. Two corrections: 1. Add cargo-operations to supporting[] of every activity that hosts a skill which delegates to it: - activities/08-implement.toon (2.6.2 -> 2.6.3): supporting[5] -> [6] - activities/10-validate.toon (2.5.2 -> 2.5.3): supporting[2] -> [3] - activities/13-complete.toon (1.3.0 -> 1.3.1): supporting[4] -> [5] This makes the runtime load the operations alongside the parent skills (validate-build, implement-task, finalize-documentation). 2. Strip every raw `cargo X` shell command from delegation prose. The prior wording said things like "invoke cargo-operations.test ... do NOT call `cargo test` directly" — embedding the very command we want the agent to avoid, which is the wrong cue. The prose now references only the operation (cargo-operations.test, .check, .build-release, .clippy, .fmt-check, .doc) and explicitly states each delegating skill "does not invoke cargo directly": - skills/16-validate-build.toon (1.3.0 -> 1.4.0): description and all four protocol steps rewritten; precondition added that loads cargo-operations via get_skill before any cargo-using step runs; resource-budget rule renamed to delegate-to-cargo-operations and reframed as a delegation rule. - skills/10-implement-task.toon (2.1.0 -> 2.1.1): verify-locally prose stripped of raw cargo. - skills/17-finalize-documentation.toon (1.2.0 -> 1.2.1): tool-usage prose stripped of raw cargo. - activities/10-validate.toon: check-format step description stripped of raw cargo. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ness-recovery to start_session only
A work-package resume failed with HMAC signature verification when the
orchestrator called next_activity with a saved disk token. Root cause:
the orchestrator's prior start_session call passed the saved token under
a non-existent key (saved_session_token) instead of the canonical
session_token parameter. The MCP schema silently stripped the unknown
key, the server took the fresh-session-with-parent branch, and the
saved state was never adopted. Downstream calls then re-used the literal
saved token, which next_activity verifies strictly with no recovery.
Two trigger conditions converged:
1. workflow-engine ops described start_session calls as JS object
literals with shorthand variable references — e.g.,
start_session({ session_token: saved_session_token, ... }) — which
reads to an LLM as a key named saved_session_token rather than a
variable bound to the session_token parameter. The variable name
differs from the parameter name, so the misreading silently produced
a wrong call.
2. The skill had no rule constraining where HMAC staleness recovery
could occur, leaving it implicit that next_activity might also
recover (it does not).
Changes:
- adopt-session, create-session, restore, handle-sub-workflow procedures
rewritten in plain English: each step names every MCP parameter
explicitly and binds the corresponding workflow VARIABLE to it, with
a "do NOT pass" list for keys that cause silent misroutes (notably
the saved_session_token variable name).
- adopt-session error catalogue gains strict_param_violation so future
misuse surfaces a clear recovery hint rather than a fresh-session.
- Three new top-level skill rules:
- staleness-recovery-only-via-start-session: codifies the policy that
no other workflow tool performs HMAC re-signing, and that resumes
must always pass through start_session first.
- start-session-strict-params: enumerates the four valid parameter
keys (workflow_id, parent_session_token, session_token, agent_id)
and reminds that workflow variable names sharing a parameter
shorthand must still be bound to the canonical parameter.
- parameter-vs-variable: general guidance separating workflow
variable namespaces from MCP parameter namespaces.
- Bootstrap orchestrator prompt (resource 02) rewritten to bind
{session_token} to the canonical session_token parameter and
explicitly forbid the saved_session_token invention.
Pairs with a strict-schema change in the workflow-server repo
(src/tools/resource-tools.ts) that converts start_session to
.registerTool with z.object(shape).strict(), so unknown keys now fail
with Input validation error: ... unrecognized_keys instead of being
silently dropped.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…t validate-build orchestration from cargo-operations execution
The validate activity duplicated validate-build's protocol: the activity's
steps[] paraphrased the same run-tests/verify-build/check-format/check-lint
flow that the skill's protocol[] already described. With cargo execution
also living in cargo-operations, the same logic was authored in three
places, drifting between them and producing the validate/cargo-operations
wiring failures observed earlier in this branch.
This refactor adopts the operation-call pattern used by the meta workflow's
discover-session and initialize-session activities: the activity declares
the operations[] it consumes, each step's description is an explicit
operation call, and the runtime resolves skills via the skill::operation
references. The legacy skills.supporting block (still typed as Optional
in src/schema/activity.schema.ts but marked LEGACY) is removed.
Activity (activities/10-validate.toon, 2.5.3 -> 3.0.0):
- operations[8] declared up front: cargo-operations::test, ::check,
::build-release, ::fmt-check, ::clippy plus validate-build::analyze-failure,
::apply-fix, ::aggregate-results.
- Each cargo step is now an explicit op call —
cargo-operations::test(scope: '--workspace'),
cargo-operations::check(scope: '--workspace'),
cargo-operations::fmt-check(scope: '--all'),
cargo-operations::clippy(scope: '--workspace') — guarded with
when: project_type == 'rust-substrate'.
- New aggregate-results step calls validate-build::aggregate-results
binding the cargo-op outputs (test_status, check_status, fmt_status,
clippy_status) to its inputs.
- The fix-revalidate-cycle loop's analyze-failure / apply-fix steps are
now operation calls into validate-build::analyze-failure and ::apply-fix.
- The signature-scan step stays prose; manage-git is not yet
operation-oriented and is out of scope here.
Skill validate-build (skills/16-validate-build.toon, 1.4.0 -> 2.0.0):
- Removed the duplicated protocol blocks (run-tests, verify-build,
check-format, check-lint, fix-failures). Cargo execution belongs
entirely to cargo-operations.
- Operation-oriented: three operations — analyze-failure (classify a
failed check, propose a fix_strategy), apply-fix (execute the strategy
via harness Edit/Write or cargo-operations::fmt-fix), and
aggregate-results (combine per-check outcomes into a single
validation_results envelope).
- New rule no-cargo-here codifies the boundary: this skill never invokes
cargo or describes cargo invocations; it operates on the OUTPUTS of
cargo-operations operations.
Skill cargo-operations (skills/24-cargo-operations.toon, 1.0.0 -> 1.1.0):
- Added output[] declarations on clippy (clippy_status, lint_diagnostics)
and fmt-check (fmt_status, fmt_diff_summary) so the activity's
{clippy_status} / {fmt_status} variable bindings populate.
Skill implement-task (skills/10-implement-task.toon):
- verify-locally simplified by upstream edit — drops the
cargo-operations call, leaving 'Check for obvious regressions in
affected code'. write-code's TDD reference deduplicated to a single
bullet pointing at resource 23.
skills/README.md: row 16 updated to reflect validate-build's narrower,
analysis/aggregation-only capability.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…st the schema scripts/validate-workflow-toon.ts surfaced two count-tag mismatches that prevented the affected skill files from parsing. The TOON decoder treats `name[N]:` as a hard contract on the number of array items, so a stale count silently breaks the skill at load time even though the content is correct. - skills/10-implement-task.toon: write-code[4] -> write-code[3]. A prior edit reduced the bullet list from 4 to 3 (deduplicated TDD references) without updating the count tag. - skills/classify-problem.toon: assess-complexity.procedure[3] -> [4] and determine-path.procedure[1] -> [3]. Pre-existing miscounts in e09cb9d that were never exercised until this validation pass. Both work-package and meta now pass scripts/validate-workflow-toon.ts end-to-end (workflow.toon + all activities + all skills). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…sts step
The implement activity's task-cycle loop had a run-tests step with no
description and a supporting list missing cargo-operations. With no
operation call to bind to and the cargo-operations skill not loaded,
the agent improvised by spawning bare cargo test, which bypasses the
resource budget and hangs the host on memory-constrained machines.
Two corrections:
- skills.supporting now lists cargo-operations alongside the existing
five entries (count tag was already [6] but the list was 5 items —
cargo-operations had been dropped earlier; the count is now correct).
- task-cycle.run-tests step description set to the explicit operation
call: cargo-operations::test(scope: '-p {current_task.crate}').
Per-task scope follows cargo-operations' scope-narrow-then-wide rule
for inner TDD loops.
Description text is intentionally minimal — operation-call form only.
Cargo execution semantics, the resource budget, and scope-fallback
guidance live inside cargo-operations and must not leak into the
calling activity's step descriptions.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The nice -n 19 bullet was removed in 8fe943a (deduplicated against cargo-operations::resource-budget) but the [4] count was not updated, causing the TOON loader to reject the skill ("Expected 4 list array items, but got 3"). Drop to [3] to match the remaining bullets and restore skill-loader.test.ts > should load a meta skill directly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Consolidates state persistence, parallelizes validation, tightens
compliance gates, and removes a class of worker-lifecycle bugs. Each
edit lives in the single owning skill or activity that already governs
the concern — no prose duplication across files.
meta/skills/00-workflow-engine.toon
- commit-and-persist now runs persist BETWEEN the source commit and
the engineering commit, so workflow-state.json rides along in one
engineering commit instead of producing a separate state-persist
commit per activity.
- persist splits the on-disk envelope: workflow-state.json holds
slowly-changing variables/history; the HMAC-signed token moves to
a sibling .session-token file. Eliminates token noise from state
diffs in code review.
- restore reads the sibling token first, with a legacy fallback for
older planning folders that still embed sessionToken inside
workflow-state.json.
meta/skills/02-version-control.toon
- All commits now use 'git commit -s' (DCO sign-off by default).
- commit-submodule reads the submodule's AGENTS.md before committing
and strips Co-Authored-By or other forbidden trailers when the
policy disallows them.
- New rules: dco-sign-off, respect-submodule-agents.
work-package/skills/24-cargo-operations.toon
- New rule foreground-only: cargo MUST run synchronously in the
caller's foreground; never run_in_background inside a worker
(worker exit kills the build process group).
- New operation preflight: probes toolchain prerequisites (protoc,
openssl, pkg-config) so validate fails fast instead of mid-compile.
- New operation run-suite: runs check/clippy/test/fmt-check
concurrently against one scope and emits a single
validation_results envelope. Replaces the four serial cargo steps
in the validate activity.
work-package/skills/14-manage-artifacts.toon
- New operation verify-readme-conforms: diffs the planning folder
README against resource 01 and emits structured drift findings.
work-package/activities/10-validate.toon
- Steps collapsed from 10 to 7. preflight + run-suite replace the
four serial cargo invocations and the legacy aggregate-results
bridge.
- fix-revalidate-cycle's revalidate step now re-runs run-suite as a
single atomic re-validation.
work-package/activities/11-strategic-review.toon
- New step verify-readme calls manage-artifacts::verify-readme-conforms
so README template drift is caught here instead of at PR review.
- New step verify-change-fragment validates that the changes/
fragment references the captured issue_url; missing reference
blocks the activity instead of deferring to the human reviewer.
- analyze-strategic-findings produces strategic_findings_summary,
interpolated into the review-findings checkpoint message so the
user sees findings inline with the options.
- context_to_preserve grows to include the new variables.
work-package/activities/01-start-work-package.toon
- create-pr now sets pr_exists=true after creating a draft PR, fixing
the variable drift that left pr_exists=false through the entire
downstream flow.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Meta workflow refactor that exercises the operation-focused model introduced by the companion server PR (#110). Migrates every cross-cutting meta skill to operations format, consolidates the role-based meta-orchestrator + workflow-orchestrator + activity-worker engine logic into a single
workflow-enginecapability skill, and rewrites all five meta activities to useskill_operations[]+step.operationinstead of legacyskills.primary+step.skill.Depends on #110 for schema, loader, and tool support. Without it, the new constructs do not load.
Key changes
New capability skill
workflow-engine— operations:dispatch-activity,evaluate-transition,commit-and-persist,handle-sub-workflow,finalize-activity,yield-checkpoint,resume-from-checkpoint,bubble-checkpoint-up,present-checkpoint-to-user,respond-checkpoint. Each operation is a small linear procedure invoking a small set of MCP / harness / shell tools.Migrated capability skills
session-protocol— protocol bullets converted to rules (every entry was an invariant, not a procedure).state-management— operationspersist,restore.version-control— operationsinitialize-folder,commit-regular-files,commit-submodule,identify-path-type.github-cli-protocol— operations per PR/issue action with inlinegh apiinvocations.knowledge-base-search— operationsload-domain-index,catalog-search,chunks-search,broad-chunks-search.atlassian-operations— one operation per Atlassian MCP tool with the tool reference inline. Replaces the deletedatlassian-toolsresource.gitnexus-operations— operationsverify-index,query,context,impact,rename,detect-changes,cypher,read-process,read-cluster. Depth/risk table inlined as theimpactoperation'sprose. Thegitnexus-referenceresource is retained for legacy work-package usage.Operation
toolslayoutSource-keyed map → array of tool names (provenance only):
agent-conduct
Gains
orchestrator-disciplinegroup — canonical home for cross-orchestrator rules referenced by core-ops.Activities migrated
00-discover-session,01-initialize-session,02-resolve-target,03-dispatch-client-workflow,04-end-workflowswitch fromskills.primary/skills.supportingtoskill_operations[]. Step-level operation references useoperation+argsfields.Resources
04-atlassian-tools.mddeleted (content inlined into atlassian-operations).05-workflow-state-format.mdretained (state schema reference).03-gitnexus-reference.mdretained for legacy usage; per-operation refs are inline in the skill.Legacy retention (dual-support)
The role-based skills (
meta-orchestrator,activity-worker,workflow-orchestrator) are preserved at the tail of the skill numbering (10–12) so client workflows still onskills.primary: meta-orchestratoretc. continue to load.meta workflow.toon
Bumps to v5.0.0; declares
skill_operations[]and dropsskills.primary(legacy field).Test plan
🤖 Generated with Claude Code