diff --git a/cicd-pipeline-security-audit/activities/01-scope-setup.toon b/cicd-pipeline-security-audit/activities/01-scope-setup.toon index aa73ff0d..323bbb0a 100644 --- a/cicd-pipeline-security-audit/activities/01-scope-setup.toon +++ b/cicd-pipeline-security-audit/activities/01-scope-setup.toon @@ -9,7 +9,6 @@ recognition[4]: - scan github actions - cicd security audit skills: - primary: meta/activity-worker supporting[1]: - execute-cicd-audit required: true diff --git a/cicd-pipeline-security-audit/activities/02-reconnaissance.toon b/cicd-pipeline-security-audit/activities/02-reconnaissance.toon index e9cd93b3..4dbe78cb 100644 --- a/cicd-pipeline-security-audit/activities/02-reconnaissance.toon +++ b/cicd-pipeline-security-audit/activities/02-reconnaissance.toon @@ -8,7 +8,6 @@ recognition[3]: - reconnaissance - map triggers skills: - primary: meta/activity-worker supporting[1]: - execute-cicd-audit required: true diff --git a/cicd-pipeline-security-audit/activities/03-primary-scan.toon b/cicd-pipeline-security-audit/activities/03-primary-scan.toon index 7aedcbbb..3c429ec4 100644 --- a/cicd-pipeline-security-audit/activities/03-primary-scan.toon +++ b/cicd-pipeline-security-audit/activities/03-primary-scan.toon @@ -8,7 +8,6 @@ recognition[3]: - run detection - primary scan skills: - primary: meta/activity-worker supporting[1]: - execute-cicd-audit required: true diff --git a/cicd-pipeline-security-audit/activities/04-report-generation.toon b/cicd-pipeline-security-audit/activities/04-report-generation.toon index ccf6b302..47dbdd40 100644 --- a/cicd-pipeline-security-audit/activities/04-report-generation.toon +++ b/cicd-pipeline-security-audit/activities/04-report-generation.toon @@ -8,7 +8,6 @@ recognition[3]: - consolidate findings - finalize report skills: - primary: meta/activity-worker supporting[1]: - execute-cicd-audit required: true diff --git a/cicd-pipeline-security-audit/activities/05-sub-workflow-scan.toon b/cicd-pipeline-security-audit/activities/05-sub-workflow-scan.toon index bd6cf67f..3e359a2e 100644 --- a/cicd-pipeline-security-audit/activities/05-sub-workflow-scan.toon +++ b/cicd-pipeline-security-audit/activities/05-sub-workflow-scan.toon @@ -7,7 +7,6 @@ recognition[2]: - scan submodule workflows - run detection patterns skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/cicd-pipeline-security-audit/activities/06-sub-verification.toon b/cicd-pipeline-security-audit/activities/06-sub-verification.toon index 1869f1c8..39957066 100644 --- a/cicd-pipeline-security-audit/activities/06-sub-verification.toon +++ b/cicd-pipeline-security-audit/activities/06-sub-verification.toon @@ -7,7 +7,6 @@ recognition[2]: - verify scan results - check scan completeness skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/cicd-pipeline-security-audit/activities/07-sub-merge.toon b/cicd-pipeline-security-audit/activities/07-sub-merge.toon index aa5858e3..b9880d22 100644 --- a/cicd-pipeline-security-audit/activities/07-sub-merge.toon +++ b/cicd-pipeline-security-audit/activities/07-sub-merge.toon @@ -7,7 +7,6 @@ recognition[2]: - merge findings - consolidate scan results skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/cicd-pipeline-security-audit/workflow.toon b/cicd-pipeline-security-audit/workflow.toon index 11cdebea..2097881c 100644 --- a/cicd-pipeline-security-audit/workflow.toon +++ b/cicd-pipeline-security-audit/workflow.toon @@ -32,7 +32,6 @@ rules[19]: - "AGENT OUTPUT PERSISTENCE: Every sub-agent MUST write its own structured output as a JSON file to the planning folder. The orchestrator verifies all expected files exist BEFORE dispatching V or M. If any file is missing, the orchestrator re-dispatches the agent. File naming: s{n}-{submodule}.json for scanners, verification-report.json for V, merged-findings.json and reconciliation-table.json for M." - "SUB-AGENT BOOTSTRAP: Every sub-agent receives workflow-server bootstrap instructions in its spawn-agent prompt (harness-compat): call start_session(session_token, agent_id) to inherit the dispatched session, then next_activity({ activity_id: }), then follow activity steps sequentially. Sub-agents self-load their activity definition — the orchestrator does NOT inline the activity content." skills: - primary: meta/workflow-orchestrator variables[14]: - name: target_submodules type: string diff --git a/meta/activities/00-discover-session.toon b/meta/activities/00-discover-session.toon index 77da56d2..18b404f0 100644 --- a/meta/activities/00-discover-session.toon +++ b/meta/activities/00-discover-session.toon @@ -1,7 +1,7 @@ id: discover-session -version: 3.0.0 +version: 7.0.0 name: Discover Session -description: "Identify the user's intended target workflow and search for an existing client session to resume. Calls list_workflows for the catalog, matches the user request against workflow descriptions, scans planning folders for saved client sessions matching the request's identifying context (ticket, branch, PR, work-package name), and presents resume / workflow-selection checkpoints. Always runs first — bootstrap delegates target identification and session matching here." +description: "Identify the user's intended target workflow and search for an existing client session to resume. Always runs first — bootstrap delegates target identification and session matching here." problem: The meta workflow needs to determine which client workflow to dispatch and whether to resume an existing client session, before initialize-session creates or adopts the client session recognition[4]: - start a workflow @@ -10,30 +10,31 @@ recognition[4]: - work on required: true estimatedTime: 1-2m -skills: - primary: meta/activity-worker - supporting[1]: - - state-management -rules[2]: - - "Always call list_workflows — never hardcode the workflow catalog" +operations[5]: + - "workflow-engine::list-workflows" + - "workflow-engine::match-target-workflow" + - "workflow-engine::extract-identifying-context" + - "workflow-engine::scan-saved-sessions" + - "workflow-engine::match-saved-session" +rules[1]: - "Match identifying context against saved sessions even when the user said 'start' — surface saved state via the resume-session checkpoint" -steps[5]: +steps[7]: - id: list-available-workflows - name: List Available Workflows - description: "Call list_workflows (no session token required) to retrieve the catalog of available workflows with their titles, descriptions, and recognition tags. Cache the catalog for the match step." - - id: identify-target - name: Identify Target Workflow and Context - description: "Compare the user's request against the workflow catalog. Match on title, description keywords, and recognition tags. Set target_workflow_id to the matched workflow. If multiple workflows could match, set workflow_match_ambiguous = true so the workflow-selection checkpoint fires. Also extract identifying context — ticket number (GitHub #N, Jira PROJ-123), branch name, PR number, or work-package description — for the saved-session match step." + description: "workflow-engine::list-workflows()" + - id: match-target + description: "workflow-engine::match-target-workflow(user_request: {user_request}, catalog: {workflow_catalog})" + - id: extract-context + description: "workflow-engine::extract-identifying-context(user_request: {user_request})" - id: scan-planning-folders - name: Scan Planning Folders for Saved Sessions - description: "List directories under .engineering/artifacts/planning/. For each directory containing a workflow-state.toon file, read it and extract: saved sessionToken, workflowId, planningFolder, and key state variables (issue_number, branch_name, pr_number, work-package description). Collect all candidates whose workflowId matches target_workflow_id." - skill: state-management + description: "workflow-engine::scan-saved-sessions(target_workflow_id: {target_workflow_id})" - id: match-session - name: Match Saved Session to User Request - description: "Compare the identifying context from identify-target against the candidate saved sessions. Match on issue_number, branch_name, pr_number, or directory name containing the ticket identifier. If multiple matches, prefer the most recently updated by savedAt. If no matches, set has_saved_state = false." - - id: prepare-result - name: Prepare Discovery Result - description: "If a match was found: set has_saved_state = true, saved_session_token = matched session's sessionToken, planning_folder_path = matched session's planningFolder. If no match: set has_saved_state = false. Set is_resuming = false by default; the resume-session checkpoint may flip it to true." + description: "workflow-engine::match-saved-session(context: {identifying_context}, candidates: {saved_session_candidates})" + - id: record-match + description: "Set has_saved_state = true; copy saved_session_token and planning_folder_path from the matched candidate." + when: "has_saved_state == true" + - id: record-no-match + description: "Set has_saved_state = false; the resume-session checkpoint will not fire." + when: "has_saved_state == false" checkpoints[2]: - id: workflow-selection name: Workflow Selection diff --git a/meta/activities/01-initialize-session.toon b/meta/activities/01-initialize-session.toon index 4eab4a40..92a79573 100644 --- a/meta/activities/01-initialize-session.toon +++ b/meta/activities/01-initialize-session.toon @@ -1,55 +1,34 @@ id: initialize-session -version: 1.0.0 +version: 4.0.0 name: Initialize Session -description: "Create or adopt the client workflow's session as a child of the meta session. If discover-session matched a saved client session, adopt it via start_session and restore variables from disk. Otherwise, create a fresh child session via start_session({ workflow_id, parent_session_token }) and initialize the planning folder. Sets client_session_token, planning_folder_path, and the session-recovery flags." +description: "Create or adopt the client workflow's session as a child of the meta session. Restore variables on resume; create the planning folder on fresh starts." problem: The client workflow needs a valid session token before its orchestrator can be dispatched, and saved state must be restored before activities resume -skills: - primary: meta/activity-worker - supporting[3]: - - session-protocol - - state-management - - version-control required: true estimatedTime: 1-2m -rules[3]: - - "When creating a fresh client session, ALWAYS pass parent_session_token so trace correlation links the meta session to the client workflow" - - "When adopting a saved session, treat the saved token as opaque — never decode or modify it" - - "If start_session returns recovered: true, the saved payload was corrupted — variables MUST be reconstructed from the on-disk state file before any activity runs" -steps[5]: - - id: start-or-adopt-session - name: Start or Adopt Client Session - description: "If has_saved_state: call start_session({ session_token: saved_session_token, agent_id: 'orchestrator' }) to adopt the saved client session. Otherwise: call start_session({ workflow_id: target_workflow_id, parent_session_token: session_token, agent_id: 'orchestrator' }) to create a fresh child session. Save the returned token as client_session_token." - skill: session-protocol +operations[5]: + - "workflow-engine::adopt-session" + - "workflow-engine::create-session" + - "workflow-engine::restore" + - "workflow-engine::persist" + - "version-control::initialize-folder" +steps[6]: + - id: adopt-saved-session + description: "workflow-engine::adopt-session(saved_session_token: {saved_session_token})" + when: "has_saved_state == true" + - id: create-fresh-session + description: "workflow-engine::create-session(workflow_id: {target_workflow_id}, parent_session_token: {session_token})" + when: "has_saved_state == false" - id: detect-recovery - name: Detect Server-Restart Recovery - description: "Inspect the start_session response. If recovered: true, the saved token failed signature verification AND its payload was corrupted — set session_recovered = true so the next step reconstructs variables from disk. If adopted: true, the token was re-signed but its payload was preserved — set session_adopted = true (no reconstruction needed). Otherwise both flags remain false." + description: "Inspect the start_session response. Set session_recovered when it carries recovered: true; set session_adopted when it carries adopted: true." - id: restore-state - name: Restore Variables from Disk - description: "If is_resuming: call restore_state({ session_token: client_session_token, file_path: '{planning_folder_path}/workflow-state.toon' }) to load the saved variables and apply each to the client session. This step covers both adopted and recovered sessions — for recovered sessions it is the only source of truth for state." - condition: - type: simple - variable: is_resuming - operator: "==" - value: true - skill: state-management + description: "workflow-engine::restore(session_token: {client_session_token}, file_path: {planning_folder_path}/workflow-state.toon)" + when: "is_resuming == true" - id: derive-planning-folder - name: Derive Planning Folder Path - description: "If fresh session and planning_folder_path is not yet set, derive it from the user's request context: .engineering/artifacts/planning/YYYY-MM-DD-{initiative-name}/ where initiative-name is kebab-cased from issue title, work-package description, or other identifying context. Store as planning_folder_path." - condition: - type: simple - variable: is_resuming - operator: "!=" - value: true - skill: version-control - - id: initialize-folder - name: Initialize Planning Folder - description: "If fresh session: create the planning folder at planning_folder_path (mkdir -p), then call save_state({ session_token: client_session_token, planning_folder_path }) to write the initial workflow-state.toon containing the client session token and default variables. This guarantees the token is on disk before any activity is dispatched." - condition: - type: simple - variable: is_resuming - operator: "!=" - value: true - skill: state-management + description: "version-control::initialize-folder(initiative_name: )" + when: "is_resuming == false" + - id: initialize-state + description: "workflow-engine::persist(session_token: {client_session_token}, planning_folder_path: {planning_folder_path})" + when: "is_resuming == false" transitions[1]: - to: resolve-target isDefault: true diff --git a/meta/activities/02-resolve-target.toon b/meta/activities/02-resolve-target.toon index 7082d03f..a3b4af66 100644 --- a/meta/activities/02-resolve-target.toon +++ b/meta/activities/02-resolve-target.toon @@ -1,33 +1,27 @@ id: resolve-target -version: 1.0.0 +version: 4.0.0 name: Resolve Target -description: "Detect the target repository structure (regular directory vs. submodule monorepo) and resolve target_path. Skipped when target_path was already restored from saved state. Sets is_monorepo and target_path for downstream activities that perform git operations on the user's codebase." +description: "Detect the target repository structure (regular directory vs. submodule monorepo) and resolve target_path." problem: Workflows that operate on a target codebase need to know whether the working directory is a regular repo or a submodule monorepo, and which submodule is the target -skills: - primary: meta/activity-worker required: true estimatedTime: 1-2m -rules[2]: - - "Skip detection when target_path was already restored from saved state (target_path != '.')" +operations[2]: + - "version-control::detect-repo-type" + - "version-control::list-submodules" +rules[1]: - "target_path MUST resolve to a directory containing a working git tree" entryActions[1]: - action: log message: "Resolving target repository structure" steps[3]: - id: detect-monorepo - name: Detect Repository Type - description: "Check whether the working directory contains a .gitmodules file (test -f .gitmodules). If present, this is a submodule monorepo. If absent, this is a regular repository and target_path defaults to the repository root." + description: "version-control::detect-repo-type()" - id: list-submodules - name: List Submodules - description: "If is_monorepo is true (set by the repo-type-confirmed checkpoint): parse .gitmodules to extract the submodule paths and present them as a numbered list, including a brief description of each (from the submodule's README first paragraph or its path)." - condition: - type: simple - variable: is_monorepo - operator: "==" - value: true - - id: capture-target-path - name: Capture Target Path - description: "If is_monorepo: ask the user to select a submodule, set target_path to its path, and verify the directory exists. If not is_monorepo: set target_path to '.'." + description: "version-control::list-submodules()" + when: "is_monorepo == true" + - id: capture-submodule-target + description: "Ask the user to select a submodule from the listed entries. Set target_path to the chosen path." + when: "is_monorepo == true" checkpoints[1]: - id: repo-type-confirmed name: Repository Type Confirmation diff --git a/meta/activities/03-dispatch-client-workflow.toon b/meta/activities/03-dispatch-client-workflow.toon index 8e075d73..f7ce8553 100644 --- a/meta/activities/03-dispatch-client-workflow.toon +++ b/meta/activities/03-dispatch-client-workflow.toon @@ -1,37 +1,31 @@ id: dispatch-client-workflow -version: 1.0.0 +version: 4.0.0 name: Dispatch Client Workflow -description: "Compose the workflow-orchestrator prompt, dispatch the orchestrator (sub-agent in spawning harnesses, inline persona otherwise) for the client workflow, and drive the checkpoint-yield loop. Each loop iteration parses the orchestrator's most recent output: a block triggers present-checkpoint → ask-user → respond-checkpoint → continue-orchestrator; a workflow_complete result sets client_workflow_completed and exits the loop." +description: "Compose the workflow-orchestrator prompt, dispatch the orchestrator, and drive the checkpoint-yield loop until workflow_complete." problem: The orchestrator runs as a sub-agent (or inline persona) and surfaces checkpoints upward; meta must mediate user interaction for those checkpoints and resume the orchestrator with the resolved effects -skills: - primary: meta/activity-worker - supporting[3]: - - meta-orchestrator - - harness-compat - - session-protocol required: true -rules[3]: - - "NEVER auto-resolve a checkpoint — the user MUST explicitly select an option (or the autoAdvance timer MUST fully elapse for advisory checkpoints)" +operations[5]: + - "workflow-engine::compose-prompt" + - "workflow-engine::extract-checkpoint-handle" + - "workflow-engine::handle-workflow-complete" + - "harness-compat::spawn-agent" + - "harness-compat::continue-agent" +rules[1]: - "Pass client_session_token to the orchestrator prompt — the orchestrator inherits state via that token, NEVER via the meta session token" - - "Always dispatch as foreground (blocking) per harness-compat::spawn-agent — background dispatch silently breaks checkpoint delivery" entryActions[1]: - action: validate target: client_session_token message: "Cannot dispatch without a client session token; initialize-session must run first" steps[2]: - id: compose-orchestrator-prompt - name: Compose Orchestrator Prompt - description: "Build the workflow-orchestrator prompt using resource meta/02 (workflow-orchestrator-prompt) as the template. Substitute: workflow_id = target_workflow_id, session_token = client_session_token, planning_folder_path, target_path, agent_id = 'workflow-orchestrator'. The prompt instructs the orchestrator to call start_session to adopt the session, then load and follow its primary skill." - skill: meta-orchestrator + description: "workflow-engine::compose-prompt(template_ref: meta/workflow-orchestrator-prompt, substitutions: { workflow_id: {target_workflow_id}, session_token: {client_session_token}, planning_folder_path: {planning_folder_path}, target_path: {target_path}, agent_id: workflow-orchestrator })" - id: dispatch-orchestrator - name: Dispatch Orchestrator (Initial) - description: "Call harness-compat::spawn-agent with the composed prompt. Spawn-agent always runs foreground and blocks until the orchestrator yields a checkpoint or returns workflow_complete. Subsequent iterations of checkpoint-loop use harness-compat::continue-agent to resume the orchestrator." - skill: harness-compat + description: "harness-compat::spawn-agent(prompt: {composed_orchestrator_prompt}, description: Workflow orchestrator for {target_workflow_id})" loops[1]: - id: checkpoint-loop name: Checkpoint-Yield Loop type: doWhile - description: "Iterate while the client workflow is still running. Each iteration handles either a yielded checkpoint or the workflow_complete signal. Body steps short-circuit via condition when client_workflow_completed becomes true." + description: "Iterate until the orchestrator reports workflow_complete." condition: type: simple variable: client_workflow_completed @@ -39,45 +33,26 @@ loops[1]: value: false maxIterations: 200 steps[5]: - - id: parse-orchestrator-result - name: Parse Orchestrator Result - description: "Inspect the orchestrator's most recent output. If it contains a block: extract checkpoint_handle and store as pending_checkpoint_handle. If the output is workflow_complete: apply any final variables_changed, set client_workflow_completed = true so the remaining loop body is skipped via condition." - - id: present-checkpoint - name: Present Checkpoint - description: "Call present_checkpoint({ checkpoint_handle: pending_checkpoint_handle }) — and ONLY checkpoint_handle, never session_token or checkpoint_id — to retrieve the question text and option list for THIS checkpoint. Do not reuse options from a prior checkpoint." - condition: - type: simple - variable: client_workflow_completed - operator: "==" - value: false - skill: meta-orchestrator - - id: ask-user - name: Ask User - description: "For blocking checkpoints (no autoAdvanceMs): use the harness AskQuestion tool with the retrieved message and options; capture the user's selected option_id. For advisory checkpoints (autoAdvanceMs set): present the message in chat and use Shell sleep for the full autoAdvanceMs before resolving with auto_advance — never short-circuit the timer." - condition: - type: simple - variable: client_workflow_completed - operator: "==" - value: false - skill: meta-orchestrator + - id: capture-checkpoint-yield + description: "workflow-engine::extract-checkpoint-handle(output: {orchestrator_output})" + when: "client_workflow_completed == false" + - id: capture-workflow-complete + description: "workflow-engine::handle-workflow-complete(result: {orchestrator_output})" + when: "client_workflow_completed == false" + - id: present-and-resolve + description: "workflow-engine::present-checkpoint-to-user(checkpoint_handle: {pending_checkpoint_handle})" + when: "client_workflow_completed == false" - id: respond-checkpoint - name: Respond Checkpoint - description: "Call respond_checkpoint({ checkpoint_handle: pending_checkpoint_handle, option_id: }) — or { auto_advance: true } for advisory checkpoints with the timer fully elapsed, or { condition_not_met: true } only for conditional checkpoints whose prerequisite evaluated false. Capture the returned effects (variable changes)." - condition: - type: simple - variable: client_workflow_completed - operator: "==" - value: false - skill: meta-orchestrator + description: "workflow-engine::respond-checkpoint(checkpoint_handle: {pending_checkpoint_handle}, resolution: {user_selection})" + when: "client_workflow_completed == false" + actions[1]: + - action: set + target: client_session_token + value: "{resumed_session_token}" + description: "Advance the client session token to the post-respond handle returned by respond_checkpoint. The previous client_session_token still has bcp set; reusing it would gate every subsequent worker call." - id: continue-orchestrator - name: Continue Orchestrator - description: "Call harness-compat::continue-agent with a resume prompt that conveys the checkpoint resolution: the option chosen and the effect's variable updates. The orchestrator updates its internal state and resumes its waiting worker. Wait for the next yield or workflow_complete." - condition: - type: simple - variable: client_workflow_completed - operator: "==" - value: false - skill: harness-compat + description: "harness-compat::continue-agent(session_token: {client_session_token}, prompt: Checkpoint resolved. Use this resumed session_token for all subsequent calls (NOT your yield-time checkpoint_handle — that still has bcp set): {client_session_token}. Effects to apply: {effects}. Continue execution from the paused step.)" + when: "client_workflow_completed == false" transitions[1]: - to: end-workflow condition: diff --git a/meta/activities/04-end-workflow.toon b/meta/activities/04-end-workflow.toon index 534c71e7..2a8a0406 100644 --- a/meta/activities/04-end-workflow.toon +++ b/meta/activities/04-end-workflow.toon @@ -1,29 +1,21 @@ id: end-workflow -version: 1.0.0 +version: 4.0.0 name: End Workflow -description: "Verify the client workflow's outcomes were satisfied, generate a session summary, persist final state, and confirm closure with the user. If the user opts to return to the workflow (e.g., to address an unmet outcome), transitions back to dispatch-client-workflow with abort_completion set." +description: "Verify the client workflow's outcomes were satisfied, generate a session summary, persist final state, and confirm closure with the user. If the user opts to return to the workflow, transitions back to dispatch-client-workflow with abort_completion set." problem: Workflow sessions need an explicit close-out so the user knows the work is done and the final state is durably persisted -skills: - primary: meta/activity-worker - supporting[2]: - - state-management - - meta-orchestrator required: true estimatedTime: 2-3m -rules[2]: - - "Final save_state is mandatory — workflow-state.toon must reflect the final session token, variable state, and a status of 'completed'" - - "Outcome verification compares the workflow definition's outcome[] against state — surface any unsatisfied outcomes to the user before closure" +operations[3]: + - "workflow-engine::verify-outcomes" + - "workflow-engine::generate-summary" + - "workflow-engine::persist" steps[3]: - id: verify-outcomes - name: Verify Outcomes - description: "Read the client workflow's outcome[] from its definition. For each outcome, check whether it was satisfied — via state variables, artifact presence in planning_folder_path, or completed-activities trace. Collect any unmet outcomes for the summary." + description: "workflow-engine::verify-outcomes(outcome: {target_workflow_outcomes}, state: {client_state})" - id: generate-summary - name: Generate Session Summary - description: "Compose a markdown summary including: workflow ID and title; start and completion timestamps; activities completed; key checkpoint decisions (option chosen and rationale where stated); artifacts produced with paths; outcomes satisfied vs. unmet; follow-up items raised during the workflow. Present to the user as a chat message before the completion checkpoint." + description: "workflow-engine::generate-summary(workflow: {target_workflow}, trace: {client_trace})" - id: final-persist - name: Persist Final State - description: "Call save_state({ session_token: client_session_token, planning_folder_path }) with the final variable state. The workflow-state.toon file remains valid for future audit and for resume operations against the closed session." - skill: state-management + description: "workflow-engine::persist(session_token: {client_session_token}, planning_folder_path: {planning_folder_path})" checkpoints[1]: - id: completion-confirmed name: Completion Confirmation diff --git a/meta/resources/00-bootstrap-protocol.md b/meta/resources/00-bootstrap-protocol.md index a52fa775..fba92c4a 100644 --- a/meta/resources/00-bootstrap-protocol.md +++ b/meta/resources/00-bootstrap-protocol.md @@ -1,14 +1,17 @@ --- id: bootstrap-protocol -version: 6.1.0 +version: 7.0.0 --- # Bootstrap Protocol +IMPORTANT: YOU *MUST* *ALWAYS* EXECUTE ALL OF THESE STEPS + 1. Fetch: - `workflow-server://schemas/workflow` - `workflow-server://schemas/skill` + - `workflow-server://schemas/activity` 2. `start_session({ workflow_id: "meta", agent_id: "orchestrator" })`. Save the returned `session_token`. -3. `get_workflow({ session_token })`. Follow the primary skill returned in the response. +3. `get_workflow({ session_token })`. The response carries the workflow's resolved operations bundle ahead of the workflow definition (separated by `\n\n---\n\n`). Follow the operations and rules in the bundle to drive execution. diff --git a/meta/resources/01-activity-worker-prompt.md b/meta/resources/01-activity-worker-prompt.md index 0e1f5092..f727c984 100644 --- a/meta/resources/01-activity-worker-prompt.md +++ b/meta/resources/01-activity-worker-prompt.md @@ -1,6 +1,6 @@ --- id: activity-worker-prompt -version: 2.0.0 +version: 3.0.0 --- You are an autonomous worker agent executing a single activity for the `{workflow_id}` workflow. @@ -14,6 +14,11 @@ You are an autonomous worker agent executing a single activity for the `{workflo ## Bootstrap Instructions -1. Call `get_activity({ session_token })` to load the complete activity definition. -2. Examine the returned skill definition. If it contains a `_resources` array, call `get_resource({ session_token, resource_id })` to fetch the full text content for EACH required resource. -3. Follow the skill's instructions. +1. Call `get_activity({ session_token })`. The response carries the activity's resolved operations bundle ahead of the activity definition (separated by `\n\n---\n\n`). Each operation entry is `{ source, name, type, body, ref }`. +2. For any operation in the bundle whose body declares a `resources[]` array, call `get_resource({ session_token, resource_id })` for each resource id. +3. Execute each step in the activity. A step's `description` carries the inline operation invocation (`skill::operation(arg: {var}, ...)`); a `when:` field, when present, gates execution against the current variable state. +4. Follow the rules in the operations bundle throughout — `agent-conduct`, `workflow-engine`, and any other touched skills include their global rules automatically. + + +# Rules +- As a worker agent, you must NEVER call any of the following workflow-server MCP tools: next_activity, get_workflow, or list_workflows \ No newline at end of file diff --git a/meta/resources/02-workflow-orchestrator-prompt.md b/meta/resources/02-workflow-orchestrator-prompt.md index e613bedc..96d0239d 100644 --- a/meta/resources/02-workflow-orchestrator-prompt.md +++ b/meta/resources/02-workflow-orchestrator-prompt.md @@ -1,6 +1,6 @@ --- id: workflow-orchestrator-prompt -version: 2.1.0 +version: 3.1.0 --- You are an autonomous workflow orchestrator managing the execution of the `{workflow_id}` workflow. @@ -13,8 +13,8 @@ You are an autonomous workflow orchestrator managing the execution of the `{work ## Bootstrap Instructions -1. Call `start_session({ session_token: "{session_token}", agent_id: "{agent_id}" })` to adopt the session. -2. Call `get_workflow({ session_token, summary: false })` to load the workflow structure and primary skill. -3. Examine the returned skill definition. If it contains a `_resources` array, call `get_resource({ session_token, resource_id })` to fetch the full text content for EACH required resource. -4. **Resume detection:** If `start_session` returned `inherited: true` or `adopted: true`, you are resuming a previous session. Call `get_workflow_status({ session_token })` to read the `current_activity` field (the session already encodes the activity position — do NOT start from `initialActivity`). Dispatch the activity-worker for that activity with the restored state variables provided in this prompt. -5. Follow the skill's instructions to proceed. +1. Call MCP tool `start_session` with EXACTLY these named parameters: `session_token` = `"{session_token}"` (the value above, bound to the canonical `session_token` parameter — do NOT invent a `saved_session_token` parameter), `agent_id` = `"{agent_id}"`. Pass nothing else; the schema is strict and unknown keys are rejected. If the response carries `recovered: true`, call `workflow-engine::restore` (from the operations bundle returned next) to rebuild variables from the on-disk state file. If the response carries `adopted: true`, the saved token was re-signed in place — keep using the RETURNED `session_token` for every subsequent call. +2. Call `get_workflow({ session_token })`. The response carries the workflow's resolved operations bundle ahead of the workflow definition (separated by `\n\n---\n\n`). Each operation entry is `{ source, name, type, body, ref }`. +3. For any operation in the bundle whose body declares a `resources[]` array, call `get_resource({ session_token, resource_id })` for each resource id. +4. **Resume detection:** Call `get_workflow_status({ session_token })`. Pick the activity to dispatch: use `current_activity` when it is set (resuming mid-workflow), otherwise use the workflow's `initialActivity` (fresh start). Then ALWAYS dispatch a worker for that activity via `workflow-engine::dispatch-activity` — the orchestrator NEVER executes activity steps inline, even on resume, even when restored variables and prior planning-folder artifacts are visible in context. The worker is responsible for detecting already-completed work from artifact presence and skipping accordingly. Resume changes WHICH activity is dispatched, not WHETHER one is dispatched. +5. Drive the activity loop using the operations in the bundle — `workflow-engine::dispatch-activity`, `evaluate-transition`, `commit-and-persist`, `bubble-checkpoint-up`. Bubble worker checkpoint yields up unchanged; resume the worker with the resolved effects on each round. diff --git a/meta/resources/03-gitnexus-reference.md b/meta/resources/03-gitnexus-reference.md deleted file mode 100644 index 2ed031ce..00000000 --- a/meta/resources/03-gitnexus-reference.md +++ /dev/null @@ -1,337 +0,0 @@ ---- -id: gitnexus-reference -version: 2.0.0 ---- - -# GitNexus Reference - -Checklists, pattern tables, examples, and CLI commands for GitNexus workflows. For tool definitions and protocols, see the `gitnexus-operations` skill (universal skill 08). - -> If `gitnexus://repo/{name}/context` warns the index is stale, run `npx gitnexus analyze` in the terminal before proceeding. - ---- - -## Contents - -1. [Quick Reference](#1-quick-reference) — Task routing, MCP resources, graph schema -2. [Exploring Codebases](#2-exploring-codebases) — Checklist and example -3. [Impact Analysis](#3-impact-analysis) — Checklist, depth/risk tables, example -4. [Debugging](#4-debugging) — Checklist, pattern table, example -5. [Refactoring](#5-refactoring) — Checklists (rename, extract, split), risk table, example -6. [CLI Commands](#6-cli-commands) — analyze, status, clean, wiki, list - ---- - -## 1. Quick Reference - -### Task Routing - -| Task | Section | -| -------------------------------------------- | ------------------------------------------------ | -| Understand architecture / "How does X work?" | [2. Exploring Codebases](#2-exploring-codebases) | -| Blast radius / "What breaks if I change X?" | [3. Impact Analysis](#3-impact-analysis) | -| Trace bugs / "Why is X failing?" | [4. Debugging](#4-debugging) | -| Rename / extract / split / refactor | [5. Refactoring](#5-refactoring) | -| Index, status, clean, wiki CLI commands | [6. CLI Commands](#6-cli-commands) | - -### MCP Resources - -Lightweight reads (~100-500 tokens) for navigation: - -| Resource | Content | -| ---------------------------------------------- | ----------------------------------------- | -| `gitnexus://repo/{name}/context` | Stats, staleness check | -| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores | -| `gitnexus://repo/{name}/cluster/{clusterName}` | Area members | -| `gitnexus://repo/{name}/processes` | All execution flows | -| `gitnexus://repo/{name}/process/{processName}` | Step-by-step trace | -| `gitnexus://repo/{name}/schema` | Graph schema for Cypher | - -### Graph Schema - -**Nodes:** File, Function, Class, Interface, Method, Community, Process -**Edges (via CodeRelation.type):** CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS - -```cypher -MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "myFunc"}) -RETURN caller.name, caller.filePath -``` - ---- - -## 2. Exploring Codebases - -### When to Use - -- "How does authentication work?" -- "What's the project structure?" -- "Show me the main components" -- Understanding code you haven't seen before - -### Checklist - -``` -- [ ] READ gitnexus://repo/{name}/context -- [ ] gitnexus_query for the concept you want to understand -- [ ] Review returned processes (execution flows) -- [ ] gitnexus_context on key symbols for callers/callees -- [ ] READ process resource for full execution traces -- [ ] Read source files for implementation details -``` - -### Example: "How does payment processing work?" - -``` -1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes -2. gitnexus_query({query: "payment processing"}) - → CheckoutFlow: processPayment → validateCard → chargeStripe - → RefundFlow: initiateRefund → calculateRefund → processRefund -3. gitnexus_context({name: "processPayment"}) - → Incoming: checkoutHandler, webhookHandler - → Outgoing: validateCard, chargeStripe, saveTransaction -4. Read src/payments/processor.ts for implementation details -``` - ---- - -## 3. Impact Analysis - -### When to Use - -- "Is it safe to change this function?" -- "What will break if I modify X?" -- Before making non-trivial code changes -- Before committing — to understand what your changes affect - -### Checklist - -``` -- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents -- [ ] Review d=1 items first (these WILL BREAK) -- [ ] Check high-confidence (>0.8) dependencies -- [ ] READ processes to check affected execution flows -- [ ] gitnexus_detect_changes() for pre-commit check -- [ ] Assess risk level and report to user -``` - -### Depth Levels - -| Depth | Risk Level | Meaning | -| ----- | ---------------- | ------------------------ | -| d=1 | **WILL BREAK** | Direct callers/importers | -| d=2 | LIKELY AFFECTED | Indirect dependencies | -| d=3 | MAY NEED TESTING | Transitive effects | - -### Risk Assessment - -| Affected | Risk | -| ------------------------------ | -------- | -| <5 symbols, few processes | LOW | -| 5-15 symbols, 2-5 processes | MEDIUM | -| >15 symbols or many processes | HIGH | -| Critical path (auth, payments) | CRITICAL | - -### Example: "What breaks if I change validateUser?" - -``` -1. gitnexus_impact({target: "validateUser", direction: "upstream"}) - → d=1: loginHandler, apiMiddleware (WILL BREAK) - → d=2: authRouter, sessionManager (LIKELY AFFECTED) - -2. READ gitnexus://repo/my-app/processes - → LoginFlow and TokenRefresh touch validateUser - -3. Risk: 2 direct callers, 2 processes = MEDIUM -``` - ---- - -## 4. Debugging - -### When to Use - -- "Why is this function failing?" -- "Trace where this error comes from" -- "This endpoint returns 500" -- Investigating bugs, errors, or unexpected behavior - -### Checklist - -``` -- [ ] Understand the symptom (error message, unexpected behavior) -- [ ] gitnexus_query for error text or related code -- [ ] Identify the suspect function from returned processes -- [ ] gitnexus_context to see callers and callees -- [ ] Trace execution flow via process resource if applicable -- [ ] gitnexus_cypher for custom call chain traces if needed -- [ ] Read source files to confirm root cause -``` - -### Debugging Patterns - -| Symptom | GitNexus Approach | -| -------------------- | ---------------------------------------------------------- | -| Error message | `gitnexus_query` for error text → `context` on throw sites | -| Wrong return value | `context` on the function → trace callees for data flow | -| Intermittent failure | `context` → look for external calls, async deps | -| Performance issue | `context` → find symbols with many callers (hot paths) | -| Recent regression | `detect_changes` to see what your changes affect | - -### Example: "Payment endpoint returns 500 intermittently" - -``` -1. gitnexus_query({query: "payment error handling"}) - → Processes: CheckoutFlow, ErrorHandling - → Symbols: validatePayment, handlePaymentError - -2. gitnexus_context({name: "validatePayment"}) - → Outgoing calls: verifyCard, fetchRates (external API!) - -3. READ gitnexus://repo/my-app/process/CheckoutFlow - → Step 3: validatePayment → calls fetchRates (external) - -4. Root cause: fetchRates calls external API without proper timeout -``` - ---- - -## 5. Refactoring - -### When to Use - -- "Rename this function safely" -- "Extract this into a module" -- "Split this service" -- Any task involving renaming, extracting, splitting, or restructuring code - -### Rename Symbol - -``` -- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits -- [ ] Review graph edits (high confidence) and text_search edits (review carefully) -- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits -- [ ] gitnexus_detect_changes() — verify only expected files changed -- [ ] Run tests for affected processes -``` - -### Extract Module - -``` -- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs -- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers -- [ ] Define new module interface -- [ ] Extract code, update imports -- [ ] gitnexus_detect_changes() — verify affected scope -- [ ] Run tests for affected processes -``` - -### Split Function/Service - -``` -- [ ] gitnexus_context({name: target}) — understand all callees -- [ ] Group callees by responsibility -- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update -- [ ] Create new functions/services -- [ ] Update callers -- [ ] gitnexus_detect_changes() — verify affected scope -- [ ] Run tests for affected processes -``` - -### Risk Rules - -| Risk Factor | Mitigation | -| ------------------- | ----------------------------------------- | -| Many callers (>5) | Use gitnexus_rename for automated updates | -| Cross-area refs | Use detect_changes after to verify scope | -| String/dynamic refs | gitnexus_query to find them | -| External/public API | Version and deprecate properly | - -### Example: Rename `validateUser` to `authenticateUser` - -``` -1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true}) - → 12 edits: 10 graph (safe), 2 text_search (review) - → Files: validator.ts, login.ts, middleware.ts, config.json... - -2. Review text_search edits (config.json: dynamic reference!) - -3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false}) - → Applied 12 edits across 8 files - -4. gitnexus_detect_changes({scope: "all"}) - → Affected: LoginFlow, TokenRefresh - → Risk: MEDIUM — run tests for these flows -``` - ---- - -## 6. CLI Commands - -All commands work via `npx` — no global install required. - -### analyze — Build or refresh the index - -```bash -npx gitnexus analyze -``` - -Run from the project root. Parses source files, builds the knowledge graph, writes to `.gitnexus/`. - -| Flag | Effect | -| -------------- | ---------------------------------------------------------------- | -| `--force` | Force full re-index even if up to date | -| `--embeddings` | Enable embedding generation for semantic search (off by default) | - -**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. - -### status — Check index freshness - -```bash -npx gitnexus status -``` - -Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. - -### clean — Delete the index - -```bash -npx gitnexus clean -``` - -Deletes `.gitnexus/` and unregisters the repo from the global registry. - -| Flag | Effect | -| --------- | ------------------------------------------------- | -| `--force` | Skip confirmation prompt | -| `--all` | Clean all indexed repos, not just the current one | - -### wiki — Generate documentation from the graph - -```bash -npx gitnexus wiki -``` - -Generates repository documentation from the knowledge graph using an LLM. - -| Flag | Effect | -| ------------------- | ----------------------------------------- | -| `--force` | Force full regeneration | -| `--model ` | LLM model (default: minimax/minimax-m2.5) | -| `--base-url ` | LLM API base URL | -| `--api-key ` | LLM API key | -| `--concurrency ` | Parallel LLM calls (default: 3) | -| `--gist` | Publish wiki as a public GitHub Gist | - -### list — Show all indexed repos - -```bash -npx gitnexus list -``` - -Lists all repositories registered in `~/.gitnexus/registry.json`. - -### Troubleshooting - -- **"Not inside a git repository"**: Run from a directory inside a git repo -- **Index is stale after re-analyzing**: Restart Claude Code to reload the MCP server -- **Embeddings slow**: Omit `--embeddings` (off by default) or set `OPENAI_API_KEY` for faster API-based embedding diff --git a/meta/resources/04-atlassian-tools.md b/meta/resources/04-atlassian-tools.md deleted file mode 100644 index 9466659e..00000000 --- a/meta/resources/04-atlassian-tools.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -id: atlassian-tools -version: 1.0.0 ---- - -# Atlassian MCP Tool Reference - -Complete reference for Atlassian MCP server tools. Organized by product. - -## Prerequisites - -Every product-specific tool requires `cloudId`. Call `getAccessibleAtlassianResources` first. - -## Jira Tools - -| Tool | When | Key Params | Returns | -|------|------|------------|---------| -| `searchJiraIssuesUsingJql` | Precise search with field-level filtering | `cloudId`, `jql`, `fields[]`, `maxResults` | Matching issues | -| `getVisibleJiraProjects` | Discover projects before creating issues | `cloudId`, optional `searchString` | Projects with keys and issue types | -| `getJiraProjectIssueTypesMetadata` | Discover issue types for a project | `cloudId`, `projectIdOrKey` | Issue types with IDs and names | -| `getJiraIssueTypeMetaWithFields` | Discover fields for an issue type | `cloudId`, `projectIdOrKey`, `issueTypeId` | Field metadata | -| `createJiraIssue` | Create a new issue | `cloudId`, `projectKey`, `issueTypeName`, `summary`, optional `description`, `additional_fields` | Created issue key | -| `editJiraIssue` | Update issue fields | `cloudId`, `issueIdOrKey`, `fields` object | Confirmation | -| `getJiraIssue` | Read a single issue | `cloudId`, `issueIdOrKey` | Full issue details | -| `getTransitionsForJiraIssue` | Discover available status transitions | `cloudId`, `issueIdOrKey` | Available transitions with IDs | -| `transitionJiraIssue` | Change issue status | `cloudId`, `issueIdOrKey`, `transition` object with ID | Confirmation | -| `addCommentToJiraIssue` | Add a comment | `cloudId`, `issueIdOrKey`, `commentBody` (Markdown) | Created comment | -| `addWorklogToJiraIssue` | Log work | `cloudId`, `issueIdOrKey`, `timeSpent` (e.g., '2h') | Confirmation | -| `lookupJiraAccountId` | Resolve user name/email to account ID | `cloudId`, `searchString` | Matching accounts | - -## Confluence Tools - -| Tool | When | Key Params | Returns | -|------|------|------------|---------| -| `searchConfluenceUsingCql` | Structured search with CQL | `cloudId`, `cql`, optional `limit`, `cursor` | Matching content | -| `createConfluencePage` | Create a page | `cloudId`, `spaceId`, `body` (Markdown), `contentFormat: 'markdown'`, optional `title`, `parentId` | Created page ID | -| `updateConfluencePage` | Update a page (full replace) | `cloudId`, `pageId`, `body` (Markdown), optional `title` | Updated page | -| `getConfluencePage` | Read a page | `cloudId`, `pageId`, `contentFormat: 'markdown'` | Page content as Markdown | -| `getConfluenceSpaces` | List spaces | `cloudId`, optional filters | Spaces with IDs and keys | -| `getPagesInConfluenceSpace` | List pages in a space | `cloudId`, `spaceId`, optional `title` filter | Pages in space | -| `getConfluencePageDescendants` | List child pages | `cloudId`, `pageId`, optional `depth`, `limit` | Descendant pages | -| `createConfluenceFooterComment` | Page-level comment | `cloudId`, `pageId`, `body` (Markdown) | Created comment | -| `createConfluenceInlineComment` | Inline text comment | `cloudId`, `pageId`, `body` (Markdown), `inlineCommentProperties` | Created comment | - -## Cross-Product Tools - -| Tool | When | Key Params | Returns | -|------|------|------------|---------| -| `getAccessibleAtlassianResources` | First call — obtain cloudId | none | Cloud sites with UUIDs | -| `atlassianUserInfo` | Get current user's account ID | none | User details with account ID | -| `search` (Rovo) | Broad natural-language search across Jira + Confluence | `query` | Results with ARIs | -| `fetch` | Retrieve full details by ARI | `id` (ARI from search) | Full entity details | - -## Common CQL Patterns - -- `title ~ "keyword" AND type = page` -- `space = SPACEKEY AND label = "label"` -- `ancestor = pageId` diff --git a/meta/resources/05-workflow-state-format.md b/meta/resources/05-workflow-state-format.md deleted file mode 100644 index 515ae8d1..00000000 --- a/meta/resources/05-workflow-state-format.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: workflow-state-format -version: 3.0.0 ---- - -# Workflow State File Format - -Schema reference for the `workflow-state.toon` file written to `{planning_folder_path}/workflow-state.toon` by the `save_state` MCP tool. Agents do NOT read or write this file directly — they call `save_state` and `restore_state`, which handle serialization, encryption, and schema validation. - -## Top-Level (`StateSaveFile`) - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `id` | string | yes | Unique save identifier (UUID or prefixed ID) | -| `savedAt` | ISO 8601 | yes | Timestamp of this save | -| `description` | string | no | Human-readable save point description | -| `workflowId` | string | yes | Workflow ID (e.g., `work-package`) | -| `workflowVersion` | string | yes | Workflow version | -| `planningFolder` | string | yes | Absolute path to the planning folder | -| `sessionToken` | string | yes | Opaque HMAC-signed session token. Both orchestrator and worker share this token; session identity is embedded within it. | -| `sessionTokenEncrypted` | boolean | yes | Whether the token is encrypted | -| `state` | object | yes | Nested execution state — see below | - -## `state` Object - -`currentActivity` is **not** stored here; it is encoded in the opaque `sessionToken` and retrieved via `get_workflow_status`. - -| Field | Type | Description | -|-------|------|-------------| -| `stateVersion` | integer | Monotonically increasing sequence number | -| `startedAt` | ISO 8601 | When execution started | -| `updatedAt` | ISO 8601 | Most recent state change | -| `currentStep` | integer | Current step index (1-based) | -| `completedActivities` | string[] | Activity IDs completed in order | -| `skippedActivities` | string[] | Activity IDs skipped | -| `completedSteps` | object | Map of activity ID → completed step indices (1-based) | -| `checkpointResponses` | object | Checkpoint responses keyed by `activityId-checkpointId` | -| `decisionOutcomes` | object | Automated decision branches keyed by `activityId-decisionId` | -| `activeLoops` | array | Stack of executing loops (innermost last) | -| `variables` | object | Current workflow variable values | -| `history` | array | Chronological execution event log | -| `status` | string | `running`, `paused`, `suspended`, `completed`, `aborted`, `error` | -| `triggeredWorkflows` | array | Child workflows triggered from this one | -| `parentWorkflow` | object | Reference to parent workflow (if triggered) | - -## Stale Token Handling - -On resume, the orchestrator calls `start_session({ session_token: saved_token })`. The server returns one of: - -- **Normal**: HMAC verified — payload preserved; agent continues with restored state in memory. -- **`adopted: true`**: HMAC failed (server restarted with a new key) BUT the payload was structurally valid — server re-signed and returned a fresh token; state preserved. -- **`recovered: true`**: HMAC failed AND payload corrupted — server returned a fresh session. State must be reconstructed via `restore_state({ session_token, file_path })` to load variables from this state file. - -## Persistence Tools - -`save_state` and `restore_state` are MCP tools — refer to the API reference for parameters and return shape. Agents MUST NOT bypass these tools to read or write the state file directly; doing so skips path validation, encryption-flag handling, and schema validation. diff --git a/meta/resources/README.md b/meta/resources/README.md index af54eeb7..2966e85d 100644 --- a/meta/resources/README.md +++ b/meta/resources/README.md @@ -2,7 +2,9 @@ > Part of the [Meta Workflow](../README.md) -Six markdown resources providing the bootstrap navigation primer, prompt templates for sub-agent dispatch, and reference documentation for the universal skills. +Markdown resources providing the bootstrap navigation primer and prompt templates for sub-agent dispatch. + +Tool reference content for Atlassian, GitNexus, and state management has moved into the corresponding capability skills' operations under v5 of the meta workflow — each operation declares its own `tools` block and any `prose` reference content. --- @@ -10,12 +12,17 @@ Six markdown resources providing the bootstrap navigation primer, prompt templat | Index | Resource | Purpose | Used By | |-------|----------|---------|---------| -| `00` | [Bootstrap Protocol](00-bootstrap-protocol.md) | Pre-session navigation primer — load schemas, then `start_session({ workflow_id: "meta" })`. Bootstrap does NOT identify targets, scan saved sessions, or branch on resume — those run as meta activities | The agent at a blank-slate prompt | -| `01` | [Activity Worker Prompt](01-activity-worker-prompt.md) | Template prompt for spawning an activity-worker sub-agent (substitution variables: `workflow_id`, `activity_id`, `session_token`, `agent_id`) | [`workflow-orchestrator`](../skills/10-workflow-orchestrator.toon) — `dispatch-activity` phase | -| `02` | [Workflow Orchestrator Prompt](02-workflow-orchestrator-prompt.md) | Template prompt for spawning a workflow-orchestrator sub-agent (substitution variables: `workflow_id`, `session_token`, `agent_id`) | [Dispatch Client Workflow](../activities/README.md#03-dispatch-client-workflow) — `compose-orchestrator-prompt` step | -| `03` | [GitNexus Reference](03-gitnexus-reference.md) | Checklists, pattern tables, examples, and CLI commands for GitNexus workflows (explore, impact, debug, refactor) | [`gitnexus-operations`](../skills/07-gitnexus-operations.toon) | -| `04` | [Atlassian Tools](04-atlassian-tools.md) | Complete reference for Atlassian MCP server tools (Jira and Confluence) — parameters, when-to-use, and return shapes | [`atlassian-operations`](../skills/06-atlassian-operations.toon) | -| `05` | [Workflow State Format](05-workflow-state-format.md) | Schema reference for `workflow-state.toon` — the file `save_state` and `restore_state` operate on. Top-level fields, state-object fields, stale-token handling | [`state-management`](../skills/02-state-management.toon), [`activity-worker`](../skills/09-activity-worker.toon), [`workflow-orchestrator`](../skills/10-workflow-orchestrator.toon) | +| `00` | [Bootstrap Protocol](00-bootstrap-protocol.md) | Pre-session navigation primer — load schemas, then `start_session({ workflow_id: "meta" })`. | The agent at a blank-slate prompt | +| `01` | [Activity Worker Prompt](01-activity-worker-prompt.md) | Template prompt for spawning an activity-worker sub-agent | `workflow-engine::dispatch-activity` and the legacy workflow-orchestrator skill | +| `02` | [Workflow Orchestrator Prompt](02-workflow-orchestrator-prompt.md) | Template prompt for spawning a workflow-orchestrator sub-agent | Meta dispatch-client-workflow activity | + +### Removed in v5 + +| Index | Resource | Where the content lives now | +|-------|----------|---------------------------| +| `03` | GitNexus Reference | Inlined into [`gitnexus-operations`](../skills/07-gitnexus-operations.toon) operations | +| `04` | Atlassian Tools | Inlined into [`atlassian-operations`](../skills/06-atlassian-operations.toon) operations | +| `05` | Workflow State Format | State persistence is now agent-managed (no schema resource needed) | --- @@ -27,20 +34,6 @@ Any workflow can load these resources via: get_resource({ session_token, resource_id: "meta/00" }) // Bootstrap protocol get_resource({ session_token, resource_id: "meta/01" }) // Activity worker prompt get_resource({ session_token, resource_id: "meta/02" }) // Workflow orchestrator prompt -get_resource({ session_token, resource_id: "meta/03" }) // GitNexus reference -get_resource({ session_token, resource_id: "meta/04" }) // Atlassian tools -get_resource({ session_token, resource_id: "meta/05" }) // Workflow state format ``` -Skills declare lightweight `_resources` array entries (e.g., `"meta/03"`) — the loader returns these as references; full content is fetched on demand via `get_resource`. - ---- - -## Why these resources are not skills - -Resources are markdown reference material consumed by agents at runtime. Skills are TOON definitions that encode protocol, rules, tools, and errors. The split is: - -- **Skill** owns the procedural decisions and behavioural rules. -- **Resource** owns the lookup tables, examples, and large reference content the skill calls out to. - -Conceptual guides that previously duplicated the docs (`activity-worker-guide`, `workflow-orchestrator-guide`) were removed in v4.0.0 — the docs in [docs/](../../../docs/) are the authoritative conceptual reference, and skills carry the procedural truth. +Skills declare lightweight `_resources` array entries (e.g., `"meta/activity-worker-prompt"`) — the loader returns these as references; full content is fetched on demand via `get_resource`. diff --git a/meta/skills/00-session-protocol.toon b/meta/skills/00-session-protocol.toon deleted file mode 100644 index d60756b7..00000000 --- a/meta/skills/00-session-protocol.toon +++ /dev/null @@ -1,28 +0,0 @@ -id: session-protocol -version: 1.1.0 -capability: Govern session lifecycle — token handling, step manifests, checkpoint token discipline, resource usage, and skill loading - -description: "Cross-cutting skill defining the protocol for workflow sessions. Covers session token mechanics (passing, updating, opacity), checkpoint token discipline (checkpoint_handle vs session_token), step manifest requirements for activity transitions, resource consumption patterns, and the bootstrap sequence for loading skills." - -protocol: - token-management[5]: - - "CRITICAL: EVERY tool call requires a session_token parameter. For fresh sessions, call start_session({ workflow_id, agent_id }) to create a session for the target workflow directly. For resuming, call start_session({ session_token: saved_token, agent_id }) to adopt the existing session. Do NOT default to 'meta' — specify the target workflow_id explicitly." - - "Use the updated session_token from each response for the next call. Tokens are returned both in the response body and in _meta.session_token. ALWAYS prefer the token from the most recent response — do not reuse a token from an earlier call in the same session." - - "TOKEN SUCCESSION: Each tool call that accepts a session_token returns a NEW token in its response. The old token is consumed and MUST NOT be reused. If you call two tools sequentially, the second call MUST use the token returned by the first call — not the token you passed to the first call. Failure to follow token succession causes HMAC signature verification failures." - - "STALE TOKEN RECOVERY: If any tool call returns 'HMAC signature verification failed', the server has restarted and generated a new signing key. Do NOT retry with the same token. Instead: call start_session({ workflow_id, agent_id }) to get a fresh session for the target workflow, then reconstruct state by transitioning to the correct activity." - - "Token-exempt tools: discover, list_workflows, start_session, and health_check do not require a session token." - checkpoint-token-discipline[4]: - - "CHECKPOINT TOKENS ARE DISTINCT FROM SESSION TOKENS. yield_checkpoint returns a checkpoint_handle — an HMAC-signed token string (contains a '.' separator) that encodes the checkpoint state. This is NOT the same as the checkpoint_id (a short name like 'classification-confirmed')." - - "present_checkpoint and respond_checkpoint take a checkpoint_handle parameter, NOT a session_token. Never pass your session_token or checkpoint_id as the checkpoint_handle." - - "yield_checkpoint and resume_checkpoint take a session_token parameter. For resume_checkpoint, pass the checkpoint_handle as the session_token value (the checkpoint_handle IS the worker's advanced session token with the checkpoint encoded)." - - "If you receive 'Invalid session token' or 'missing signature' errors from present_checkpoint or respond_checkpoint, you are passing the wrong value as checkpoint_handle — use the exact string returned by yield_checkpoint in the checkpoint_handle field of the response." - validation[1]: - - "Check _meta.validation in each response for warnings. Warnings indicate inconsistencies (workflow mismatch, invalid transition, version drift, missing step manifest) and should be addressed but do not block execution." - step-manifests[2]: - - "STEP MANIFEST: When transitioning to the next activity (calling next_activity({ session_token, activity_id, step_manifest })), include a step_manifest parameter listing each step completed in the previous activity with its output summary." - - "STEP COMPLETENESS: All steps within an activity are required. Optionality is handled at the activity level (via transition conditions), not at the step level." - resource-usage[1]: - - "RESOURCE LOADING: Skills return _resources as lightweight references (index, id, version — no content). Call get_resource({ session_token, resource_id }) with the index from the _resources array (e.g., '07' for a bare local index, 'meta/01' for a cross-workflow reference) to load the full content. When a step says 'use attached resource XX', find the matching entry in _resources and call get_resource." - -resources[1]: - - "meta/00" diff --git a/meta/skills/00-workflow-engine.toon b/meta/skills/00-workflow-engine.toon new file mode 100644 index 00000000..3e38e36e --- /dev/null +++ b/meta/skills/00-workflow-engine.toon @@ -0,0 +1,387 @@ +id: workflow-engine +version: 5.1.0 +capability: Operations and rules for workflow execution — session lifecycle, state persistence, activity dispatch, transition evaluation, checkpoint flow + +description: "Capability skill bundling everything needed to execute a workflow's structured flow. Operations cover session token mechanics (implicit), state persistence (persist/restore), activity dispatch and transition evaluation, the post-activity commit-and-persist hook, sub-workflow handling, and the full checkpoint protocol (yield, bubble, present-to-user, respond, resume). Rules cover token mechanics, checkpoint discipline, state-mutation invariants, and orchestrator/worker behavioural boundaries. Each operation is a short linear procedure invoking a small set of MCP / harness / shell tools." + +operations: + list-workflows: + description: "Retrieve the catalog of available workflows" + output[1]: + - catalog: "Array of { id, title, description, tags } entries" + procedure[1]: + - "Call list_workflows" + tools: + workflow-server[1]: + - list_workflows + + match-target-workflow: + description: "Match a user request against the workflow catalog and surface ambiguity" + inputs[2]: + - user_request: "User's free-form request" + - catalog: "Array of workflow entries from list-workflows" + output[2]: + - target_workflow_id: "Best-match workflow id, or null when no candidate matches" + - ambiguous: "true when more than one workflow matches with similar confidence" + procedure[1]: + - "Score each catalog entry against user_request by title, description keywords, and recognition tags; return the top match and set ambiguous when the top scores are close" + + extract-identifying-context: + description: "Extract ticket, branch, PR, and work-package identifiers from a user request" + inputs[1]: + - user_request: "User's free-form request" + output[1]: + - context: "Map of any identifiers found: { issue_number?, branch_name?, pr_number?, work_package? }" + procedure[1]: + - "Scan user_request for GitHub issue numbers (#N), Jira keys (PROJ-123), branch references, PR numbers, and work-package descriptions; collect any found into context" + + match-saved-session: + description: "Pick the saved-session candidate that best matches an identifying context" + inputs[2]: + - context: "Identifying context from extract-identifying-context" + - candidates: "Saved sessions from scan-saved-sessions" + output[1]: + - match: "Best matching candidate { sessionToken, planningFolder, savedAt }, or null when none match" + procedure[1]: + - "Score each candidate by overlap between its variables (issue_number, branch_name, pr_number, work-package description, planning-folder name) and context; pick the most recently-updated by savedAt on ties; return null when no candidate has any overlap" + + scan-saved-sessions: + description: "Find saved client sessions matching a target workflow under .engineering/artifacts/planning/" + inputs[1]: + - target_workflow_id: "Workflow ID to filter candidates by" + output[1]: + - candidates: "Array of { sessionToken, planningFolder, savedAt, variables } entries whose workflowId matches" + procedure[3]: + - "List directories under .engineering/artifacts/planning/" + - "For each directory, read its workflow-state.toon" + - "Keep entries whose workflowId equals target_workflow_id" + tools: + harness[1]: + - Read + + adopt-session: + description: "Adopt a saved session by passing the saved token to start_session" + inputs[1]: + - saved_session_token: "Token loaded from the saved workflow-state.toon (a workflow-engine VARIABLE, NOT an MCP parameter name)" + output[1]: + - session_token: "Adopted token (re-signed in place if the server restarted; sid, act, and variables preserved)" + procedure[3]: + - "Call MCP tool start_session with EXACTLY these named parameters: session_token = , agent_id = 'orchestrator'." + - "Do NOT pass workflow_id (the workflow is derived from the saved token's wf field). Do NOT pass parent_session_token. Do NOT invent a 'saved_session_token' parameter — that is a workflow-engine variable name, not an MCP parameter name. The MCP schema is strict and unknown keys are rejected." + - "On success the response includes adopted=true (and a re-sign warning if the server had restarted). Use the RETURNED session_token for all subsequent calls — never re-pass the original saved value to any other tool." + tools: + workflow-server[1]: + - start_session + errors: + strict_param_violation: + cause: "start_session returned 'Invalid arguments' / 'unrecognized_keys' because an unknown parameter name (e.g., 'saved_session_token') was passed instead of session_token" + recovery: "Re-issue start_session with the saved token bound to the session_token parameter, exactly as the procedure prescribes" + unrecoverable_token: + cause: "start_session reports the token payload is unrecoverable (corrupted beyond payload-only decoding)" + recovery: "Call start_session with parameters: workflow_id = , agent_id = 'orchestrator' (no session_token) for a fresh session, then reconstruct state from the on-disk workflow-state.toon via workflow-engine::restore" + rules: + strict-params: "start_session is the ONLY MCP tool that performs HMAC staleness recovery and the ONLY one that adopts a saved token. It is also strict-schema: unknown keys are rejected at the MCP boundary. Bind the saved_session_token VARIABLE to the session_token PARAMETER and pass nothing else." + no-recovery-elsewhere: "Other workflow tools (next_activity, get_workflow, get_resource, etc.) verify HMAC strictly with no recovery. NEVER pass a saved/disk token to them — always go through start_session first to obtain a freshly-signed token, then use that returned token everywhere else." + + create-session: + description: "Create a fresh client session as a child of the meta session" + inputs[2]: + - workflow_id: "Target client workflow id (e.g., 'work-package')" + - parent_session_token: "The meta session token currently held by the orchestrator (used as the parent context source)" + output[1]: + - session_token: "Newly minted child session token" + procedure[2]: + - "Call MCP tool start_session with EXACTLY these named parameters: workflow_id = , parent_session_token = , agent_id = 'orchestrator'." + - "Do NOT pass session_token (this is a fresh session, not an inherited one) and do NOT pass any other parameter. The schema is strict and unknown keys are rejected. Use the RETURNED session_token for all subsequent calls inside the child workflow." + tools: + workflow-server[1]: + - start_session + + compose-prompt: + description: "Substitute state variables into a prompt template resource" + inputs[2]: + - template_ref: "Resource ref for the prompt template (e.g., meta/workflow-orchestrator-prompt)" + - substitutions: "Map of placeholder name → value" + output[1]: + - prompt: "Composed prompt string" + procedure[2]: + - "Load the template via get_resource" + - "Replace each {placeholder} with its substitution value" + tools: + workflow-server[1]: + - get_resource + + extract-checkpoint-handle: + description: "Parse an orchestrator's most recent output to extract the checkpoint handle" + inputs[1]: + - output: "Orchestrator's most recent text output" + output[1]: + - checkpoint_handle: "The checkpoint_handle string when a block is present, otherwise null" + procedure[1]: + - "Find the ... block; parse its JSON body and return checkpoint_handle" + + handle-workflow-complete: + description: "Apply a workflow_complete result's final variables and mark the dispatched workflow finished" + inputs[1]: + - result: "The orchestrator's workflow_complete result with its variables_changed payload" + procedure[2]: + - "Apply variables_changed to the local state" + - "Set client_workflow_completed = true" + + verify-outcomes: + description: "Compare a workflow's declared outcome[] against state and identify gaps" + inputs[2]: + - outcome: "Array of expected outcome strings from the workflow definition" + - state: "Current variable state and completed-activities trace" + output[1]: + - gaps: "Array of unsatisfied outcomes" + procedure[1]: + - "For each outcome, evaluate satisfaction against state variables, artifact presence in planning_folder_path, and completed-activities trace; collect any unmet items" + + generate-summary: + description: "Compose the markdown session summary presented at workflow close" + inputs[2]: + - workflow: "Workflow definition (id, title, outcomes)" + - trace: "Completed activities, checkpoint decisions, artifacts produced" + output[1]: + - summary_markdown: "Markdown string ready to present to the user" + procedure[1]: + - "Compose sections: workflow id and title, start/completion timestamps, activities completed, key checkpoint decisions, artifacts with paths, outcomes satisfied vs. unmet, follow-up items" + + persist: + description: "Write the current session state to two files: workflow-state.json (slowly-changing variables, completed activities, history) and .session-token (the HMAC-signed token, which changes on every save). Splitting reduces diff noise on workflow-state.json — the high-churn token no longer dominates every state-change diff in code review." + inputs[3]: + - session_token: "The current session token" + - planning_folder_path: "Absolute path to the planning folder" + - state: "Current variable state, completed activities, and history to persist" + procedure[3]: + - "Compose the state envelope using ONLY the fields below — do not duplicate anything that is already encoded in the session token (workflowId/wf, currentActivity/act, agentId/aid, parent context/psid+pwf+pact+pv, workflowVersion/v) or already present inside variables (e.g., planning_folder_path)." + - "Write the JSON envelope to {planning_folder_path}/workflow-state.json via the harness Write tool. Required envelope shape (top-level): { stateVersion, savedAt, startedAt, state }. NOTE: sessionToken is NOT part of this envelope (see next step). The nested state object holds: { variables, completedActivities, skippedActivities, checkpointResponses, history, status }. Optional fields (omit when empty): activeLoops, triggeredWorkflows. EXAMPLE: {\"stateVersion\":5,\"savedAt\":\"2026-04-28T10:00:00Z\",\"startedAt\":\"2026-04-27T16:12:00Z\",\"state\":{\"variables\":{\"issue_number\":\"307\",\"planning_folder_path\":\"/abs/path\"},\"completedActivities\":[\"start-work-package\",\"design-philosophy\"],\"skippedActivities\":[\"requirements-elicitation\"],\"checkpointResponses\":{\"design-philosophy-classification-confirmed\":\"confirmed\"},\"history\":[{\"timestamp\":\"2026-04-27T16:12:00Z\",\"event\":\"session_created\"}],\"status\":\"running\"}}" + - "Write the raw session token (single line, no JSON wrapper, no quotes) to {planning_folder_path}/.session-token via the harness Write tool. Overwrite on every save. This is the ONLY token-bearing file; do NOT also embed the token inside workflow-state.json." + tools: + harness[1]: + - Write + rules: + state-format: "workflow-state.json is a plain-text JSON file with a fixed envelope. The session token lives in the sibling .session-token file (also plain text, single line). Both files are unencrypted; the token is HMAC-signed and self-authenticating." + token-in-sibling: "The HMAC-signed session token MUST live in {planning_folder_path}/.session-token, NOT inside workflow-state.json. This isolates the high-churn token from the slowly-changing state envelope so workflow-state.json diffs stay readable in code review and the token does not bloat git history." + no-token-duplication: "Do NOT write workflowId, workflowVersion, currentActivity, agentId, or parentWorkflow at the top level — these are already encoded in the session token (wf, v, act, aid, psid/pwf/pact/pv) and the server is the source of truth. Restore decodes them from the token." + no-derived-fields: "Do NOT write fields derivable from other persisted fields: currentStep (= completedActivities.length), updatedAt (= savedAt at the envelope level). Compute on read if a consumer needs them." + omit-empty-collections: "Omit empty maps/arrays from the file rather than writing {} or []. Exception: completedActivities and history are always present (possibly empty) so a fresh save is recognisable." + variables-canonical-home: "Domain state — including planning_folder_path, branch_name, issue_number, etc. — lives ONLY inside state.variables. Do not duplicate any variable at the envelope level." + + restore: + description: "Load saved state from a planning folder and resume via start_session token inheritance. The session token is read from the .session-token sibling file (current format) with a fallback to the legacy sessionToken field inside workflow-state.json for older planning folders." + inputs[2]: + - workflow_id: "The workflow ID to resume (informational; the canonical id is also encoded in the saved token's wf field)" + - file_path: "Absolute path to the workflow-state.json file (the sibling .session-token is read from the same directory)" + output[1]: + - session_token: "Resumed session token with inherited state (re-signed in place if the server restarted since the file was written)" + procedure[3]: + - "Read {dirname(file_path)}/.session-token into a variable named saved_session_token (single line, no parsing). If that file does not exist (legacy planning folders pre-split), fall back to reading workflow-state.json and extracting the sessionToken field. The token carries workflowId, workflowVersion, currentActivity, agentId, and any parent context — do not look for those at the envelope level." + - "Call MCP tool start_session with EXACTLY these named parameters: session_token = , agent_id = 'orchestrator'. workflow_id is unnecessary (it is derived from the token's wf field) and SHOULD NOT be passed; do not pass parent_session_token or any other key. The schema is strict and unknown keys are rejected — in particular do NOT pass a literal 'saved_session_token' key." + - "Use the RETURNED session_token for every subsequent MCP call. Never re-read the saved files and pass an old token to next_activity / get_workflow / get_resource — those tools do not perform staleness recovery." + tools: + harness[1]: + - Read + workflow-server[1]: + - start_session + + dispatch-activity: + description: "Transition the session to a target activity and spawn a worker for it" + inputs[3]: + - activity_id: "Activity ID to enter" + - prompt_template: "Resource ref for the worker prompt (e.g., meta/01)" + - state: "Current variable state for prompt substitution" + output[2]: + - worker_result: "{ type: 'checkpoint_pending', handle } or { type: 'activity_complete', ...payload }" + - trace_token: "Trace token captured from next_activity response, appended to trace_tokens" + procedure[3]: + - "Call next_activity({ session_token, activity_id, step_manifest }); capture _meta.trace_token" + - "Compose the worker prompt from prompt_template substituting state values" + - "harness-compat::spawn-agent with the composed prompt; await result" + tools: + workflow-server[1]: + - next_activity + resources[1]: + - "meta/activity-worker-prompt" + errors: + worker_timeout: + cause: "Worker sub-agent did not return within the expected time" + recovery: "harness-compat::continue-agent if still running; otherwise dispatch a fresh worker for the same activity_id." + worker_incomplete: + cause: "Worker reports fewer steps than the activity defines, or required checkpoints have no response" + recovery: "Resume the worker with explicit instructions to complete the missing items. Do NOT accept the partial result." + state_desync: + cause: "Worker reports variable changes conflicting with orchestrator state" + recovery: "Worker values take precedence (the worker has ground truth from user interaction)." + rules: + step-manifest-required: "When calling next_activity, 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." + reject-empty-checkpoints: "If an activity defines required checkpoints and the worker returns checkpoints_responded as empty, REJECT the result and resume the worker." + no-get-activity-from-orchestrator: "Workflow-orchestrators NEVER call get_activity. The activity definition is the worker's domain. Orchestrators need only the activity_id (from initialActivity or transitions) to call next_activity and compose the worker prompt." + no-pre-load-skills: "NEVER call get_skill or get_skills to pre-load skills. The worker self-bootstraps via get_activity, which bundles the operations the activity needs." + variable-mutation-source: "Variables mutate from two sources only: checkpoint option effects (setVariable) and worker activity_complete results (variables_changed). Never mutate state through ad-hoc reasoning." + + evaluate-transition: + description: "Pick the next activity from the current activity's transitions[]" + inputs[3]: + - activity: "Just-completed activity definition (with transitions[])" + - state: "Current variable state" + - transition_override: "Optional activity_id from a checkpoint effect transitionTo" + output[1]: + - next_activity_id: "Activity ID to dispatch next, or null if the workflow is complete" + procedure[3]: + - "If transition_override is set, return it" + - "Iterate activity.transitions[] in array order; return the first whose condition evaluates true" + - "If no condition matches and no isDefault transition exists, return null (workflow_complete)" + errors: + transition_ambiguous: + cause: "Multiple transition conditions evaluate to true at the activity boundary" + recovery: "Take the first matching transition in array order. Log a warning." + + commit-and-persist: + description: "Post-activity hook — commit source-side changes (target_path), persist state into the planning folder, then commit engineering artifacts (.engineering/artifacts/) including the freshly-written workflow-state.json in a single commit. Persist runs BETWEEN the two commits so workflow-state.json rides along with the activity's other artifacts; producing a separate state-persist commit doubles commit count without adding history value." + inputs[3]: + - activity_id: "Activity that just completed" + - planning_folder_path: "Path to the planning folder" + - target_path: "Path to the target submodule where source-side changes live (typically the application repo)" + procedure[3]: + - "If target_path has uncommitted changes (git status --porcelain non-empty), invoke version-control::commit-submodule with paths=changed files, submodule_message='(): source changes' (pick the Conventional Commits type that fits the activity — feat for implement, fix for post-impl-review fixes, refactor for cleanup, etc.), and parent_branch=current parent branch. Skip when the working tree is clean." + - "Invoke workflow-engine::persist with the current session_token and planning_folder_path. The resulting workflow-state.json (and its sibling .session-token) is staged in the SAME engineering commit as the activity's other artifacts in the next step — never as a separate commit." + - "Invoke version-control::commit-regular-files for ALL changes under .engineering/artifacts/ (including the workflow-state.json and .session-token just written by persist) with message 'docs(): artifacts'" + rules: + commit-after-activity: "After every completed activity, BOTH source-side changes (under target_path, via version-control::commit-submodule) AND engineering artifacts (under .engineering/artifacts/, via version-control::commit-regular-files) MUST be committed and pushed before evaluating transitions to the next activity. Skipping either scope leaves a dirty working tree that breaks resume and downstream activities (validate, strategic-review, submit-for-review). The submodule commit may be skipped only when target_path's working tree is clean." + persist-before-engineering-commit: "Persist runs BETWEEN the source commit and the engineering commit so workflow-state.json rides along in the same engineering commit as the activity's other artifacts. Producing a separate 'state persist' commit doubles commit count without adding history value. Skipping persist altogether makes the session unrecoverable on restart." + + handle-sub-workflow: + description: "Dispatch a child workflow with parent context" + inputs[2]: + - workflow_id: "Child workflow ID" + - parent_session_token: "Parent (current) session token" + output[1]: + - child_session_token: "New child session token" + procedure[2]: + - "Call MCP tool start_session with EXACTLY these named parameters: workflow_id = , parent_session_token = , agent_id = 'workflow-orchestrator'. Do NOT pass session_token (this is a child session, not an inherited one). The schema is strict and unknown keys are rejected." + - "harness-compat::spawn-agent for the child orchestrator with the new token in its prompt" + tools: + workflow-server[1]: + - start_session + + finalize-activity: + description: "Compile the activity_complete result after all steps, checkpoints, and artifacts are done" + inputs[3]: + - steps_completed: "Array of completed step entries" + - checkpoints_responded: "Array of checkpoint responses (option_id + effects)" + - artifacts_produced: "Array of artifact entries (id, name, path)" + output[1]: + - result: "{ result_type: 'activity_complete', steps_completed, checkpoints_responded, variables_changed, artifacts_produced, transition_override? }" + procedure[2]: + - "Update the planning folder's README.md Progress table for each artifact produced and the footer status" + - "Compile and return the activity_complete object; include transition_override if a checkpoint effect specified transitionTo" + + yield-checkpoint: + description: "Pause at a checkpoint and surface the handle" + inputs[1]: + - checkpoint_id: "ID of the checkpoint being yielded" + output[1]: + - emitted: " block containing only the checkpoint_handle" + procedure[3]: + - "Call yield_checkpoint({ session_token, checkpoint_id }); capture the returned checkpoint_handle" + - "Emit a block containing ONLY the checkpoint_handle" + - "STOP — make no further tool calls until the orchestrator resumes you" + tools: + workflow-server[1]: + - yield_checkpoint + rules: + checkpoint-handle-distinct-from-session: "yield_checkpoint returns a checkpoint_handle (HMAC-signed, contains '.'). present_checkpoint and respond_checkpoint take a checkpoint_handle parameter, NOT a session_token. Never substitute one for the other." + + resume-from-checkpoint: + description: "Continue execution after the orchestrator resolves a checkpoint" + inputs[2]: + - resumed_session_token: "Fresh session token (bcp cleared) returned by respond_checkpoint and threaded down through the orchestrator's resume prompt. This is NOT the yield-time checkpoint_handle — that handle still has bcp set and resume_checkpoint will reject it." + - effects: "Variable updates passed back by the orchestrator" + output[1]: + - session_token: "Advanced token to use for subsequent calls (get_activity, etc.)" + procedure[2]: + - "Call resume_checkpoint({ session_token: resumed_session_token }); capture the new session_token from the response and use it for every subsequent call" + - "Apply effects to local state and continue from the paused step" + tools: + workflow-server[1]: + - resume_checkpoint + errors: + checkpoint_still_active: + cause: "resume_checkpoint returned 'Cannot resume: Checkpoint is still active'" + recovery: "You passed the yield-time checkpoint_handle (bcp still set). Use the resumed_session_token from your resume prompt (the new token returned by respond_checkpoint), not the handle you yielded with." + hmac_failure: + cause: "resume_checkpoint or any subsequent call returned 'Invalid session token: HMAC signature verification failed'" + recovery: "The token in your resume prompt is the source of truth. Do not transcribe it from a tool-result display (which may be truncated) and do not reach back for an earlier session token from your context. Use the EXACT resumed_session_token your orchestrator just handed you." + rules: + resume-uses-post-respond-token: "resume_checkpoint requires a token whose bcp is cleared. The yield-time checkpoint_handle does NOT satisfy this — only the token returned in the response body of respond_checkpoint does. The orchestrator MUST thread that token down to you on resume." + + bubble-checkpoint-up: + description: "Forward a worker's checkpoint to the parent (meta) orchestrator without resolving it" + inputs[1]: + - checkpoint_handle: "Handle yielded by the worker" + output[1]: + - emitted: " block containing only the checkpoint_handle" + procedure[3]: + - "Receive the worker's block and extract the checkpoint_handle" + - "Emit a block containing the SAME checkpoint_handle (do not modify it)" + - "STOP — wait to be resumed by the parent with the resolved effects" + rules: + no-direct-interaction: "Sub-agent orchestrators NEVER prompt the user directly. Surface checkpoints by bubbling the worker's checkpoint_handle up unchanged." + + present-checkpoint-to-user: + description: "Load checkpoint details and present them to the user" + inputs[1]: + - checkpoint_handle: "HMAC-signed handle bubbled up from the worker" + output[1]: + - selection: "{ option_id, effects } — captured user response" + procedure[3]: + - "Call present_checkpoint({ checkpoint_handle }) and read the message + options" + - "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, 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." + - "Capture the user's option_id (or auto_advance / condition_not_met)" + tools: + workflow-server[1]: + - present_checkpoint + harness[1]: + - AskQuestion + errors: + invalid_checkpoint_handle: + cause: "present_checkpoint returned 'Invalid session token' or 'missing signature'" + recovery: "You are passing the wrong value as checkpoint_handle. Use the EXACT string returned by yield_checkpoint." + rules: + no-auto-resolution: "NEVER auto-resolve a checkpoint without first presenting it. auto_advance: true is only valid after AskQuestion has been shown to the user and the autoAdvanceMs timer has elapsed without a response. Skipping AskQuestion and going straight to a sleep + auto_advance is a protocol violation, even when the default option seems obvious from prior context or prior user input on a different checkpoint." + present-before-any-resolution: "present_checkpoint returning data is not the same as presenting to the user. Every checkpoint resolution path — option_id, auto_advance, or condition_not_met — MUST be preceded by an AskQuestion that displays the checkpoint's message and options. All checkpoints block; autoAdvanceMs is a fallback for when the user does not respond, not a license to skip the prompt." + apply-effects-immediately: "Apply the resolved effects to internal state on receipt, then pass them down to the orchestrator/worker." + checkpoint-handle-distinct-from-session: "present_checkpoint takes a checkpoint_handle parameter, NOT a session_token. The handle is the HMAC-signed token returned by yield_checkpoint (contains '.')." + + respond-checkpoint: + description: "Send the user's selection back to the server" + inputs[2]: + - checkpoint_handle: "Handle from present-checkpoint-to-user" + - resolution: "{ option_id } | { auto_advance: true } | { condition_not_met: true }" + output[2]: + - effects: "Variable updates returned by the server, to pass back down to the orchestrator/worker" + - resumed_session_token: "Fresh session token returned by the server with bcp cleared. This token (NOT the yield-time checkpoint_handle) MUST be passed back to the worker so it can resume — the original checkpoint_handle still has bcp set and any subsequent tool call with it is gated." + procedure[1]: + - "Call respond_checkpoint({ checkpoint_handle, ...resolution }); from the response, capture BOTH effects and the new checkpoint_handle field — that field is the resumed_session_token the worker needs" + tools: + workflow-server[1]: + - respond_checkpoint + errors: + invalid_checkpoint_handle: + cause: "respond_checkpoint returned 'Invalid session token' or 'missing signature'" + recovery: "You are passing the wrong value as checkpoint_handle. Use the EXACT string returned by yield_checkpoint." + rules: + no-option-hallucination: "If respond_checkpoint returns 'Invalid option', STOP. Call present_checkpoint on the same handle to retrieve valid options. Never guess." + thread-resumed-token: "The server returns a NEW token in the checkpoint_handle field of the response. Capture it as resumed_session_token and propagate it to the worker on resume. Failing to do so leaves the worker with its yield-time handle (bcp still set), and every subsequent tool call is gated by assertCheckpointsResolved." + +rules: + token-passes-on-each-call: "EVERY tool call (other than discover, list_workflows, start_session, health_check) requires a session_token parameter." + use-most-recent-token: "Each tool call returns a NEW token (in the response body and _meta.session_token). The next call MUST use that new token. Reusing a stale token causes HMAC verification failure." + token-is-opaque: "Treat the session token as an opaque string. NEVER parse, decode, or modify its contents. Session identity is embedded within the token; there is no separate session_id field." + validation-warnings: "Check _meta.validation in each response. Warnings are advisory but should be addressed." + resource-loading-via-tool: "Resource refs returned in operation bodies (e.g., 'meta/activity-worker-prompt') are lightweight pointers. Load full content via get_resource({ session_token, resource_id })." + staleness-recovery-only-via-start-session: "HMAC staleness recovery (re-signing a saved token after a server restart) is performed ONLY by start_session. No other workflow tool — next_activity, get_workflow, get_resource, get_skill, resolve_operations, yield/resume/respond_checkpoint — has a recovery path: they verify HMAC strictly and fail. When resuming a saved session, ALWAYS go through start_session first (binding the saved token to the session_token parameter); use the returned token for everything else. Never pass a saved/disk token directly to any tool other than start_session." + start-session-strict-params: "start_session has a strict input schema and rejects unknown keys (e.g., 'saved_session_token', 'token', 'sessionToken'). The valid parameters are exactly: workflow_id, parent_session_token, session_token, agent_id. Workflow VARIABLES with the same shorthand name (e.g., the saved_session_token variable) must be bound to the canonical PARAMETER (session_token) at the call site." + parameter-vs-variable: "Workflow operations describe input/output VARIABLES with their own names (e.g., saved_session_token). MCP tool calls take their own canonical PARAMETER names (e.g., session_token). When invoking an MCP tool, always bind variables to parameters explicitly — do not pass workflow variables under their workflow names as MCP parameters." diff --git a/meta/skills/01-agent-conduct.toon b/meta/skills/01-agent-conduct.toon index b7c85f3a..17faf4df 100644 --- a/meta/skills/01-agent-conduct.toon +++ b/meta/skills/01-agent-conduct.toon @@ -1,5 +1,5 @@ id: agent-conduct -version: 3.0.0 +version: 4.0.0 capability: Define agent behavioral boundaries for file sensitivity, communication, operational discipline, checkpoint resolution, and cross-cutting orchestrator constraints description: "Cross-cutting behavioral boundaries. Single source of truth for: file sensitivity, communication tone, attribution prohibition, code commentary, operational discipline, checkpoint discipline (worker / workflow-orchestrator / meta-orchestrator role split), and shared orchestrator-discipline rules (target-path scope, no-domain-work, automatic transitions, no ad-hoc interaction). Per-role skills reference these rules; they are not restated." @@ -25,13 +25,13 @@ rules: - "Workflow-orchestrators MUST NOT call respond_checkpoint. They bubble up the checkpoint_handle yielded by the worker to the meta-orchestrator." - "Meta-orchestrators use AskQuestion, present_checkpoint, and respond_checkpoint. No one else calls respond_checkpoint." - "Checkpoints are explicit user decision gates. The meta-orchestrator MUST NOT call respond_checkpoint with an option_id unless the user has explicitly selected that option. Never fabricate an option_id or auto-resolve." - operational-discipline[4]: - - "Domain-specific tools may ONLY be called from within a workflow activity whose skills declare the relevant capability. References in the user's request (URLs, issue keys) are context to preserve, not triggers for immediate API calls." - - "Do NOT read workflow resource files directly from disk — load resources via get_resource({ session_token, resource_id: '' }) where is a string from the skill's _resources array (e.g., '07' or 'meta/01'). NEVER pass a skill ID, step ID, or activity ID as resource_id." - - "CPU-intensive build commands (cargo build, cargo check, cargo test, cargo clippy, npm run build, and similar) MUST be prefixed with nice -n 19 to run at lowest CPU scheduling priority." + operational-discipline[3]: + - "Domain-specific tools may ONLY be invoked from operations bundled into the current activity or workflow response. References in the user's request (URLs, issue keys) are context to preserve, not triggers for immediate API calls." + - "Do NOT read workflow resource files directly from disk — load them via get_resource({ session_token, resource_id }) using the refs declared on operations (e.g., 'meta/activity-worker-prompt'). Resource ids are preferred; numeric indices ('meta/01') resolve for backward compatibility." - "cargo fmt is exempt from nice — it is fast and should run at normal priority." - orchestrator-discipline[4]: + orchestrator-discipline[5]: - "no-domain-work: The orchestrator (meta or workflow) MUST NOT execute activity steps, write code, review code, or produce artifacts. All domain work is delegated to the worker." + - "no-inline-on-resume: On resume, the orchestrator MUST dispatch every activity through workflow-engine::dispatch-activity (which spawns a worker sub-agent) — exactly as on a fresh start. Restored variables, a populated planning folder, prior artifacts visible in context, and a current_activity preserved in the session token are NOT licence to bypass dispatch and execute steps in the orchestrator's own context. Resume changes WHICH activity gets dispatched (current_activity, not initialActivity); it does not change WHETHER a worker is dispatched. The worker is responsible for detecting already-completed work from artifact presence and skipping accordingly — that discipline does not transfer to the orchestrator." - "target-path-scope: Branch creation, PR creation, and code commits MUST be performed inside the target_path directory (the submodule), NEVER in the parent monorepo. Planning artifact commits (.engineering/artifacts/) MUST be performed in the parent repo where that directory lives, on the current branch — do NOT create a new branch in the parent repo." - - "automatic-transitions: After an activity completes and artifacts are committed, the orchestrator MUST evaluate the transition table and immediately dispatch the next activity WITHOUT pausing for user confirmation. Transitions are deterministic — they are evaluated against state variables, not user prompts. Any pause between activities for user confirmation is a protocol violation." + - "automatic-transitions: After an activity completes, the orchestrator MUST evaluate the transition table and immediately dispatch the next activity WITHOUT pausing for user confirmation. Transitions are deterministic — they are evaluated against state variables, not user prompts. Any pause between activities for user confirmation is a protocol violation." - "no-ad-hoc-interaction: The orchestrator MUST NOT generate questions, solicit confirmation, or produce any output that waits for user input outside of checkpoint yields from the worker. The ONLY mechanism for user interaction is presenting checkpoint_pending yields. Summaries, status updates, and progress notes may be emitted as informational messages, but MUST NOT be phrased as questions or imply the user should respond before the workflow continues." diff --git a/meta/skills/02-state-management.toon b/meta/skills/02-state-management.toon deleted file mode 100644 index ff0f7863..00000000 --- a/meta/skills/02-state-management.toon +++ /dev/null @@ -1,26 +0,0 @@ -id: state-management -version: 4.0.0 -capability: Concept reference for workflow state mutation, persistence, and resume -description: "Concept-level skill for workflow state. Documents how variables mutate (checkpoint effects, worker outputs), the persist-after-activity invariant, and the server's adopted/recovered token semantics. State persistence uses the save_state and restore_state MCP tools — agents do NOT read or write workflow-state.toon directly. The file format is documented in resource meta/05." - -protocol: - variable-mutation[3]: - - "Variables mutate from two sources only: checkpoint option effects (setVariable in the checkpoint definition) and worker activity_complete results (variables_changed)." - - "The orchestrator applies effects to its internal state immediately on receiving them, then includes the updated values in subsequent worker dispatches." - - "NEVER mutate state through ad-hoc reasoning. State changes are deterministic — they come from explicit effects or explicit worker outputs." - persistence[3]: - - "After EVERY completed activity (post commit-artifacts), the workflow-orchestrator calls save_state({ session_token, planning_folder_path }) to write the current session token, variables, and trace tokens to {planning_folder_path}/workflow-state.toon." - - "This invariant is mandatory — skipping persist after an activity makes the session unrecoverable on the next restart." - - "save_state handles serialization, encryption, and schema validation. The agent provides only the inputs." - resume[3]: - - "On resume, the orchestrator calls start_session({ session_token: saved_token }) and inspects the response." - - "If adopted: true — the saved payload is intact; the server re-signed the token with its current key. Continue with the restored state in memory (already in the token)." - - "If recovered: true — the saved payload was corrupted; a fresh session was created. Call restore_state({ session_token, file_path }) to rebuild variables from the on-disk state file, then transition to the saved currentActivity." - -rules: - no-direct-file-io: "NEVER read or write workflow-state.toon directly. Use save_state and restore_state MCP tools — they enforce the schema, handle encryption, and gate path traversal." - token-is-opaque: "Treat the session token as an opaque string. NEVER parse, decode, or modify it. Session identity is embedded in the token." - persist-or-fail: "If save_state fails (disk full, permission denied), the activity transition MUST NOT proceed. State desync is a hard failure." - -resources[1]: - - "meta/05" diff --git a/meta/skills/02-version-control.toon b/meta/skills/02-version-control.toon new file mode 100644 index 00000000..2b72aad9 --- /dev/null +++ b/meta/skills/02-version-control.toon @@ -0,0 +1,114 @@ +id: version-control +version: 5.0.0 +capability: Initialize planning folders and commit artifacts in the parent repository or a submodule + +description: "Operations for version-control actions during workflow execution: planning-folder initialization, regular-directory commits, and the two-step submodule commit pattern. Rules guard destructive operations and conventional-commit hygiene. Activity-lifecycle invariants (when to commit) live in workflow-engine, not here." + +operations: + detect-repo-type: + description: "Determine whether the working directory is a regular repo or a submodule monorepo" + output[1]: + - is_monorepo: "true when .gitmodules exists at the repo root" + procedure[1]: + - "Run `test -f .gitmodules`; is_monorepo is true when the file exists, false otherwise" + tools: + shell[1]: + - test + + list-submodules: + description: "Read and parse .gitmodules to enumerate submodule paths" + output[1]: + - submodules: "Array of { path, name, url } entries" + procedure[1]: + - "Read .gitmodules; parse each [submodule \"name\"] section to extract path and url" + tools: + harness[1]: + - Read + + initialize-folder: + description: "Create a planning folder for a new workflow run under .engineering/artifacts/planning/" + inputs[1]: + - initiative_name: "Kebab-case identifier derived from the issue title or work-package description" + output[1]: + - planning_folder_path: "Absolute path to the created folder" + procedure[3]: + - "Compose path: .engineering/artifacts/planning/YYYY-MM-DD-{initiative_name}/" + - "mkdir -p the path" + - "Return the absolute path as planning_folder_path" + tools: + shell[1]: + - mkdir + errors: + no_folder_path: + cause: "Attempted to write an artifact without a planning folder" + recovery: "Run version-control::initialize-folder first" + + commit-regular-files: + description: "Stage, commit, and push files in a regular (non-submodule) directory of the parent repo" + inputs[3]: + - paths: "Array of file paths to stage (under .engineering/artifacts/, .engineering/AGENTS.md, .engineering/scripts/, etc.)" + - message: "Conventional Commits message (e.g., 'docs(work-package): activity-X artifacts')" + - branch: "Branch to push to (typically the current branch — do NOT create a new branch in the parent repo)" + procedure[3]: + - "git add {paths}" + - "git commit -s -m '{message}'" + - "git push origin {branch}" + tools: + shell[1]: + - git + errors: + uncommitted_changes: + cause: "Changes exist but the user has not requested a commit" + recovery: "Report the changes and wait for user direction" + destructive_operation: + cause: "Agent attempted a destructive git operation" + recovery: "Stop immediately. Ask for explicit user confirmation with clear consequences." + + commit-submodule: + description: "Two-step submodule commit: commit + push inside the submodule, then update the parent's submodule pointer" + inputs[4]: + - submodule_path: "Path of the submodule from the repo root (e.g., 'workflows', '.engineering/workflows')" + - paths: "Array of file paths inside the submodule" + - submodule_message: "Conventional Commits message for the submodule commit" + - parent_branch: "Branch to push the parent commit to" + procedure[7]: + - "Read {submodule_path}/AGENTS.md (when present). If it forbids Co-Authored-By, LLM attribution, or similar trailers, strip them from {submodule_message} BEFORE committing — fixing it after commit usually requires a force push, which this skill forbids." + - "cd {submodule_path}" + - "git add {paths} && git commit -s -m '{submodule_message}' && git push origin " + - "cd back to the repo root" + - "git add {submodule_path}" + - "git commit -s -m 'chore: update {submodule_path} submodule'" + - "git push origin {parent_branch}" + note: "The submodule push (step 2) MUST complete before the parent commit (step 5). Skipping step 5 leaves the parent pointing at the old submodule commit. Skipping the submodule push leaves the parent pointing at a commit that does not exist on the remote." + tools: + shell[1]: + - git + errors: + submodule-desync: + cause: "Parent points to a submodule commit that does not exist on the remote" + recovery: "cd into the submodule and push the missing commit, then verify the parent pointer resolves" + stale-pointer: + cause: "Submodule committed but parent pointer not updated" + recovery: "cd to repo root, git add the submodule path, commit, and push" + + identify-path-type: + description: "Determine whether a path is a regular directory or a git submodule before committing" + inputs[1]: + - path: "Path to inspect" + output[1]: + - kind: "'submodule' (mode 160000) or 'regular' (mode 040000)" + procedure[1]: + - "Run 'git ls-tree HEAD {path}' and read the mode prefix" + tools: + shell[1]: + - git + +rules: + no-destructive-ops: "NEVER run destructive or irreversible operations (force push to protected branches, hard resets) without explicit user request." + no-hook-skipping: "NEVER skip hooks (--no-verify, --no-gpg-sign) unless the user explicitly requests it." + explicit-commit: "NEVER commit changes unless the user explicitly asks. Verify the request before executing." + read-agents-md: "BEFORE committing engineering artifacts, ALWAYS read .engineering/AGENTS.md for the definitive git structure." + conventional-commits: "Follow Conventional Commits: type(optional-scope): description. Common types: feat, fix, docs, style, refactor, test, chore, build, ci. Reference issue numbers when applicable." + dco-sign-off: "All commits made via this skill use 'git commit -s'. The Signed-off-by trailer is required by DCO and harmless when not. Adding it by default avoids the failure-then-retry pattern when target repos enforce DCO via a pre-commit hook." + respect-submodule-agents: "commit-submodule MUST honour the SUBMODULE'S AGENTS.md authorial-trailer policy in addition to the parent's. When the submodule forbids Co-Authored-By or similar LLM-attribution trailers, strip them from {submodule_message} before invocation. Discovery, not retrofit — fixing it after commit usually requires a force push." + diff --git a/meta/skills/03-github-cli-protocol.toon b/meta/skills/03-github-cli-protocol.toon new file mode 100644 index 00000000..7e09585a --- /dev/null +++ b/meta/skills/03-github-cli-protocol.toon @@ -0,0 +1,83 @@ +id: github-cli-protocol +version: 3.0.0 +capability: Operations for GitHub CLI usage with GraphQL-deprecation workarounds + +description: "Operations for common GitHub PR/issue tasks. Mutating operations route through gh's REST API (gh api) because gh's GraphQL paths fail under Projects Classic deprecation. Read operations use the standard gh CLI." + +operations: + update-pr-description: + description: "Update the body of an existing PR via REST" + inputs[3]: + - owner: "Repo owner (e.g., 'm2ux')" + - repo: "Repo name" + - number: "PR number" + procedure[1]: + - "gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f body=" + tools: + shell[1]: + - gh + errors: + graphql-deprecation: + cause: "gh pr edit or similar GraphQL-based mutation command failed with the Projects Classic deprecation error" + recovery: "Use the equivalent REST API endpoint via gh api (as in this operation's procedure)" + + update-pr-title: + description: "Update the title of an existing PR via REST" + inputs[3]: + - owner: "Repo owner" + - repo: "Repo name" + - number: "PR number" + procedure[1]: + - "gh api repos/{owner}/{repo}/pulls/{number} -X PATCH -f title=" + tools: + shell[1]: + - gh + + add-labels: + description: "Add labels to an issue or PR via REST" + inputs[4]: + - owner: "Repo owner" + - repo: "Repo name" + - number: "Issue or PR number" + - labels: "Comma-separated label names" + procedure[1]: + - "gh api repos/{owner}/{repo}/issues/{number}/labels -X POST -f labels={labels}" + tools: + shell[1]: + - gh + + view-pr: + description: "View an existing PR (read-only — safe via gh CLI)" + inputs[1]: + - identifier: "PR number or URL" + procedure[1]: + - "gh pr view {identifier}" + tools: + shell[1]: + - gh + + list-prs: + description: "List PRs (read-only — safe via gh CLI)" + inputs[1]: + - filters: "Optional flags (e.g., '--state open --author @me')" + procedure[1]: + - "gh pr list {filters}" + tools: + shell[1]: + - gh + + list-issues: + description: "List issues (read-only — safe via gh CLI)" + inputs[1]: + - filters: "Optional flags (e.g., '--state open --label bug')" + procedure[1]: + - "gh issue list {filters}" + tools: + shell[1]: + - gh + +rules: + no-graphql-mutations: "Do NOT use gh CLI commands that mutate PRs/issues via GraphQL (e.g., gh pr edit) — they fail under Projects Classic deprecation. Use gh api with REST endpoints for all mutating operations." + read-ops-safe: "Read operations via gh CLI (gh pr view, gh pr list, gh issue list) are safe and preferred." + ask-before-replying: "Ask the user before replying to PR comments or review feedback." + diff --git a/meta/skills/03-version-control.toon b/meta/skills/03-version-control.toon deleted file mode 100644 index ab43af5e..00000000 --- a/meta/skills/03-version-control.toon +++ /dev/null @@ -1,69 +0,0 @@ -id: version-control -version: 3.0.0 -capability: Initialize planning folders and manage version control practices, including submodule artifacts -description: "Governs version control practices across the repository. Includes .engineering/artifacts/ lifecycle (creating planning folders), commit message conventions (Conventional Commits), branch management, and committing artifacts across regular directories and git submodules. Agents must read .engineering/AGENTS.md before committing to understand the git structure." - -inputs[1]: - - id: planning-base-path - description: "Base directory for planning artifacts" - default: ".engineering/artifacts/planning" - required: false - -protocol: - initialize-folder[4]: - - "Derive initiative-name from issue title or work package description (kebab-case)" - - "Create folder at .engineering/artifacts/planning/YYYY-MM-DD-{initiative-name}/" - - "Store planning_folder_path in context for use by other activities" - - "NEVER create planning documents directly in .engineering/artifacts/" - commit-workflow[4]: - - "Follow the Conventional Commits specification: type(optional-scope): description" - - "Common types: feat, fix, docs, style, refactor, test, chore, build, ci" - - "Reference issue numbers when applicable (e.g., 'feat: add search (#42)')" - - "Verify the user explicitly requested the commit before executing" - branch-workflow[4]: - - "Understand the project's branching strategy before creating branches" - - "Follow naming conventions for feature branches (e.g., type/issue-number-short-description)" - - "Keep branches focused on specific features or fixes" - - "Regularly sync with the main branch to avoid merge conflicts" - pre-commit[2]: - - "Verify the user explicitly requested the commit" - - "For Rust projects, run cargo fmt to format code before committing" - identify-path-type[2]: - - "Before committing, determine whether the path is a regular directory or a submodule" - - "Run 'git ls-tree HEAD <path>' — 160000 means submodule, 040000 means regular directory" - commit-regular-files[2]: - - "For .engineering/artifacts/, .engineering/AGENTS.md, .engineering/scripts/: git add <files> && git commit && git push" - - "These are regular files in the parent repo — no two-step workflow needed" - commit-submodule[5]: - - "Step 1: cd into the submodule (e.g., workflows/ or .engineering/workflows/) && git add <files> && git commit && git push origin <branch>" - - "Step 2: cd <repo-root> && git add <submodule-path> && git commit -m 'chore: update <submodule> submodule' && git push" - - "CRITICAL: The push in Step 1 MUST happen before the commit in Step 2." - - "If you skip Step 2, the parent still points to the old submodule commit" - - "If you skip Step 1's push, the parent points to a commit that does not exist on the remote" - -rules: - no-destructive-ops: "NEVER run destructive or irreversible operations (force push to protected branches, hard resets) without explicit user request." - no-hook-skipping: "NEVER skip hooks (--no-verify, --no-gpg-sign) unless the user explicitly requests it." - explicit-commit: "NEVER commit changes unless the user explicitly asks. Verify the request before executing." - commit-after-activity: "Engineering artifacts MUST be committed and pushed after each completed activity, before evaluating transitions to the next activity. The orchestrator is responsible for committing artifacts written by the worker." - read-agents-md: "BEFORE committing engineering artifacts, ALWAYS read .engineering/AGENTS.md for the definitive git structure." - -errors: - uncommitted_changes: - cause: "Changes exist but user hasn't requested a commit" - recovery: "Report the changes and wait for user direction" - destructive_operation: - cause: "Agent attempted a destructive git operation" - recovery: "Stop immediately. Ask for explicit user confirmation with clear explanation of consequences." - no_folder_path: - cause: "Attempting to create artifact without planning folder" - recovery: "Run initialize-folder steps first" - wrong_location: - cause: "Artifact created outside planning folder" - recovery: "Move document to correct location" - submodule-desync: - cause: "Parent points to a submodule commit that doesn't exist on the remote" - recovery: "cd into the submodule and push the missing commit, then verify the parent pointer resolves" - stale-pointer: - cause: "Submodule committed but parent pointer not updated" - recovery: "cd to repo root, git add the submodule path, commit, and push" diff --git a/meta/skills/04-github-cli-protocol.toon b/meta/skills/04-github-cli-protocol.toon deleted file mode 100644 index 292b5959..00000000 --- a/meta/skills/04-github-cli-protocol.toon +++ /dev/null @@ -1,26 +0,0 @@ -id: github-cli-protocol -version: 1.1.0 -capability: Enforce correct GitHub CLI usage patterns including GraphQL deprecation workarounds - -description: "Cross-cutting skill that governs how agents use the GitHub CLI (gh). Mutating operations on PRs and issues must use the REST API because gh commands that use GraphQL fail due to Projects Classic deprecation. Read operations via gh CLI are safe." - -protocol: - mutating-operations[3]: - - "Update PR description: gh api repos/OWNER/REPO/pulls/NUMBER -X PATCH -f body=CONTENT" - - "Update PR title: gh api repos/OWNER/REPO/pulls/NUMBER -X PATCH -f title=TITLE" - - "Add labels: gh api repos/OWNER/REPO/issues/NUMBER/labels -X POST -f labels=LABELS" - read-operations[3]: - - "gh pr view — safe for viewing PRs" - - "gh pr list — safe for listing PRs" - - "gh issue list — safe for listing issues" - user-approval[1]: - - "ALWAYS ask the user before replying to PR comments or review feedback" - -rules: - no-graphql-mutations: "Do not use gh CLI commands that mutate PRs/issues via GraphQL (e.g., gh pr edit) — they fail due to Projects Classic deprecation. Use gh api with REST endpoints for all mutating operations instead." - read-ops-safe: "Read operations via gh CLI (gh pr view, gh pr list, gh issue list) are safe and preferred." - -errors: - graphql-deprecation: - cause: "gh pr edit or similar GraphQL-based mutation command failed with Projects Classic deprecation error" - recovery: "Use the equivalent REST API endpoint via gh api instead" diff --git a/meta/skills/04-knowledge-base-search.toon b/meta/skills/04-knowledge-base-search.toon new file mode 100644 index 00000000..2a8d4510 --- /dev/null +++ b/meta/skills/04-knowledge-base-search.toon @@ -0,0 +1,62 @@ +id: knowledge-base-search +version: 3.0.0 +capability: Operations for targeted concept-rag searches via pre-indexed domain maps + +description: "Operations for searching the knowledge base. Domain indexes in .engineering/resources/ map natural terminology to indexed concept terms, reducing exploratory queries from 3-5 to 2 targeted ones." + +operations: + load-domain-index: + description: "Read the matching domain index file from .engineering/resources/" + inputs[1]: + - domain: "Domain hint (e.g., 'substrate', 'blockchain')" + output[1]: + - index: "Parsed source registry, concept lookup table, and topic clusters" + procedure[2]: + - "Locate {domain}-knowledge-index.md under .engineering/resources/" + - "Read the file and parse its source registry, concept table, and topic clusters" + tools: + harness[1]: + - Read + errors: + no_index_for_domain: + cause: "No knowledge index file found in .engineering/resources/ for the requested domain" + recovery: "Fall back to standard concept-rag search: catalog-search then chunks-search" + + catalog-search: + description: "Resolve a document name to its full source path" + inputs[1]: + - document_name: "Name from the index" + procedure[1]: + - "Call catalog_search({ name: document_name })" + tools: + concept-rag[1]: + - catalog_search + + chunks-search: + description: "Search within a known document by its resolved path" + inputs[2]: + - source_path: "Path returned by catalog-search" + - query: "Search query" + procedure[1]: + - "Call chunks_search({ source_path, query })" + tools: + concept-rag[1]: + - chunks_search + errors: + stale_index: + cause: "Knowledge base has been updated since the local index was created" + recovery: "If chunks-search returns no results for an indexed path, fall back to catalog-search to rediscover" + + broad-chunks-search: + description: "Search across documents using an indexed concept term" + inputs[1]: + - concept_term: "Mapped concept from the index" + procedure[1]: + - "Call broad_chunks_search({ concept: concept_term })" + tools: + concept-rag[1]: + - broad_chunks_search + errors: + no_mapping_for_term: + cause: "The local index does not contain a mapping for the search term" + recovery: "Use broad-chunks-search with the natural term; note the gap for future index updates" diff --git a/meta/skills/05-atlassian-operations.toon b/meta/skills/05-atlassian-operations.toon new file mode 100644 index 00000000..53641f32 --- /dev/null +++ b/meta/skills/05-atlassian-operations.toon @@ -0,0 +1,301 @@ +id: atlassian-operations +version: 3.0.0 +capability: Operations for Jira and Confluence tasks via the Atlassian MCP server + +description: "Operations for the common Jira and Confluence tasks. Each operation wraps one or two Atlassian MCP tools with explicit inputs and the tool reference inline. cloudId is resolved via resolve-cloud-id once per session and reused." + +operations: + resolve-cloud-id: + description: "Obtain the cloudId for the target Atlassian site" + output[1]: + - cloudId: "UUID of the cloud site, used by every product-specific tool" + procedure[1]: + - "Call getAccessibleAtlassianResources and use the first cloudId returned (or the one matching the user's site)" + tools: + atlassian[1]: + - getAccessibleAtlassianResources + errors: + missing_cloud_id: + cause: "A product-specific Atlassian tool was called without resolving cloudId first" + recovery: "Call resolve-cloud-id, then retry the original operation with the returned cloudId" + permission_denied: + cause: "User lacks permission for the requested operation" + recovery: "Verify Jira/Confluence permissions and project roles" + + user-info: + description: "Get the current user's account ID" + output[1]: + - accountId: "Current user's account ID" + procedure[1]: + - "Call atlassianUserInfo" + tools: + atlassian[1]: + - atlassianUserInfo + + lookup-jira-account-id: + description: "Resolve a name or email to a Jira account ID" + inputs[2]: + - cloudId: "From resolve-cloud-id" + - searchString: "Name or email to resolve" + procedure[1]: + - "Call lookupJiraAccountId({ cloudId, searchString })" + tools: + atlassian[1]: + - lookupJiraAccountId + + search-jira-issues: + description: "Search Jira issues with JQL" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - jql: "JQL query string" + - fields: "Optional array of fields to return" + procedure[1]: + - "Call searchJiraIssuesUsingJql({ cloudId, jql, fields, maxResults })" + tools: + atlassian[1]: + - searchJiraIssuesUsingJql + + list-jira-projects: + description: "Discover Jira projects with their issue types" + inputs[1]: + - cloudId: "From resolve-cloud-id" + procedure[1]: + - "Call getVisibleJiraProjects({ cloudId, searchString? })" + tools: + atlassian[1]: + - getVisibleJiraProjects + + list-jira-issue-types: + description: "List issue types available in a project" + inputs[2]: + - cloudId: "From resolve-cloud-id" + - projectIdOrKey: "Project key (e.g., 'ENG')" + procedure[1]: + - "Call getJiraProjectIssueTypesMetadata({ cloudId, projectIdOrKey })" + tools: + atlassian[1]: + - getJiraProjectIssueTypesMetadata + + list-jira-issue-fields: + description: "Discover the fields for a specific issue type in a project" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - projectIdOrKey: "Project key" + - issueTypeId: "Issue type ID from list-jira-issue-types" + procedure[1]: + - "Call getJiraIssueTypeMetaWithFields({ cloudId, projectIdOrKey, issueTypeId })" + tools: + atlassian[1]: + - getJiraIssueTypeMetaWithFields + + create-jira-issue: + description: "Create a new Jira issue" + inputs[5]: + - cloudId: "From resolve-cloud-id" + - projectKey: "Project key" + - issueTypeName: "Issue type name from list-jira-issue-types" + - summary: "Issue summary" + - additional_fields: "Optional object with description, assignee, labels, etc." + output[1]: + - issueKey: "Created issue key (e.g., 'ENG-123')" + procedure[1]: + - "Call createJiraIssue({ cloudId, projectKey, issueTypeName, summary, description?, additional_fields? })" + tools: + atlassian[1]: + - createJiraIssue + errors: + invalid_issue_type: + cause: "create-jira-issue called with a non-existent issueTypeName" + recovery: "Call list-jira-issue-types to discover valid types, then retry" + + edit-jira-issue: + description: "Update fields on an existing Jira issue" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + - fields: "Object of field updates" + procedure[1]: + - "Call editJiraIssue({ cloudId, issueIdOrKey, fields })" + tools: + atlassian[1]: + - editJiraIssue + + get-jira-issue: + description: "Read a single Jira issue" + inputs[2]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + procedure[1]: + - "Call getJiraIssue({ cloudId, issueIdOrKey })" + tools: + atlassian[1]: + - getJiraIssue + + list-jira-transitions: + description: "Discover available status transitions for an issue" + inputs[2]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + procedure[1]: + - "Call getTransitionsForJiraIssue({ cloudId, issueIdOrKey })" + tools: + atlassian[1]: + - getTransitionsForJiraIssue + + transition-jira-issue: + description: "Move an issue to a new status" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + - transition: "Transition object with id from list-jira-transitions" + procedure[1]: + - "Call transitionJiraIssue({ cloudId, issueIdOrKey, transition })" + tools: + atlassian[1]: + - transitionJiraIssue + errors: + transition_not_available: + cause: "transition-jira-issue called with a transition id that is not available for the current issue state" + recovery: "Call list-jira-transitions to get the available transitions and retry with one of those ids" + + comment-jira-issue: + description: "Add a comment to a Jira issue" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + - commentBody: "Markdown comment body" + procedure[1]: + - "Call addCommentToJiraIssue({ cloudId, issueIdOrKey, commentBody })" + tools: + atlassian[1]: + - addCommentToJiraIssue + + log-work-jira-issue: + description: "Log work time on a Jira issue" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - issueIdOrKey: "Issue key" + - timeSpent: "e.g., '2h', '30m'" + procedure[1]: + - "Call addWorklogToJiraIssue({ cloudId, issueIdOrKey, timeSpent })" + tools: + atlassian[1]: + - addWorklogToJiraIssue + + search-confluence: + description: "Search Confluence content with CQL" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - cql: "CQL query string" + - limit: "Optional result limit" + procedure[1]: + - "Call searchConfluenceUsingCql({ cloudId, cql, limit?, cursor? })" + tools: + atlassian[1]: + - searchConfluenceUsingCql + + create-confluence-page: + description: "Create a Confluence page" + inputs[5]: + - cloudId: "From resolve-cloud-id" + - spaceId: "Target space ID" + - body: "Markdown body" + - title: "Page title (optional)" + - parentId: "Optional parent page ID" + procedure[1]: + - "Call createConfluencePage({ cloudId, spaceId, body, contentFormat: 'markdown', title?, parentId? })" + tools: + atlassian[1]: + - createConfluencePage + + update-confluence-page: + description: "Update a Confluence page (full body replace)" + inputs[4]: + - cloudId: "From resolve-cloud-id" + - pageId: "Page ID" + - body: "New Markdown body" + - title: "Optional new title" + procedure[1]: + - "Call updateConfluencePage({ cloudId, pageId, body, title? })" + tools: + atlassian[1]: + - updateConfluencePage + + get-confluence-page: + description: "Read a Confluence page as Markdown" + inputs[2]: + - cloudId: "From resolve-cloud-id" + - pageId: "Page ID" + procedure[1]: + - "Call getConfluencePage({ cloudId, pageId, contentFormat: 'markdown' })" + tools: + atlassian[1]: + - getConfluencePage + + list-confluence-spaces: + description: "List spaces accessible to the current user" + inputs[1]: + - cloudId: "From resolve-cloud-id" + procedure[1]: + - "Call getConfluenceSpaces({ cloudId, ...filters })" + tools: + atlassian[1]: + - getConfluenceSpaces + + list-confluence-pages-in-space: + description: "List pages in a Confluence space" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - spaceId: "Space ID" + - title: "Optional title filter" + procedure[1]: + - "Call getPagesInConfluenceSpace({ cloudId, spaceId, title? })" + tools: + atlassian[1]: + - getPagesInConfluenceSpace + + list-confluence-page-descendants: + description: "List child pages of a Confluence page" + inputs[4]: + - cloudId: "From resolve-cloud-id" + - pageId: "Page ID" + - depth: "Optional traversal depth" + - limit: "Optional result limit" + procedure[1]: + - "Call getConfluencePageDescendants({ cloudId, pageId, depth?, limit? })" + tools: + atlassian[1]: + - getConfluencePageDescendants + + comment-confluence-page-footer: + description: "Add a page-level (footer) comment to a Confluence page" + inputs[3]: + - cloudId: "From resolve-cloud-id" + - pageId: "Page ID" + - body: "Markdown body" + procedure[1]: + - "Call createConfluenceFooterComment({ cloudId, pageId, body })" + tools: + atlassian[1]: + - createConfluenceFooterComment + + comment-confluence-page-inline: + description: "Add an inline (in-text) comment to a Confluence page" + inputs[4]: + - cloudId: "From resolve-cloud-id" + - pageId: "Page ID" + - body: "Markdown body" + - inlineCommentProperties: "Object describing the inline anchor" + procedure[1]: + - "Call createConfluenceInlineComment({ cloudId, pageId, body, inlineCommentProperties })" + tools: + atlassian[1]: + - createConfluenceInlineComment + +rules: + resolve-cloud-id-once: "Call resolve-cloud-id ONCE per session and cache the cloudId. Every product-specific operation requires it." + content-format-markdown: "Set contentFormat to 'markdown' for Confluence create/update/read operations." + account-id-for-users: "User fields require account IDs. Use lookup-jira-account-id (or user-info for the current user) to resolve names/emails." + transitions-are-dynamic: "ALWAYS call list-jira-transitions before transition-jira-issue — transition IDs are issue-specific." + verify-after-mutation: "After any mutating operation, call the corresponding read operation (e.g., get-jira-issue, get-confluence-page) to verify the change." + diff --git a/meta/skills/05-knowledge-base-search.toon b/meta/skills/05-knowledge-base-search.toon deleted file mode 100644 index 1b61d17c..00000000 --- a/meta/skills/05-knowledge-base-search.toon +++ /dev/null @@ -1,49 +0,0 @@ -id: knowledge-base-search -version: 1.2.0 -capability: Optimise knowledge base searches by loading a pre-indexed domain map before querying concept-rag - -description: "This skill reduces concept-rag tool calls from 3-5 exploratory calls down to 2 targeted calls. Agents load a domain knowledge index from the local project's .engineering/resources/ directory, then use the pre-mapped source paths, concept terms, and search strategies to make a single targeted query. Domain indexes bridge the gap between natural terminology and the indexed concept strings in concept-rag." - -inputs[2]: - - id: search-topic - description: "The topic or question the agent needs to find in the knowledge base" - - id: domain-hint - description: "Optional domain hint to select the correct index resource (e.g., substrate, blockchain)" - required: false - -protocol: - identify-domain[2]: - - Determine the domain from the search topic or domain-hint input - - "Match domain to an available knowledge index file in .engineering/resources/ (e.g., substrate-knowledge-index.md)" - load-index[4]: - - "Read the matched index file from .engineering/resources/ using the Read tool" - - Parse the source registry, concept lookup table, and topic clusters - - Identify the document names and mapped concept terms relevant to the search topic - - "Domain knowledge indexes are stored as markdown files in the project's .engineering/resources/ directory" - execute-targeted-search[4]: - - "Use catalog_search with the document name from the index to resolve the full source path" - - "Use chunks_search with the resolved source path when searching within a known document" - - "Use broad_chunks_search with the mapped concept term when searching across documents" - - "Fall back to catalog_search only when the index has no mapping for the topic" - synthesize-results[2]: - - Combine search results with the context provided by the index (related concepts, topic cluster) - - Present findings with source citations - -output[1]: - - id: search-results - description: "Targeted knowledge base search results with source citations" - components: - findings: "Content retrieved from concept-rag using the indexed search strategy" - sources: "Source documents and paths used" - related_concepts: "Related concepts from the index that may warrant follow-up" - -errors: - no_index_for_domain: - cause: "No knowledge index file found in .engineering/resources/ for the requested domain" - recovery: "Fall back to standard concept-rag search: catalog_search then chunks_search" - no_mapping_for_term: - cause: The index does not contain a mapping for the search term - recovery: "Use broad_chunks_search with the natural term; note the gap for future index updates" - stale_index: - cause: Knowledge base has been updated since the index was created - recovery: "If chunks_search returns no results for an indexed path, fall back to catalog_search to rediscover" diff --git a/meta/skills/06-atlassian-operations.toon b/meta/skills/06-atlassian-operations.toon deleted file mode 100644 index ba0a7404..00000000 --- a/meta/skills/06-atlassian-operations.toon +++ /dev/null @@ -1,54 +0,0 @@ -id: atlassian-operations -version: 1.1.0 -capability: Perform common Atlassian Jira and Confluence operations via the Atlassian MCP server -description: "Guides agents through the correct sequence of Atlassian MCP tool calls. Most tools require a cloudId from getAccessibleAtlassianResources. Covers Jira issue lifecycle, Confluence page lifecycle, and cross-product search. Use attached resource meta/04 for the complete tool parameter reference." - -inputs[2]: - - id: operation-type - description: "The Atlassian operation to perform (e.g., create-jira-issue, search-confluence)" - - id: operation-context - description: "Context: project key, issue key, space ID, page ID, search query, etc." - -protocol: - resolve-cloud-id[2]: - - "Call getAccessibleAtlassianResources to obtain the cloudId for the target site" - - "Cache the cloudId for subsequent calls in the same session" - identify-operation[3]: - - "Match the request to an operation: jira-search, jira-create, jira-update, jira-transition, jira-comment, confluence-search, confluence-create, confluence-update, rovo-search" - - "For search: use Rovo for broad natural-language queries, JQL/CQL for precise filtering" - - "For create/update: gather required metadata first (project key, issue type, space ID)" - execute[2]: - - "Call the appropriate tool with cloudId and operation-specific params (see resource meta/04 for tool reference)" - - "For transitions: always call getTransitionsForJiraIssue first to discover available transition IDs" - verify-result[1]: - - "After mutating operations, verify by fetching the entity to confirm the change was applied" - -output[1]: - - id: operation-result - description: "Result of the Atlassian operation" - components: - entity_type: "issue, page, comment, or space" - entity_id: "Issue key or page ID" - operation: "created, updated, transitioned, or searched" - result_summary: "Brief outcome summary" - -rules: - content-format: "Set contentFormat to 'markdown' for Confluence create/update/read operations." - account-id-for-users: "User fields require account IDs. Use lookupJiraAccountId to resolve names/emails." - -resources[1]: - - "meta/04" - -errors: - missing_cloud_id: - cause: "A product tool was called without resolving cloudId first" - recovery: "Call getAccessibleAtlassianResources, then retry" - invalid_issue_type: - cause: "createJiraIssue called with non-existent issue type" - recovery: "Call getJiraProjectIssueTypesMetadata to discover valid types" - transition_not_available: - cause: "transitionJiraIssue called with unavailable transition ID" - recovery: "Call getTransitionsForJiraIssue to get available transitions" - permission_denied: - cause: "User lacks permission for the requested operation" - recovery: "Verify Jira/Confluence permissions and project roles" diff --git a/meta/skills/06-gitnexus-operations.toon b/meta/skills/06-gitnexus-operations.toon new file mode 100644 index 00000000..4ace1379 --- /dev/null +++ b/meta/skills/06-gitnexus-operations.toon @@ -0,0 +1,146 @@ +id: gitnexus-operations +version: 3.0.0 +capability: Operations for codebase queries via the GitNexus knowledge graph + +description: "Operations wrapping the GitNexus MCP tools (query, context, impact, rename, detect_changes, cypher) and the lightweight resource reads. Each operation has the tool reference and a small linear procedure inline. Pertinent reference tables (impact depth/risk, refactor risk classes) live in the relevant operation's prose." + +operations: + verify-index: + description: "Read the GitNexus index context resource and check freshness for the target repo" + inputs[1]: + - repo_name: "Repository name as known to GitNexus" + output[2]: + - stats: "Symbol/relationship/process counts" + - stale: "Boolean — true if the index is out of date" + procedure[2]: + - "Read the MCP resource gitnexus://repo/{repo_name}/context" + - "If stale, run `npx gitnexus analyze` in the terminal before proceeding" + errors: + index_not_found: + cause: "No GitNexus index exists for the target repository" + recovery: "Run 'npx gitnexus analyze' from the project root, then retry verify-index" + index_stale: + cause: "The index is out of date relative to recent code changes" + recovery: "Run 'npx gitnexus analyze' to refresh, or 'npx gitnexus analyze --force' for a full rebuild" + + query: + description: "Find execution flows related to a concept or term" + inputs[2]: + - repo_name: "Repository name" + - search_term: "Concept, error text, or keyword" + output[1]: + - flows: "Process-grouped result list ranked by relevance" + procedure[1]: + - "Call gitnexus query({ repo_name, search_term })" + tools: + gitnexus[1]: + - query + errors: + no_processes_found: + cause: "query() returned no execution flows for the search term" + recovery: "Try broader search terms, or use cypher() for direct graph traversal" + + context: + description: "Get the 360-degree view of a symbol — callers, callees, and process participation" + inputs[2]: + - repo_name: "Repository name" + - name: "Symbol name (function, class, method, etc.)" + output[1]: + - context: "Symbol details with callers, callees, member relationships, and processes" + procedure[1]: + - "Call gitnexus context({ repo_name, name }); if ambiguous, re-call with file_path or uid from the disambiguation candidates" + tools: + gitnexus[1]: + - context + errors: + symbol_ambiguous: + cause: "Multiple symbols share the same name — context() returns disambiguation candidates" + recovery: "Re-call context() with the file_path or uid from one of the candidates" + + impact: + description: "Map upstream or downstream dependents for a symbol; assess blast radius before changes" + inputs[3]: + - repo_name: "Repository name" + - target: "Symbol or file" + - direction: "'upstream' (dependents) or 'downstream' (dependencies)" + output[2]: + - dependents: "Symbols/processes affected, grouped by depth" + - risk: "Risk classification per the depth/risk table" + procedure[1]: + - "Call gitnexus impact({ repo_name, target, direction })" + tools: + gitnexus[1]: + - impact + prose: | + Risk classification by depth (d): + | Depth | Risk | Recommended action | + |-------|---------------|--------------------------------------------| + | d=1 | WILL BREAK | Direct callers; must update synchronously | + | d=2 | LIKELY AFFECTED | Call chain at one remove; test thoroughly | + | d=3 | MAY NEED TESTING | Indirect; verify with detect_changes | + + rename: + description: "Multi-file rename driven by the call graph (preview or apply)" + inputs[4]: + - repo_name: "Repository name" + - old_name: "Current symbol name" + - new_name: "Target symbol name" + - dry_run: "true to preview edits without applying" + output[1]: + - changes: "Per-file edit list (when dry_run) or applied summary" + procedure[2]: + - "Always run with dry_run: true first; review the change list with the user" + - "Re-run with dry_run: false to apply" + tools: + gitnexus[1]: + - rename + + detect-changes: + description: "Verify the scope of recent edits — confirm only expected files/symbols changed" + inputs[1]: + - repo_name: "Repository name" + output[1]: + - delta: "Changed symbols/processes since last scan" + procedure[1]: + - "Call gitnexus detect_changes({ repo_name })" + tools: + gitnexus[1]: + - detect_changes + + cypher: + description: "Run a custom Cypher query over the GitNexus graph" + inputs[2]: + - repo_name: "Repository name" + - query: "Cypher query string" + procedure[1]: + - "Call gitnexus cypher({ repo_name, query })" + tools: + gitnexus[1]: + - cypher + prose: | + Graph schema reference: + Nodes: File, Function, Class, Interface, Method, Community, Process + Edges (via CodeRelation.type): CALLS, IMPORTS, EXTENDS, IMPLEMENTS, DEFINES, MEMBER_OF, STEP_IN_PROCESS + + read-process: + description: "Read a process resource for a step-by-step execution trace" + inputs[2]: + - repo_name: "Repository name" + - process_name: "Process identifier" + procedure[1]: + - "Read the MCP resource gitnexus://repo/{repo_name}/process/{process_name}" + + read-cluster: + description: "Read a functional-area cluster resource — area members and cohesion score" + inputs[2]: + - repo_name: "Repository name" + - cluster_name: "Cluster identifier" + procedure[1]: + - "Read the MCP resource gitnexus://repo/{repo_name}/cluster/{cluster_name}" + +rules: + query-not-grep: "Use query/context for execution flows and relationships. Grep is for text patterns and string literals only — when structure matters, use GitNexus." + dry-run-before-rename: "Always run rename with dry_run: true first and review the changes with the user before applying." + detect-changes-after-edit: "Always run detect-changes after applying a rename or batch edits to verify only expected files were affected." + index-freshness-first: "Run verify-index at the start of any GitNexus session. Stale indexes return misleading results." + diff --git a/meta/skills/07-gitnexus-operations.toon b/meta/skills/07-gitnexus-operations.toon deleted file mode 100644 index 0d2dada6..00000000 --- a/meta/skills/07-gitnexus-operations.toon +++ /dev/null @@ -1,59 +0,0 @@ -id: gitnexus-operations -version: 1.0.0 -capability: Query and navigate codebases using the GitNexus knowledge graph MCP server - -description: "This skill guides agents through the correct use of GitNexus MCP tools for codebase understanding, impact analysis, debugging, and refactoring. GitNexus builds a knowledge graph from source code — indexing symbols, call relationships, execution flows (processes), and functional areas (communities). Agents should use GitNexus when they need to understand how code works together (not just where text appears), trace execution flows, assess blast radius before changes, or perform safe multi-file renames." - -inputs[2]: - - id: task-type - description: "The type of codebase task: explore, impact-analysis, debug, or refactor" - - id: target - description: "The symbol, concept, error message, or area to investigate" - -protocol: - verify-index[3]: - - "Read gitnexus://repo/{name}/context to check index freshness and get codebase stats" - - "If the index is stale or missing, run 'npx gitnexus analyze' in the terminal before proceeding" - - "Available MCP resources for navigation: gitnexus://repo/{name}/clusters (functional areas), gitnexus://repo/{name}/cluster/{clusterName} (area members), gitnexus://repo/{name}/processes (all execution flows), gitnexus://repo/{name}/process/{processName} (step-by-step trace), gitnexus://repo/{name}/schema (graph schema for Cypher)" - select-workflow[4]: - - "explore: Use query() to find execution flows related to a concept, then context() for symbol deep-dives, then read process resources for full traces" - - "impact-analysis: Use impact() with direction 'upstream' to find dependents, then detect_changes() for pre-commit checks. Assess risk by depth (d=1 WILL BREAK, d=2 LIKELY AFFECTED, d=3 MAY NEED TESTING)" - - "debug: Use query() with error text to find related flows, then context() on suspect symbols to see callers/callees, then cypher() for custom call chain traces" - - "refactor: Use impact() to map all dependents first, then rename() with dry_run=true to preview edits, then rename() with dry_run=false to apply, then detect_changes() to verify scope" - execute[3]: - - "Start with the primary tool for the selected workflow (query for explore/debug, impact for impact-analysis/refactor)" - - "Use context() to get the 360-degree view of any symbol that appears in results — callers, callees, and process participation" - - "Read process resources (gitnexus://repo/{name}/process/{processName}) to trace full execution flows when understanding data flow or call chains" - verify-results[2]: - - "For refactoring: always run detect_changes() after applying changes to verify only expected files were affected" - - "For impact analysis: cross-reference affected processes against the codebase's functional areas (clusters) to assess blast radius breadth" - -output[1]: - - id: analysis-result - description: "Structured findings from the GitNexus analysis" - components: - symbols: "Relevant symbols with file paths and relationships" - processes: "Affected execution flows" - risk: "Risk assessment (LOW/MEDIUM/HIGH/CRITICAL) with rationale" - recommendations: "Suggested next steps based on findings" - -rules: - query-not-grep: "Use GitNexus query() when you need execution flows and relationships, not just file matches. GitNexus complements grep/search — it finds how code works together." - resource-reference: "Use attached resource meta/03 (gitnexus-reference) for checklists, pattern tables, worked examples, and CLI commands for each task type" - -resources[1]: - - "meta/03" - -errors: - index_not_found: - cause: "No GitNexus index exists for the target repository" - recovery: "Run 'npx gitnexus analyze' from the project root, then retry" - index_stale: - cause: "The index is out of date relative to recent code changes" - recovery: "Run 'npx gitnexus analyze' to refresh, or 'npx gitnexus analyze --force' for a full rebuild" - symbol_ambiguous: - cause: "Multiple symbols share the same name — context() returns disambiguation candidates" - recovery: "Re-call context() with the file_path or uid from the candidate list" - no_processes_found: - cause: "query() returned no execution flows for the search term" - recovery: "Try broader search terms, or use cypher() for direct graph traversal" diff --git a/meta/skills/07-harness-compat.toon b/meta/skills/07-harness-compat.toon new file mode 100644 index 00000000..92f07f0d --- /dev/null +++ b/meta/skills/07-harness-compat.toon @@ -0,0 +1,67 @@ +id: harness-compat +version: 3.0.0 +capability: Abstract sub-agent dispatch operations — harness-independent vocabulary for spawning, continuing, and concurrently dispatching agents + +description: "Three canonical operations (spawn-agent, continue-agent, spawn-concurrent). All skills and activities reference these operation names rather than harness-specific tool syntax. Per-harness implementation notes live in each operation's prose." + +operations: + spawn-agent: + description: "Dispatch a new isolated sub-agent with no prior context" + inputs[2]: + - prompt: "Full task prompt for the new agent" + - description: "Short label for the agent's role (optional; useful for tracing)" + output[1]: + - result: "The sub-agent's final output (text, including any <checkpoint_yield> block) — captured when the agent yields or completes" + procedure[1]: + - "Use the harness's foreground spawn primitive (see prose) with the given prompt; block until the agent yields a checkpoint or returns" + rules: + foreground-always: "CRITICAL: spawn-agent MUST be dispatched as foreground (blocking). Never set run_in_background. Background dispatch silently breaks checkpoint delivery — the orchestrator never sees the worker's <checkpoint_yield>." + token-in-prompt: "When the spawned agent inherits a workflow session, ALWAYS include the session_token in the prompt. Server state is preserved by the token, not by the harness." + prose: | + Per-harness implementation: + | Harness | Invocation | + |---------|-----------| + | cursor | Task(subagent_type=generalPurpose, description=<description>, prompt=<prompt>) — omit run_in_background or set it to false | + | cline | use_subagents({ prompt_1: <prompt> }) | + | generic | Any harness mechanism that starts a new agent with the given prompt and blocks until the agent yields or completes | + + continue-agent: + description: "Resume an existing sub-agent, preserving accumulated context where the harness supports it" + inputs[3]: + - agent_id: "Harness-assigned identifier for the agent to resume (harness-specific; may be unavailable on some harnesses)" + - session_token: "Workflow-server session token — included in the prompt for workflow-state continuity" + - prompt: "Updated instructions or continuation context" + output[1]: + - result: "The resumed agent's next yield or final output" + procedure[1]: + - "Use the harness's resume primitive (see prose) with the new prompt; block until the agent yields or completes" + rules: + foreground-always: "CRITICAL: continue-agent MUST be dispatched as foreground (blocking). Never set run_in_background." + token-in-prompt: "ALWAYS include the session_token in the prompt. The harness-level resume preserves the context window only — server-side workflow state lives in the token." + resume-is-optimisation: "Harness-level resume preserves the context window. Useful, not required for correctness — workflows must be correct without it." + prose: | + Per-harness implementation: + | Harness | Invocation | + |---------|-----------| + | cursor | Task(resume=<agent_id>) — preserves the agent's context window. Include session_token in the prompt. Never set run_in_background. | + | generic | spawn-agent with the session_token prepended to the prompt. Full workflow state is preserved by the token; the agent rebuilds context from artifacts and tool calls. | + + spawn-concurrent: + description: "Dispatch multiple independent agents in parallel" + inputs[1]: + - agents: "Array of { description, prompt } objects — each becomes an independent sub-agent" + output[1]: + - results: "Array of agent results, one per dispatched agent" + procedure[1]: + - "Use the harness's parallel-dispatch primitive (see prose) for all agents at once; block until they all yield or complete" + rules: + parallelism-is-optimisation: "Concurrent dispatch reduces wall-clock time. Not required for correctness — sequential fallback via spawn-agent is always valid." + prose: | + Per-harness implementation: + | Harness | Invocation | + |---------|-----------| + | cursor | Multiple Task calls in a single response turn — the harness executes them in parallel | + | generic | Parallel invocations when the harness supports concurrent dispatch; sequential spawn-agent calls otherwise | + +rules: + harness-independence: "All skills and activities MUST reference operation names from this skill (spawn-agent, continue-agent, spawn-concurrent) rather than harness-specific tool syntax. Harness-specific implementation details belong in this skill only, in each operation's prose." diff --git a/meta/skills/08-meta-orchestrator.toon b/meta/skills/08-meta-orchestrator.toon deleted file mode 100644 index 120edb5a..00000000 --- a/meta/skills/08-meta-orchestrator.toon +++ /dev/null @@ -1,67 +0,0 @@ -id: meta-orchestrator -version: 3.0.0 -capability: "Inline orchestration role for the meta workflow — checkpoint mediation, sub-agent dispatch, and meta-level error recovery" -description: "Skill for the agent running the meta workflow inline. The meta-orchestrator does NOT have its own activity protocol here — those live in the meta workflow's activity TOON files (00-discover-session, 01-initialize-session, 02-resolve-target, 03-dispatch-client-workflow, 04-end-workflow). This skill provides the rules, error recovery, and tool reference for the role. Cross-cutting behavioural rules live in agent-conduct (file-sensitivity, communication-tone, attribution-prohibition, operational-discipline, checkpoint-discipline, orchestrator-discipline)." - -inputs[2]: - - id: workflow-id - description: "Target workflow to orchestrate (e.g., 'work-package'); resolved by discover-session" - - id: user-request - description: "The user's original request, used by discover-session to extract identifying context" - -rules: - no-auto-resolution: "NEVER auto-resolve checkpoints. Even if the answer seems obvious, you MUST present the checkpoint to the user via AskQuestion (blocking) or the chat-plus-sleep pattern (advisory). Fabricating an option_id or answering on the user's behalf is a strict protocol violation." - present-before-respond: "If you have not called present_checkpoint on the current checkpoint_handle, you MUST NOT call respond_checkpoint. Always call present_checkpoint first. The response from present_checkpoint contains the exact question and valid options for THIS checkpoint — do NOT reuse options from a previous checkpoint or invent them." - no-option-hallucination: "NEVER fabricate an option_id. If respond_checkpoint returns 'Invalid option' or similar, STOP. Call present_checkpoint on the same checkpoint_handle to retrieve the valid options, then proceed accordingly. Do NOT guess again." - checkpoint-token-discipline: "present_checkpoint and respond_checkpoint take a checkpoint_handle (HMAC-signed token containing a '.'). NEVER pass the session_token, the checkpoint_id (a short name like 'classification-confirmed'), or any other value as the checkpoint_handle. If you receive 'Invalid session token' or 'missing signature' from a checkpoint tool, you are passing the wrong value." - reject-empty-checkpoints: "If the dispatched orchestrator returns workflow_complete but the activity defined required checkpoints with no responses recorded, REJECT the result and resume the orchestrator to address the missing checkpoints." - advisory-checkpoint-timing: "For non-blocking checkpoints with autoAdvanceMs: present the message in chat (NEVER AskQuestion — it blocks indefinitely), state the timer, and use the Shell tool to sleep for the full autoAdvanceMs duration. Only after the sleep completes without user interruption may you call respond_checkpoint with auto_advance: true. The minimum-response timer is server-enforced — do not attempt to short-circuit." - -tools: - list_workflows: - when: "discover-session step list-available-workflows — load the workflow catalog. No session token required." - params: "(none)" - start_session: - when: "Bootstrap (creating the meta session); initialize-session (creating or adopting the client session)" - params: "workflow_id (fresh) OR session_token (resume); parent_session_token when creating a child session; agent_id" - get_workflow: - when: "Bootstrap (after start_session) — load the meta workflow definition and primary skill" - params: "session_token, summary=true" - get_workflow_status: - when: "When inspecting a dispatched session — derive current_activity from the token without entering it" - params: "session_token" - present_checkpoint: - when: "Inside the dispatch-client-workflow checkpoint loop, after the orchestrator yields a checkpoint_handle" - params: "checkpoint_handle ONLY (NEVER session_token or checkpoint_id)" - respond_checkpoint: - when: "After the user selects an option (or after autoAdvanceMs fully elapses)" - params: "checkpoint_handle AND exactly one of: option_id (string) OR auto_advance (boolean true) OR condition_not_met (boolean true)" - save_state: - when: "After every completed activity (engine-driven by workflow-orchestrator); final-persist in end-workflow" - params: "session_token, planning_folder_path" - restore_state: - when: "initialize-session restore-state step (when is_resuming)" - params: "session_token, file_path" - -errors: - stale_token: - cause: "Server restarted and generated a new HMAC signing key, invalidating the saved session token" - recovery: "If start_session returns adopted: true the payload was preserved — continue. If recovered: true, the payload was corrupted — call restore_state to rebuild variables from the on-disk state file before any activity runs." - worker_timeout: - cause: "Sub-agent did not return within expected time" - recovery: "Check terminal output. Resume via harness-compat::continue-agent if still running; if stuck, dispatch a fresh sub-agent with the current state." - transition_ambiguous: - cause: "Multiple transition conditions evaluated to true at the activity boundary" - recovery: "Take the first matching transition in array order. Log a warning." - worker_incomplete: - cause: "Sub-agent reports fewer steps than the activity defines, or a required checkpoint has no response" - recovery: "Resume the sub-agent with explicit instructions to complete the missing items. Do NOT accept the partial result." - state_desync: - cause: "Sub-agent reports variable changes conflicting with orchestrator state" - recovery: "Sub-agent values take precedence (the worker has ground truth from user interaction); apply them and continue." - invalid_checkpoint_handle: - cause: "respond_checkpoint or present_checkpoint returned 'Invalid session token' or 'missing signature'" - recovery: "You are passing the wrong value as checkpoint_handle. Use the EXACT string returned by the worker's yield_checkpoint output (long token containing '.') — never the session_token or checkpoint_id." - -resources[1]: - - "meta/02" diff --git a/meta/skills/09-activity-worker.toon b/meta/skills/09-activity-worker.toon deleted file mode 100644 index 8d5b9709..00000000 --- a/meta/skills/09-activity-worker.toon +++ /dev/null @@ -1,84 +0,0 @@ -id: activity-worker -version: 2.0.0 -capability: Engine logic for the activity-worker role — activity execution, step iteration, checkpoint yielding, artifact production -description: "Single-load skill for the activity-worker (sub-agent or inline persona). Provides the worker bootstrap protocol and the rules unique to the worker role. Cross-cutting rules (file-sensitivity, communication-tone, attribution-prohibition, code-commentary, operational-discipline, checkpoint-discipline) live in agent-conduct — they are NOT restated here." - -inputs[3]: - - id: activity-id - description: "ID of the activity to execute" - - id: workflow-id - description: "Workflow ID for workflow-server calls (e.g., 'work-package')" - - id: state-variables - description: "Current workflow state variables" - -protocol: - bootstrap-activity[2]: - - "Call get_activity({ session_token }) to load the complete activity definition for the activity_id assigned to you." - - "Extract steps, checkpoints, skills, loops, decisions, transitions, and artifactPrefix from the response. The orchestrator does NOT pre-load these for you — it is your responsibility." - check-mode[1]: - - "If the activity is listed in mode.skipActivities for the active mode, report back with a skip result and do nothing else." - execute-steps[8]: - - "Execute each step in order. Required steps cannot be skipped silently — if a step cannot be completed, report it as incomplete with a reason." - - "Check whether the step has a 'skill' field BEFORE calling get_skill. If no 'skill' field, execute the step using the description and your general capabilities. Do NOT call get_skill on skill-less steps." - - "For steps with a 'skill' field, call get_skill({ session_token, step_id }) to load the skill definition. Skip this call if the same skill was loaded for a prior step in this activity and is still in context." - - "When a loaded skill has a _resources array, call get_resource({ session_token, resource_id }) for each entry. The resource_id is the string from _resources (e.g., '07' or 'meta/01') — NOT a skill ID, step ID, or activity ID." - - "If a loaded skill has no _resources array, do NOT call get_resource for that skill." - - "For steps with a 'condition' field, evaluate against state variables. If false, skip the step silently." - - "Track each completed step in steps_completed with a brief output description for the activity_complete result." - - "After yielding a checkpoint, STOP. Do not execute subsequent steps until the orchestrator resumes you with the checkpoint resolution." - yield-checkpoint[4]: - - "Before executing a step that defines a 'checkpoint' ID (or before evaluating a checkpoint whose condition is true), call yield_checkpoint({ session_token, checkpoint_id }). The response contains a checkpoint_handle — an HMAC-signed token string containing a '.' separator." - - "Output the checkpoint_handle as a raw JSON block wrapped in <checkpoint_yield> tags containing ONLY the checkpoint_handle. You MAY include prose context BEFORE the JSON block; you MUST NOT continue execution AFTER the closing </checkpoint_yield> tag." - - "If multiple checkpoints are pending in the same step manifest, yield ONLY the first one. Stop and wait for the orchestrator to resume you with the response before evaluating any subsequent checkpoint." - - "On resume, call resume_checkpoint({ session_token: checkpoint_handle }) to obtain a fresh unblocked token, apply the effects (variable changes) the orchestrator passed back, then continue from where you paused." - execute-loops[2]: - - "forEach: iterate the loop body over the named collection in 'over', binding each item to the loop's 'variable'." - - "while/doWhile: evaluate the 'condition' against state. while checks before each iteration; doWhile executes once then checks. Both respect maxIterations." - finalize[5]: - - "Write artifacts to planning_folder_path using the activity's artifactPrefix convention. Bare filenames in artifact.name are prefixed at write time (e.g., '08' + 'code-review.md' = '08-code-review.md')." - - "Update the planning folder's README.md Progress table: mark each artifact produced by this activity as '✅ Complete', update Status column descriptive text, and update the footer status line." - - "Compile the activity_complete result with: result_type, steps_completed, checkpoints_responded, variables_changed, artifacts_produced." - - "If a checkpoint effect included transitionTo, include transition_override in the result so the orchestrator overrides the default transition." - - "Return the result. The orchestrator handles commit-artifacts and persist-state — workers do NOT commit or persist." - -rules: - skill-operation-notation: "References of the form `skill-id::operation` (e.g., `harness-compat::spawn-agent`) denote a named operation defined in the operations field of the identified skill. Read that skill to find the harness-specific implementation." - no-continuation-after-yield: "After outputting </checkpoint_yield>, STOP all execution immediately. No further tool calls, no subsequent steps, no additional output. Continuing past a yield is a strict protocol violation." - no-start-session: "Workers NEVER call start_session. Workers inherit the session from the orchestrator that spawned them — they receive the session_token in their prompt." - -tools: - next_activity: - when: "Once at activity start — transition the session to the activity assigned to you" - params: "session_token, activity_id, step_manifest (when transitioning from a prior activity)" - get_activity: - when: "After next_activity — load the complete activity definition" - params: "session_token" - get_skill: - when: "For steps that declare a 'skill' field" - params: "session_token, step_id" - get_resource: - when: "When a loaded skill has _resources entries" - params: "session_token, resource_id (string from _resources, e.g., '07' or 'meta/01')" - yield_checkpoint: - when: "Before executing a step with a checkpoint ID" - params: "session_token, checkpoint_id" - resume_checkpoint: - when: "After being resumed by the orchestrator with the checkpoint resolution" - params: "session_token (use the checkpoint_handle, not your prior session token)" - -errors: - activity_not_found: - cause: "get_activity returned an error for the given activity_id" - recovery: "Report the error in the result. Verify activity_id spelling against the workflow definition." - skill_not_found: - cause: "get_skill returned an error for the step's declared skill" - recovery: "Report the error in the result. Verify the skill ID in the step's skill field." - step_failure: - cause: "A required step cannot be completed (test failure, build error, etc.)" - recovery: "Attempt recovery per the skill's error handling. If unresolvable, report the failure with error details." - checkpoint_skipped: - cause: "A checkpoint's condition evaluated to false at yield time" - recovery: "Skip the checkpoint silently and note it in the result." - -resources[1]: - - "meta/05" diff --git a/meta/skills/10-workflow-orchestrator.toon b/meta/skills/10-workflow-orchestrator.toon deleted file mode 100644 index f4edfc2b..00000000 --- a/meta/skills/10-workflow-orchestrator.toon +++ /dev/null @@ -1,91 +0,0 @@ -id: workflow-orchestrator -version: 2.0.0 -capability: Engine logic for the workflow-orchestrator role — drives a single client workflow's lifecycle, dispatches activity workers, evaluates transitions, and persists state -description: "Single-load skill for the workflow-orchestrator (sub-agent or inline persona). Provides the generic doWhile-over-activities engine that drives an arbitrary client workflow from initialActivity through workflow_complete. Cross-cutting rules (file-sensitivity, communication-tone, attribution-prohibition, operational-discipline, checkpoint-discipline, orchestrator-discipline) live in agent-conduct — they are NOT restated here. Per-activity hooks (commit-artifacts, persist-state) reference version-control and state-management skills rather than restating their procedures." - -inputs[3]: - - id: workflow-id - description: "Client workflow to orchestrate (e.g., 'work-package')" - - id: session-token - description: "Session token for the client workflow, inherited from the meta-orchestrator" - - id: planning-folder-path - description: "Path to the planning folder for this workflow run" - -protocol: - resume-detect[2]: - - "On bootstrap, call get_workflow_status({ session_token }). If current_activity is set, the session is mid-activity — go to dispatch-activity for current_activity. If current_activity is empty but completedActivities is non-empty, determine the next activity from the workflow's activity list and call next_activity to advance." - - "If current_activity is empty and completedActivities is empty, this is a fresh start — use the workflow's initialActivity and call next_activity to enter it." - main-loop[5]: - - "Loop body for each activity: dispatch-activity → process-result → after-activity → evaluate-transition → advance-or-complete." - - "dispatch-activity: spawn or continue the worker for the current activity." - - "process-result: validate the worker's result and apply variable changes." - - "after-activity: commit artifacts and persist state (delegated)." - - "evaluate-transition: pick the next activity (or recognise workflow_complete)." - dispatch-activity[3]: - - "Call next_activity({ session_token, activity_id, step_manifest }) to transition the session. Capture _meta.trace_token from the response and append to trace_tokens." - - "Compose the worker prompt using resource meta/01 (activity-worker-prompt) with substitutions for workflow_id, activity_id, session_token, agent_id. The worker self-bootstraps via get_activity — you MUST NOT call get_activity yourself." - - "Dispatch via harness-compat::spawn-agent (foreground / blocking). Wait for the worker's result." - process-result[4]: - - "If the worker output contains <checkpoint_yield>: extract the checkpoint_handle and yield it upward to the meta-orchestrator using your own <checkpoint_yield> block. Stop and wait to be resumed." - - "If activity_complete: validate steps_completed against the activity's required steps and checkpoints_responded against the activity's required checkpoints. If incomplete, resume the worker to address the missing items — do NOT accept the partial result." - - "Apply variables_changed to your internal state. Append the activity to completedActivities." - - "Append a semantic trace entry to {planning_folder_path}/workflow-trace.toon for this activity (events derived from steps_completed, checkpoints_responded, variables_changed). Then call get_trace({ session_token, trace_tokens }) to resolve the mechanical trace and append that too. Clear trace_tokens." - after-activity[2]: - - "commit-artifacts: per version-control.commit-regular-files — stage all changed files in .engineering/artifacts/ in the parent repo, commit with conventional format 'docs(<workflow-id>): <activity-id> artifacts', and push. Do NOT commit anything outside .engineering/artifacts/." - - "persist-state: per state-management.persistence — call save_state({ session_token, planning_folder_path }). Do NOT skip this; an unpersisted activity makes the session unrecoverable." - evaluate-transition[3]: - - "If the worker returned a transition_override (from a checkpoint effect transitionTo), use that activity_id." - - "Otherwise, evaluate the activity's transitions[] against state variables in array order. Take the first matching condition. If none match and no isDefault transition exists, the workflow is complete." - - "On workflow_complete: prepare a final summary (workflow id, dates, completed activities, key decisions, artifacts, outcomes met/unmet) and return { status: 'workflow_complete', final_state } to the meta-orchestrator." - resolve-checkpoints[3]: - - "When the worker yields a <checkpoint_yield>, the contained checkpoint_handle is an HMAC-signed token (contains a '.'). It is NOT the checkpoint_id." - - "Bubble up by emitting your own <checkpoint_yield> containing ONLY the worker's checkpoint_handle, then stop. The meta-orchestrator handles present_checkpoint, the user interaction, and respond_checkpoint." - - "When resumed, the meta-orchestrator passes you the resolved effects (variable updates). Apply them to your internal state, then resume the worker via harness-compat::continue-agent so the worker can call resume_checkpoint and continue." - handle-sub-workflows[3]: - - "If a client workflow needs to dispatch a sub-workflow, call start_session({ workflow_id: 'child-workflow', parent_session_token: '<your_token>', agent_id: 'workflow-orchestrator' })." - - "Spawn a NEW workflow-orchestrator for the sub-workflow via harness-compat::spawn-agent." - - "Manage the child inline; bubble its checkpoint yields further up to the meta-orchestrator unchanged." - -rules: - no-direct-interaction: "You are a sub-agent (or inline persona). NEVER ask the user directly. Surface checkpoints by yielding the worker's checkpoint_handle to the meta-orchestrator." - reject-empty-checkpoints: "If an activity defines required checkpoints and the worker returns checkpoints_responded as empty, REJECT the result and resume the worker." - no-get-activity: "NEVER call get_activity. The activity definition is the worker's domain. You only need the activity_id (from initialActivity or transitions) to call next_activity and to compose the worker prompt. Calling get_activity from the orchestrator is a protocol violation." - no-pre-load-skills: "NEVER call get_skill or get_skills to pre-load skills for worker activities. The worker loads its own skills during self-bootstrap." - -tools: - start_session: - when: "Bootstrap (resuming) and dispatching sub-workflows" - params: "session_token (resume) OR workflow_id with parent_session_token (sub-workflow); agent_id" - get_workflow: - when: "Once at bootstrap — load the workflow structure and the initialActivity field" - params: "session_token, summary=true" - get_workflow_status: - when: "On resume — derive current_activity from the token" - params: "session_token" - next_activity: - when: "Before dispatching each activity" - params: "session_token, activity_id, step_manifest (when transitioning from a prior activity)" - get_trace: - when: "After each activity_complete — resolve trace tokens for the completed activity" - params: "session_token, trace_tokens" - save_state: - when: "After every completed activity (persist-state phase)" - params: "session_token, planning_folder_path" - -errors: - worker_timeout: - cause: "Worker sub-agent did not return within expected time" - recovery: "Check terminal output. Resume via harness-compat::continue-agent if still running; if stuck, dispatch a fresh worker with the current activity_id." - worker_incomplete: - cause: "Worker reports fewer steps than the activity defines, or required checkpoints have no response" - recovery: "Resume the worker with explicit instructions to complete the missing items. Do NOT accept the partial result." - state_desync: - cause: "Worker reports variable changes conflicting with orchestrator state" - recovery: "Worker values take precedence (the worker has ground truth from user interaction)." - transition_ambiguous: - cause: "Multiple transition conditions evaluate to true at the activity boundary" - recovery: "Take the first matching transition in array order. Log a warning." - -resources[2]: - - "meta/01" - - "meta/05" diff --git a/meta/skills/11-harness-compat.toon b/meta/skills/11-harness-compat.toon deleted file mode 100644 index 80996ad5..00000000 --- a/meta/skills/11-harness-compat.toon +++ /dev/null @@ -1,43 +0,0 @@ -id: harness-compat -version: 1.1.0 -capability: "Abstract sub-agent dispatch operations — harness-independent vocabulary for spawning, continuing, and concurrently dispatching agents" - -description: "Defines three canonical operations (spawn-agent, continue-agent, spawn-concurrent) with harness-specific implementation notes. All skills and activities reference these operation names rather than harness-specific tool syntax. The workflow-server session_token provides complete workflow-state continuity regardless of harness — harness-level resume is a context-window optimisation only, not a correctness requirement." - -operations: - spawn-agent: - description: "Dispatch a new isolated sub-agent with no prior context. ALWAYS dispatched as foreground — the calling orchestrator must block and wait for the result before proceeding." - inputs[2]: - - prompt: "Full task prompt for the new agent" - - description: "Short label for the agent's role (optional; useful for tracing)" - harness: - cursor: "Task(subagent_type=generalPurpose, description=<description>, prompt=<prompt>) — omit run_in_background or set it to false. Foreground dispatch is required so checkpoint yields surface to the orchestrator." - cline: "use_subagents({ prompt_1: <prompt> })" - generic: "Any mechanism the harness provides to start a new agent with the given prompt, blocking until the agent yields or completes." - - continue-agent: - description: "Resume or extend an existing worker, preserving accumulated context where possible. ALWAYS dispatched as foreground. The workflow-server session_token provides complete workflow-state continuity regardless of harness — server-side state (activity, variables, checkpoints) is always recoverable from the token. Harness-level resume additionally preserves the agent's context window (accumulated codebase understanding, tool results) — a beneficial optimisation, not a correctness requirement." - inputs[3]: - - agent_id: "Harness-assigned identifier for the worker to resume (harness-specific; may be unavailable on some harnesses)" - - session_token: "Workflow-server session token — ALWAYS include in the prompt for workflow-state continuity" - - prompt: "Updated instructions or continuation context" - harness: - cursor: "Task(resume=<agent_id>) — preserves context window. Include session_token in the prompt for workflow-state continuity. Never set run_in_background." - generic: "spawn-agent with session_token prepended to prompt. Full workflow state is preserved by the token; the agent rebuilds codebase context from artifacts and tool calls." - note: "The session_token encodes complete workflow state. Server-side continuity is fully provided by the token — no harness dependency. Harness-level resume (context window preservation) is an optimisation only." - - spawn-concurrent: - description: "Dispatch multiple independent agents simultaneously" - inputs[1]: - - agents: "Array of {description, prompt} objects — each becomes an independent sub-agent" - harness: - cursor: "Multiple Task calls in a single response turn — the harness executes them in parallel" - generic: "Parallel invocations if the harness supports concurrent dispatch; sequential spawn-agent calls otherwise. Correctness is unaffected by sequencing — parallelism reduces wall-clock time only." - note: "Concurrent dispatch is a performance optimisation. Workflows are correct when agents are dispatched sequentially." - -rules: - harness-independence: "All skills and activities MUST reference operation names from this skill (spawn-agent, continue-agent, spawn-concurrent) rather than harness-specific tool syntax. Harness-specific implementation details belong in this skill only." - token-always-included: "ALWAYS include the session_token in the prompt for continue-agent calls, and for any spawn-agent call that inherits a workflow session. Server state is preserved by the token, not by the harness." - foreground-always: "CRITICAL: spawn-agent and continue-agent MUST always be dispatched as foreground (blocking). Never set run_in_background (or equivalent) for workflow sub-agents. The entire checkpoint architecture depends on the orchestrator blocking until the sub-agent yields a checkpoint or completes — background dispatch silently breaks checkpoint delivery." - resume-is-optimisation: "Harness-level resume (e.g. Cursor Task resume) preserves the context window — useful but not required for correctness. Workflows must be correct without it." - parallelism-is-optimisation: "Concurrent dispatch reduces wall-clock time but is not required for correctness. Sequential fallback is always valid." diff --git a/meta/skills/README.md b/meta/skills/README.md index f434dad4..e4be1d0e 100644 --- a/meta/skills/README.md +++ b/meta/skills/README.md @@ -42,7 +42,8 @@ To honour anti-pattern 27 (single source of truth), each rule lives in exactly o | `no-direct-interaction`, `no-get-activity`, `no-pre-load-skills`, `reject-empty-checkpoints` | `workflow-orchestrator` | sub-agent only | | `no-continuation-after-yield`, `no-start-session`, `skill-operation-notation` | `activity-worker` | worker only | | `token-management`, `step-manifests`, `resource-usage`, `validation` | `session-protocol` | All token-passing roles | -| `commit-after-activity`, `read-agents-md`, `no-destructive-ops`, `no-hook-skipping`, `explicit-commit` | `version-control` | Orchestrators producing artefacts | +| `read-agents-md`, `no-destructive-ops`, `no-hook-skipping`, `explicit-commit`, `conventional-commits` | `version-control` | Orchestrators producing artefacts | +| `commit-after-activity`, `persist-after-every-activity` | `workflow-engine` (under `commit-and-persist`) | Workflow orchestrators at activity boundaries | --- diff --git a/meta/workflow.toon b/meta/workflow.toon index 6b9518c1..5ad22da3 100644 --- a/meta/workflow.toon +++ b/meta/workflow.toon @@ -1,8 +1,8 @@ "$schema": ../../schemas/workflow.schema.json id: meta -version: 4.0.0 +version: 5.0.0 title: Meta Workflow -description: "Top-level lifecycle workflow for the workflow-server. Provides the universal skill repository and a five-activity sequence that runs in the meta session: identify the target workflow and any matching saved client session, create or adopt the client session as a child of meta, resolve target_path, dispatch the client orchestrator and mediate its checkpoint loop, and close out with a session summary. Excluded from list_workflows because it is not a user-facing workflow — bootstrap navigates here directly." +description: "Top-level lifecycle workflow. Five activities run in the meta session: identify the target workflow and any matching saved client session, create or adopt the client session as a child of meta, resolve target_path, dispatch the client orchestrator and mediate its checkpoint loop, and close out. Excluded from list_workflows — bootstrap navigates here directly." author: m2ux tags[5]: - meta @@ -10,8 +10,10 @@ tags[5]: - lifecycle - dispatch - session -skills: - primary: meta-orchestrator +operations[3]: + - "workflow-engine::handle-sub-workflow" + - "workflow-engine::dispatch-activity" + - "agent-conduct::orchestrator-discipline" initialActivity: discover-session rules[3]: - "This workflow is the entrypoint for all workflow operations — bootstrap protocol enters here directly via start_session({ workflow_id: 'meta' })" diff --git a/prism-audit/activities/00-scope-definition.toon b/prism-audit/activities/00-scope-definition.toon index 3b3bb92b..6e592423 100644 --- a/prism-audit/activities/00-scope-definition.toon +++ b/prism-audit/activities/00-scope-definition.toon @@ -4,7 +4,6 @@ name: Define Audit Scope description: "Collect the audit target, user's description of what to audit, and output path. Index the codebase with GitNexus. Present the scope for confirmation before proceeding to prompt generation." problem: "The audit requires a confirmed target codebase, a clear description of audit goals and focus areas, and an organised output directory before analysis can begin." skills: - primary: meta/activity-worker supporting[1]: - compose-audit-prompt steps[5]: diff --git a/prism-audit/activities/01-prompt-generation.toon b/prism-audit/activities/01-prompt-generation.toon index 5bef88b2..0200db04 100644 --- a/prism-audit/activities/01-prompt-generation.toon +++ b/prism-audit/activities/01-prompt-generation.toon @@ -4,7 +4,6 @@ name: Generate Audit Prompt description: "Analyse the target codebase structure and compose a detailed audit prompt tailored to its security-relevant characteristics. The prompt identifies audit domains, maps risk levels, specifies per-domain focus areas and patterns to check, and defines output format requirements. The generated prompt drives lens selection and analytical depth when the prism workflow is triggered." problem: "Generic audit prompts miss codebase-specific security characteristics. A blockchain ledger codebase needs different audit domains than a web service or CI/CD pipeline. The prompt must be tailored to the codebase's architecture, language, dependencies, and trust boundaries to produce meaningful findings." skills: - primary: meta/activity-worker supporting[1]: - compose-audit-prompt steps[8]: diff --git a/prism-audit/activities/02-execute-analysis.toon b/prism-audit/activities/02-execute-analysis.toon index 3bb2a5eb..8ddd10de 100644 --- a/prism-audit/activities/02-execute-analysis.toon +++ b/prism-audit/activities/02-execute-analysis.toon @@ -4,7 +4,6 @@ name: Execute Prism Analysis description: "Trigger one or more prism workflows to perform the analytical passes. Each audit scope defined during prompt-generation triggers a separate prism run with its own target, pipeline mode, and output subdirectory. The orchestrator suspends while each triggered prism workflow executes to completion, then collects the results." problem: "The audit analysis must be executed through the prism workflow's analytical pipeline (structural, adversarial, synthesis passes) rather than inline. Using trigger-workflow keeps prism generic and reusable while prism-audit controls the audit-specific context passed to each run." skills: - primary: meta/activity-worker supporting[1]: - compose-audit-prompt entryActions[2]: diff --git a/prism-audit/activities/03-audit-finalize.toon b/prism-audit/activities/03-audit-finalize.toon index 9491f3a5..5189fe12 100644 --- a/prism-audit/activities/03-audit-finalize.toon +++ b/prism-audit/activities/03-audit-finalize.toon @@ -4,7 +4,6 @@ name: Audit Report Finalization description: "Post-process the REPORT.md produced by the triggered prism workflow(s) into audit-specific deliverables. Splits the report into a summary document (AUDIT-REPORT.md) and a detailed findings document (DETAILED-FINDINGS.md), generates a design trade-off analysis (DESIGN-TRADE-OFFS.md) from conservation laws and meta-laws in the raw synthesis artifacts, and applies audit-specific formatting rules." problem: "The prism workflow produces a single clean REPORT.md with definitive findings. Security audits require three deliverables: a summary report with hyperlinked domain tables, a detailed findings document with expanded write-ups for every finding organised by severity, and a design trade-off analysis distilled from the conservation laws surfaced during the prism passes." skills: - primary: meta/activity-worker supporting[1]: - compose-audit-prompt steps[7]: diff --git a/prism-audit/activities/04-deliver-audit.toon b/prism-audit/activities/04-deliver-audit.toon index ecac99c1..b04137ba 100644 --- a/prism-audit/activities/04-deliver-audit.toon +++ b/prism-audit/activities/04-deliver-audit.toon @@ -4,7 +4,6 @@ name: Deliver Audit Results description: "Present the final audit deliverables to the user. Reads and summarises the three audit documents (AUDIT-REPORT.md, DETAILED-FINDINGS.md, DESIGN-TRADE-OFFS.md), reports all artifact paths, and provides a structured summary of findings by severity." problem: "The audit produces multiple documents across potentially multiple prism runs. The user needs a clear summary of what was produced, key metrics (finding counts by severity), and paths to all deliverables." skills: - primary: meta/activity-worker supporting[1]: - compose-audit-prompt steps[4]: diff --git a/prism-audit/workflow.toon b/prism-audit/workflow.toon index b3670c4f..62b55119 100644 --- a/prism-audit/workflow.toon +++ b/prism-audit/workflow.toon @@ -20,7 +20,6 @@ rules[6]: - "ARTIFACT VERIFICATION: After writing each artifact, workers MUST report: (a) file path written, (b) file size (KB), (c) format validation status (OK or FAIL)." skills: - primary: meta/workflow-orchestrator variables[16]: - name: audit_description type: string diff --git a/prism-evaluate/activities/00-scope-definition.toon b/prism-evaluate/activities/00-scope-definition.toon index f4187036..6a182382 100644 --- a/prism-evaluate/activities/00-scope-definition.toon +++ b/prism-evaluate/activities/00-scope-definition.toon @@ -4,7 +4,6 @@ name: Define Evaluation Scope description: "Collect the evaluation target, user's description of what to evaluate, and output path. Classify the target type, derive or validate evaluation dimensions, and present the scope for confirmation before proceeding to dimension planning." problem: "The evaluation requires a confirmed target, a clear description of evaluation goals, validated dimensions, and an organised output directory before analysis planning can begin." skills: - primary: meta/activity-worker supporting[1]: - plan-evaluation steps[5]: diff --git a/prism-evaluate/activities/01-dimension-planning.toon b/prism-evaluate/activities/01-dimension-planning.toon index 7668ec62..be263b82 100644 --- a/prism-evaluate/activities/01-dimension-planning.toon +++ b/prism-evaluate/activities/01-dimension-planning.toon @@ -4,7 +4,6 @@ name: Plan Dimension Analysis description: "Survey the target to understand its structure and content, map each evaluation dimension to prism pipeline modes and lenses, group dimensions by pipeline mode for execution, and write the evaluation plan artifact." problem: "Generic evaluation prompts miss target-specific content. A blockchain proposal needs different analytical focus than a product strategy document or a codebase architecture review. The dimension-to-lens mapping must be informed by the target's actual structure, claims, and content to produce meaningful findings." skills: - primary: meta/activity-worker supporting[1]: - plan-evaluation steps[5]: diff --git a/prism-evaluate/activities/02-execute-analysis.toon b/prism-evaluate/activities/02-execute-analysis.toon index b07c60dd..b171d23a 100644 --- a/prism-evaluate/activities/02-execute-analysis.toon +++ b/prism-evaluate/activities/02-execute-analysis.toon @@ -4,7 +4,6 @@ name: Execute Prism Analyses description: "Trigger one or more prism workflows to perform the analytical passes for each execution group. Each group triggers a separate prism run with its own pipeline mode, lens selection, and output subdirectory. The orchestrator suspends while each triggered prism workflow executes to completion, then collects the results." problem: "The evaluation analysis must be executed through the prism workflow's analytical pipeline rather than inline. Using trigger-workflow keeps prism generic and reusable while prism-evaluate controls the evaluation-specific context passed to each run." skills: - primary: meta/activity-worker supporting[1]: - plan-evaluation entryActions[1]: diff --git a/prism-evaluate/activities/03-consolidate-report.toon b/prism-evaluate/activities/03-consolidate-report.toon index 1fdc9b76..eba560df 100644 --- a/prism-evaluate/activities/03-consolidate-report.toon +++ b/prism-evaluate/activities/03-consolidate-report.toon @@ -4,7 +4,6 @@ name: Consolidate Evaluation Report description: "Read all prism analysis artifacts across evaluation dimensions, extract definitive findings per dimension, identify cross-dimensional patterns and a core finding, and compose a unified EVALUATION-REPORT.md. The report presents findings as conclusions without methodology metadata." problem: "Prism produces per-dimension analysis artifacts with varying structures (synthesis documents for full-prism, individual lens artifacts for portfolio). The evaluation consumer needs a single consolidated report with unified finding IDs, severity-calibrated findings, cross-dimensional insights, and actionable recommendations — stripped of analytical process details." skills: - primary: meta/activity-worker supporting[1]: - compose-evaluation-report steps[6]: diff --git a/prism-evaluate/activities/04-deliver-results.toon b/prism-evaluate/activities/04-deliver-results.toon index 7f3d1e53..e82d263a 100644 --- a/prism-evaluate/activities/04-deliver-results.toon +++ b/prism-evaluate/activities/04-deliver-results.toon @@ -4,7 +4,6 @@ name: Deliver Evaluation Results description: "Present the final evaluation results to the user. Reads and summarises the evaluation report, reports all artifact paths, and provides a structured summary of findings by dimension and severity. Offers the user the option to proceed with a resolution dialogue to address findings." problem: "The evaluation produces multiple artifacts across multiple prism runs. The user needs a clear summary of what was produced, key metrics (finding counts by dimension and severity), the core finding, and paths to all deliverables. The user may also want to proceed with proposing mitigations for the findings." skills: - primary: meta/activity-worker supporting[1]: - compose-evaluation-report steps[4]: diff --git a/prism-evaluate/activities/05-resolution-dialogue.toon b/prism-evaluate/activities/05-resolution-dialogue.toon index 99ef1d45..0d32388a 100644 --- a/prism-evaluate/activities/05-resolution-dialogue.toon +++ b/prism-evaluate/activities/05-resolution-dialogue.toon @@ -4,7 +4,6 @@ name: Resolution Dialogue description: "Iterate through evaluation findings one-by-one, proposing mitigations for each. For each finding, the worker reads both the evaluation report and the original target, classifies the finding by mitigation difficulty, proposes a specific mitigation, and presents it to the user for decision. The dialogue produces a MITIGATION-PLAN.md artifact documenting all accepted changes." problem: "Evaluation findings require targeted mitigations that range from simple text corrections to novel architectural proposals. Each finding needs individual consideration — the appropriate mitigation depends on the finding's nature, the target's content, and the user's intent. Batch presentation loses nuance; one-by-one dialogue preserves it." skills: - primary: meta/activity-worker supporting[1]: - resolve-findings steps[5]: diff --git a/prism-evaluate/activities/06-apply-mitigations.toon b/prism-evaluate/activities/06-apply-mitigations.toon index 6d78255b..b66e8c1f 100644 --- a/prism-evaluate/activities/06-apply-mitigations.toon +++ b/prism-evaluate/activities/06-apply-mitigations.toon @@ -4,7 +4,6 @@ name: Apply Accepted Mitigations description: "Apply the accepted mitigations from the resolution dialogue to the target document. Reads the MITIGATION-PLAN.md, applies changes in priority order, and verifies each change was applied correctly." problem: "The mitigation plan contains accepted changes ranging from single-word corrections to multi-paragraph additions. These must be applied precisely to the target without introducing errors, in the correct priority order, with verification after each change." skills: - primary: meta/activity-worker supporting[1]: - resolve-findings steps[5]: diff --git a/prism-evaluate/workflow.toon b/prism-evaluate/workflow.toon index 98a77348..e7076b16 100644 --- a/prism-evaluate/workflow.toon +++ b/prism-evaluate/workflow.toon @@ -23,7 +23,6 @@ rules[9]: - "RESOLUTION DIALOGUE: After evaluation delivery, the user may opt into a resolution dialogue that iterates through findings one-by-one, proposing mitigations and collecting user decisions. Each finding is presented individually — never in batches. For non-trivial findings, the worker proposes a novel solution that preserves the original claim where possible. Absolutely non-feasible claims are flagged explicitly." skills: - primary: meta/workflow-orchestrator variables[21]: - name: evaluation_description type: string diff --git a/prism-update/activities/00-discover-changes.toon b/prism-update/activities/00-discover-changes.toon index 05d61ef6..1aa6c78c 100644 --- a/prism-update/activities/00-discover-changes.toon +++ b/prism-update/activities/00-discover-changes.toon @@ -4,7 +4,6 @@ name: Discover Changes description: "Diff upstream prisms directory against current workflow resources. Categorize each prism as new, modified, renamed, or deleted. Classify new prisms by family and determine the next available resource index." problem: Need to understand what changed upstream before importing skills: - primary: meta/activity-worker supporting[1]: - diff-upstream steps[5]: diff --git a/prism-update/activities/01-review-changes.toon b/prism-update/activities/01-review-changes.toon index 0e495e2d..fbe1ef9b 100644 --- a/prism-update/activities/01-review-changes.toon +++ b/prism-update/activities/01-review-changes.toon @@ -4,7 +4,6 @@ name: Review Changes description: "Present discovered changes to the user for approval. User confirms scope and adjusts exclusions before import begins." problem: User needs to review and approve which upstream changes to import skills: - primary: meta/activity-worker supporting[1]: - diff-upstream steps[2]: diff --git a/prism-update/activities/02-import-resources.toon b/prism-update/activities/02-import-resources.toon index 78294ed2..fac93bf1 100644 --- a/prism-update/activities/02-import-resources.toon +++ b/prism-update/activities/02-import-resources.toon @@ -4,7 +4,6 @@ name: Import Resources description: "Apply all approved resource file changes: sync modified, apply renames, import new, remove deleted. Each change type is committed separately." problem: Resource files need to be created, updated, renamed, or removed to match upstream skills: - primary: meta/activity-worker supporting[1]: - sync-resources diff --git a/prism-update/activities/03-update-routing.toon b/prism-update/activities/03-update-routing.toon index 8b46b1af..adfa360f 100644 --- a/prism-update/activities/03-update-routing.toon +++ b/prism-update/activities/03-update-routing.toon @@ -4,7 +4,6 @@ name: Update Routing description: "Update all prism workflow skills to reflect resource changes: fix renamed references, add goal-mapping entries, expand catalogs, update resource lists." problem: Skill routing tables reference prism names and indices that may have changed skills: - primary: meta/activity-worker supporting[1]: - update-skill-routing diff --git a/prism-update/activities/04-update-docs.toon b/prism-update/activities/04-update-docs.toon index 1229679d..a2e51a98 100644 --- a/prism-update/activities/04-update-docs.toon +++ b/prism-update/activities/04-update-docs.toon @@ -4,7 +4,6 @@ name: Update Documentation description: "Update prism workflow documentation to reflect the current resource catalog, model sensitivity, and prompt guide." problem: Documentation references resource counts, family groupings, and prism names that have changed skills: - primary: meta/activity-worker supporting[1]: - update-prism-docs diff --git a/prism-update/activities/05-verify.toon b/prism-update/activities/05-verify.toon index 72ac31f4..f5d69f3b 100644 --- a/prism-update/activities/05-verify.toon +++ b/prism-update/activities/05-verify.toon @@ -4,7 +4,6 @@ name: Verify Consistency description: "Check for consistency issues across resources, skills, and documentation. Detect stale references, routing mismatches, count errors, and duplicate indices." problem: Changes across multiple files may leave inconsistencies skills: - primary: meta/activity-worker supporting[1]: - verify-prism-consistency diff --git a/prism-update/activities/06-commit-and-submit.toon b/prism-update/activities/06-commit-and-submit.toon index cfc012d8..26d69a76 100644 --- a/prism-update/activities/06-commit-and-submit.toon +++ b/prism-update/activities/06-commit-and-submit.toon @@ -4,7 +4,6 @@ name: Commit and Submit description: "Create a feature branch if needed, push all commits, and create a pull request against the workflows branch." problem: Changes need to be submitted as a PR for review skills: - primary: meta/activity-worker supporting[1]: - sync-resources diff --git a/prism-update/workflow.toon b/prism-update/workflow.toon index 6fb3c321..3bff9d8b 100644 --- a/prism-update/workflow.toon +++ b/prism-update/workflow.toon @@ -9,7 +9,6 @@ tags[3]: - sync skills: - primary: meta/workflow-orchestrator artifactLocations: planning: path: "{planning_folder_path}" diff --git a/prism/activities/00-select-mode.toon b/prism/activities/00-select-mode.toon index df323dda..752014cb 100644 --- a/prism/activities/00-select-mode.toon +++ b/prism/activities/00-select-mode.toon @@ -16,7 +16,6 @@ recognition[11]: - error resilience - behavioral analysis skills: - primary: meta/activity-worker supporting[1]: - plan-analysis steps[3]: diff --git a/prism/activities/01-structural-pass.toon b/prism/activities/01-structural-pass.toon index 394fbc06..db1512e1 100644 --- a/prism/activities/01-structural-pass.toon +++ b/prism/activities/01-structural-pass.toon @@ -3,7 +3,6 @@ version: 2.1.0 name: Structural Analysis Pass description: "Iterate over analysis_units and run the appropriate analysis for each unit. For single and full-prism units, runs the L12 structural lens. For portfolio units, runs multiple independent lenses. For behavioral units, dispatches 4 independent behavioral lenses. Each iteration writes artifacts namespaced by unit. After all units complete, transitions based on pipeline mode." skills: - primary: meta/activity-worker supporting[1]: - structural-analysis artifacts[6]: diff --git a/prism/activities/02-adversarial-pass.toon b/prism/activities/02-adversarial-pass.toon index 057a3603..8f08827b 100644 --- a/prism/activities/02-adversarial-pass.toon +++ b/prism/activities/02-adversarial-pass.toon @@ -3,7 +3,6 @@ version: 2.0.0 name: Adversarial Analysis Pass description: "Iterate over analysis_units that were assigned full-prism mode and run the adversarial lens against each unit's structural analysis artifact. Each worker runs in a fresh context. Writes adversarial-analysis.md per unit." skills: - primary: meta/activity-worker supporting[1]: - full-prism artifacts[1]: diff --git a/prism/activities/03-synthesis-pass.toon b/prism/activities/03-synthesis-pass.toon index 5dbdfe8d..9576ee92 100644 --- a/prism/activities/03-synthesis-pass.toon +++ b/prism/activities/03-synthesis-pass.toon @@ -3,7 +3,6 @@ version: 2.0.0 name: Synthesis Pass description: "Iterate over analysis_units that were assigned full-prism mode and run the synthesis lens against each unit's structural and adversarial artifacts. Each worker runs in a fresh context. Writes synthesis.md per unit." skills: - primary: meta/activity-worker supporting[1]: - full-prism artifacts[1]: diff --git a/prism/activities/04-deliver-result.toon b/prism/activities/04-deliver-result.toon index 2f1f9c5e..370c598f 100644 --- a/prism/activities/04-deliver-result.toon +++ b/prism/activities/04-deliver-result.toon @@ -3,7 +3,6 @@ version: 3.0.0 name: Deliver Result description: "Present the final report to the user. Reads the REPORT.md artifact produced by the generate-report activity and reports paths to all underlying analysis artifacts for reference. This is the terminal activity for all prism pipeline modes." skills: - primary: meta/activity-worker supporting[1]: - structural-analysis steps[3]: diff --git a/prism/activities/05-behavioral-synthesis-pass.toon b/prism/activities/05-behavioral-synthesis-pass.toon index 095c0ea9..1567a900 100644 --- a/prism/activities/05-behavioral-synthesis-pass.toon +++ b/prism/activities/05-behavioral-synthesis-pass.toon @@ -3,7 +3,6 @@ version: 1.0.0 name: Behavioral Synthesis Pass description: "Iterate over analysis_units that were assigned behavioral mode and run the behavioral synthesis lens against each unit's 4 behavioral artifacts. Each worker runs in a fresh context. Writes behavioral-synthesis.md per unit." skills: - primary: meta/activity-worker supporting[1]: - behavioral-pipeline artifacts[1]: diff --git a/prism/activities/06-generate-report.toon b/prism/activities/06-generate-report.toon index 64b42cae..7c47e17c 100644 --- a/prism/activities/06-generate-report.toon +++ b/prism/activities/06-generate-report.toon @@ -4,7 +4,6 @@ name: Generate Final Report description: "Read all analysis artifacts produced by prior passes and generate a clean final report (REPORT.md) that presents definitive findings without methodology-specific language. The report uses unified finding identifiers, organises by severity, and contains only conclusions — not the analytical process that produced them. Works across all pipeline modes." problem: "Analysis artifacts (structural-analysis.md, adversarial-analysis.md, synthesis.md, portfolio-*.md, behavioral-synthesis.md) contain methodology-specific language (conservation laws, meta-laws, analysis scorecards, dispute resolutions) that is valuable for analytical rigour but obscures the definitive results for readers who need actionable findings." skills: - primary: meta/activity-worker supporting[1]: - generate-report steps[5]: diff --git a/prism/activities/07-dispute-pass.toon b/prism/activities/07-dispute-pass.toon index 2d0ec630..8f9fa8ac 100644 --- a/prism/activities/07-dispute-pass.toon +++ b/prism/activities/07-dispute-pass.toon @@ -4,7 +4,6 @@ name: Dispute Analysis Pass description: "Run 2 maximally orthogonal prisms independently, then synthesize ONLY their disagreements. 3 fresh workers total. Prism pair is selected automatically: l12 + identity for code, l12_universal + claim for general targets." problem: "Full-prism self-correction costs 3x more than needed for many targets. Dispute provides genuine self-correction at 1/3 the cost by focusing on divergence between orthogonal analytical perspectives." skills: - primary: meta/activity-worker supporting[1]: - dispute-analysis artifacts[3]: diff --git a/prism/activities/08-subsystem-pass.toon b/prism/activities/08-subsystem-pass.toon index 5c8b1cf0..0b9f4e71 100644 --- a/prism/activities/08-subsystem-pass.toon +++ b/prism/activities/08-subsystem-pass.toon @@ -4,7 +4,6 @@ name: Subsystem Analysis Pass description: "AST-decompose source code into structural subsystems, assign different prisms per subsystem via calibration, execute per-subsystem analysis, then synthesize cross-subsystem findings. N+2 fresh workers (1 calibration + N per-subsystem + 1 synthesis). Code-only mode." problem: "Whole-file analysis with a single prism misses bugs that exist BETWEEN subsystems and structural properties that span class boundaries. Different code regions benefit from different analytical lenses." skills: - primary: meta/activity-worker supporting[1]: - subsystem-analysis artifacts[2]: diff --git a/prism/activities/09-verified-pass.toon b/prism/activities/09-verified-pass.toon index a8f3429a..d2dcce20 100644 --- a/prism/activities/09-verified-pass.toon +++ b/prism/activities/09-verified-pass.toon @@ -4,7 +4,6 @@ name: Verified Analysis Pass description: "L12 structural analysis followed by gap detection (knowledge_boundary + knowledge_audit on L12 output), gap extraction, and re-analysis with verified corrections. 4 fresh workers. Highest accuracy mode — addresses confabulation by explicitly identifying knowledge gaps before re-analyzing." problem: "Single-pass analysis may confabulate claims that depend on facts the model cannot verify. Verified mode detects these gaps and re-runs with corrections." skills: - primary: meta/activity-worker supporting[1]: - verified-analysis artifacts[3]: diff --git a/prism/activities/10-reflect-pass.toon b/prism/activities/10-reflect-pass.toon index b1ae7c2e..16c351df 100644 --- a/prism/activities/10-reflect-pass.toon +++ b/prism/activities/10-reflect-pass.toon @@ -4,7 +4,6 @@ name: Reflect Analysis Pass description: "L12 structural analysis followed by meta-analysis (claim prism applied to L12 output) and constraint synthesis. 3 fresh workers. Applies recursive meta-analysis — running a prism on the output of another prism to find what the first analysis conceals about itself." problem: "Single-pass analysis cannot examine its own blind spots. Reflect uses the claim prism to attack the L12 output as a text artifact, revealing hidden assumptions in the analysis itself, not just the code." skills: - primary: meta/activity-worker supporting[1]: - reflect-analysis artifacts[3]: diff --git a/prism/activities/11-smart-pass.toon b/prism/activities/11-smart-pass.toon index e4c87edb..e895d3f1 100644 --- a/prism/activities/11-smart-pass.toon +++ b/prism/activities/11-smart-pass.toon @@ -4,7 +4,6 @@ name: Smart Analysis Pass description: "Adaptive chain engine that automatically composes the analysis pipeline based on input characteristics. Runs prereq scan, fills knowledge gaps, selects subsystem or L12 based on code structure, runs dispute for self-correction, and updates the codebase profile. 5+ fresh workers. The only mode where the system decides the pipeline topology." problem: "Users must manually select the right pipeline mode. Smart mode removes this burden by composing the pipeline automatically based on what the input needs." skills: - primary: meta/activity-worker supporting[1]: - smart-analysis artifacts[3]: diff --git a/prism/activities/12-adaptive-pass.toon b/prism/activities/12-adaptive-pass.toon index acc34c7a..e9806333 100644 --- a/prism/activities/12-adaptive-pass.toon +++ b/prism/activities/12-adaptive-pass.toon @@ -4,7 +4,6 @@ name: Adaptive Depth Pass description: "Cost-minimizing depth escalation. Starts with the cheapest analysis (SDL deep_scan on Haiku) and escalates to deeper modes only if signal quality is insufficient. Stops at the first stage that produces adequate analytical depth. 1-3+ fresh workers depending on escalation." problem: "Users often don't know how deep an analysis needs to be. Running full-prism on every target is wasteful. Adaptive starts cheap and escalates only when needed." skills: - primary: meta/activity-worker supporting[1]: - adaptive-analysis artifacts[5]: diff --git a/prism/workflow.toon b/prism/workflow.toon index 490cbe75..c9bbfac2 100644 --- a/prism/workflow.toon +++ b/prism/workflow.toon @@ -24,7 +24,6 @@ rules[10]: - "ARTIFACT VERIFICATION: After writing each artifact, workers MUST report: (a) file path written, (b) file size (KB), (c) format validation status (OK or FAIL). This confirms successful completion and prevents silent write failures." skills: - primary: meta/workflow-orchestrator variables[26]: - name: target type: string diff --git a/remediate-vuln/activities/01-start.toon b/remediate-vuln/activities/01-start.toon index e83b57fd..62859fe3 100644 --- a/remediate-vuln/activities/01-start.toon +++ b/remediate-vuln/activities/01-start.toon @@ -6,7 +6,6 @@ problem: User needs to remediate a security vulnerability without public disclos required: true estimatedTime: 10-15m skills: - primary: meta/activity-worker rules[2]: - "STRICT ISOLATION: This activity MUST NOT call any GitHub PR or Issue creation tools (gh pr create, gh issue create)." - "PRIVATE REMOTE ONLY: All git operations must target the 'security' remote, never 'origin'." diff --git a/remediate-vuln/activities/02-strategic-review.toon b/remediate-vuln/activities/02-strategic-review.toon index 121ed2d8..d9463ebe 100644 --- a/remediate-vuln/activities/02-strategic-review.toon +++ b/remediate-vuln/activities/02-strategic-review.toon @@ -19,7 +19,6 @@ artifacts[2]: location: planning description: "High-level architecture summary for management stakeholders. Uses UML-style diagrams (system context, package, sequence) to visualize changes. See architecture-summary resource for template." skills: - primary: meta/activity-worker steps[9]: - id: diff-review name: Review diff diff --git a/remediate-vuln/activities/03-submit.toon b/remediate-vuln/activities/03-submit.toon index edea9d7d..1cbd9419 100644 --- a/remediate-vuln/activities/03-submit.toon +++ b/remediate-vuln/activities/03-submit.toon @@ -6,7 +6,6 @@ problem: User needs to submit a security fix without public disclosure required: true estimatedTime: 5-10m skills: - primary: meta/activity-worker rules[2]: - "STRICT ISOLATION: This activity MUST NOT call any GitHub PR tools (gh pr review, gh pr ready)." - "PRIVATE REMOTE ONLY: All git push operations must target the 'security' remote." diff --git a/remediate-vuln/workflow.toon b/remediate-vuln/workflow.toon index b2f07b92..2b9c73f7 100644 --- a/remediate-vuln/workflow.toon +++ b/remediate-vuln/workflow.toon @@ -20,7 +20,6 @@ rules[8]: - "Explicit approval - Get clear 'yes' or 'proceed' before major actions" - "ORCHESTRATION MODEL: This workflow uses an orchestrator/worker pattern. The agent receiving the user request acts AS the orchestrator inline (skill: meta-orchestrator from meta/skills) — it MUST NOT be spawned as a sub-agent. The orchestrator loads the workflow, manages transitions, tracks state, and presents checkpoints to the user. A worker sub-agent (skill: activity-worker from meta/skills) executes activity steps and produces artifacts. When the worker reaches a blocking checkpoint, it yields a checkpoint_pending result. The orchestrator presents the checkpoint to the user, then resumes the worker with the response. CONSTRAINT: Only ONE level of sub-agent indirection (the worker)." skills: - primary: meta/workflow-orchestrator artifactLocations: planning: path: "{planning_folder_path}" diff --git a/substrate-node-security-audit/activities/01-scope-setup.toon b/substrate-node-security-audit/activities/01-scope-setup.toon index 581181ea..eba090f4 100644 --- a/substrate-node-security-audit/activities/01-scope-setup.toon +++ b/substrate-node-security-audit/activities/01-scope-setup.toon @@ -9,7 +9,6 @@ recognition[4]: - run security review - security audit setup skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: true diff --git a/substrate-node-security-audit/activities/02-reconnaissance.toon b/substrate-node-security-audit/activities/02-reconnaissance.toon index dcae090f..0e195218 100644 --- a/substrate-node-security-audit/activities/02-reconnaissance.toon +++ b/substrate-node-security-audit/activities/02-reconnaissance.toon @@ -8,7 +8,6 @@ recognition[3]: - codebase reconnaissance - identify crates and trust boundaries skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: true diff --git a/substrate-node-security-audit/activities/03-primary-audit.toon b/substrate-node-security-audit/activities/03-primary-audit.toon index bfcf00a8..137140e2 100644 --- a/substrate-node-security-audit/activities/03-primary-audit.toon +++ b/substrate-node-security-audit/activities/03-primary-audit.toon @@ -8,7 +8,6 @@ recognition[3]: - dispatch audit agents - execute audit template skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: true diff --git a/substrate-node-security-audit/activities/04-adversarial-verification.toon b/substrate-node-security-audit/activities/04-adversarial-verification.toon index 2715b4be..a8e6560f 100644 --- a/substrate-node-security-audit/activities/04-adversarial-verification.toon +++ b/substrate-node-security-audit/activities/04-adversarial-verification.toon @@ -8,7 +8,6 @@ recognition[3]: - adversarial review - check pass items skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: true diff --git a/substrate-node-security-audit/activities/05-report-generation.toon b/substrate-node-security-audit/activities/05-report-generation.toon index 87679cfd..6221a53a 100644 --- a/substrate-node-security-audit/activities/05-report-generation.toon +++ b/substrate-node-security-audit/activities/05-report-generation.toon @@ -8,7 +8,6 @@ recognition[3]: - consolidate findings - finalize report skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: true diff --git a/substrate-node-security-audit/activities/06-ensemble-pass.toon b/substrate-node-security-audit/activities/06-ensemble-pass.toon index 501eda51..8d0f71a2 100644 --- a/substrate-node-security-audit/activities/06-ensemble-pass.toon +++ b/substrate-node-security-audit/activities/06-ensemble-pass.toon @@ -8,7 +8,6 @@ recognition[3]: - second model audit - multi-model merge skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: false diff --git a/substrate-node-security-audit/activities/07-gap-analysis.toon b/substrate-node-security-audit/activities/07-gap-analysis.toon index 65418030..7099e6a6 100644 --- a/substrate-node-security-audit/activities/07-gap-analysis.toon +++ b/substrate-node-security-audit/activities/07-gap-analysis.toon @@ -8,7 +8,6 @@ recognition[3]: - gap analysis - benchmark against professional report skills: - primary: meta/activity-worker supporting[1]: - execute-audit required: false diff --git a/substrate-node-security-audit/activities/10-sub-crate-review.toon b/substrate-node-security-audit/activities/10-sub-crate-review.toon index 7be96538..618014e7 100644 --- a/substrate-node-security-audit/activities/10-sub-crate-review.toon +++ b/substrate-node-security-audit/activities/10-sub-crate-review.toon @@ -8,7 +8,6 @@ recognition[3]: - group a sub-agent - checklist review skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/substrate-node-security-audit/activities/11-sub-static-analysis.toon b/substrate-node-security-audit/activities/11-sub-static-analysis.toon index f8abfad2..3da210a4 100644 --- a/substrate-node-security-audit/activities/11-sub-static-analysis.toon +++ b/substrate-node-security-audit/activities/11-sub-static-analysis.toon @@ -8,7 +8,6 @@ recognition[3]: - pattern-based search - mechanical checks skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/substrate-node-security-audit/activities/12-sub-toolkit-review.toon b/substrate-node-security-audit/activities/12-sub-toolkit-review.toon index b76ff6d5..05044165 100644 --- a/substrate-node-security-audit/activities/12-sub-toolkit-review.toon +++ b/substrate-node-security-audit/activities/12-sub-toolkit-review.toon @@ -8,7 +8,6 @@ recognition[3]: - group d sub-agent - per-function checklist skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/substrate-node-security-audit/activities/13-sub-architectural-analysis.toon b/substrate-node-security-audit/activities/13-sub-architectural-analysis.toon index 038a0d60..15a006dd 100644 --- a/substrate-node-security-audit/activities/13-sub-architectural-analysis.toon +++ b/substrate-node-security-audit/activities/13-sub-architectural-analysis.toon @@ -8,7 +8,6 @@ recognition[3]: - threat model construction - architectural decomposition skills: - primary: meta/activity-worker supporting[1]: - execute-sub-agent required: false diff --git a/substrate-node-security-audit/activities/14-sub-output-verification.toon b/substrate-node-security-audit/activities/14-sub-output-verification.toon index 1efb76c0..830d7eeb 100644 --- a/substrate-node-security-audit/activities/14-sub-output-verification.toon +++ b/substrate-node-security-audit/activities/14-sub-output-verification.toon @@ -8,7 +8,6 @@ recognition[3]: - output verification - check completeness skills: - primary: meta/activity-worker supporting[1]: - verify-sub-agent-output required: false diff --git a/substrate-node-security-audit/activities/15-sub-structured-merge.toon b/substrate-node-security-audit/activities/15-sub-structured-merge.toon index 6a8b85ad..c2b9172d 100644 --- a/substrate-node-security-audit/activities/15-sub-structured-merge.toon +++ b/substrate-node-security-audit/activities/15-sub-structured-merge.toon @@ -8,7 +8,6 @@ recognition[3]: - structured merge - reconcile finding counts skills: - primary: meta/activity-worker supporting[1]: - merge-findings required: false diff --git a/substrate-node-security-audit/activities/16-sub-reconnaissance.toon b/substrate-node-security-audit/activities/16-sub-reconnaissance.toon index 02435dad..97728a93 100644 --- a/substrate-node-security-audit/activities/16-sub-reconnaissance.toon +++ b/substrate-node-security-audit/activities/16-sub-reconnaissance.toon @@ -8,7 +8,6 @@ recognition[3]: - map architecture - build function registry skills: - primary: meta/activity-worker supporting[1]: - map-codebase required: false diff --git a/substrate-node-security-audit/workflow.toon b/substrate-node-security-audit/workflow.toon index 09207264..0d952d79 100644 --- a/substrate-node-security-audit/workflow.toon +++ b/substrate-node-security-audit/workflow.toon @@ -39,7 +39,6 @@ rules[26]: - "FINDING COUNT RECONCILIATION: M produces a reconciliation table where Unaccounted MUST equal zero for every agent. This is a HARD STOP — report generation MUST NOT begin with Unaccounted > 0." - "OBSERVATION ELEVATION: M reviews all agent reconnaissance_leads and additional_observations, PLUS S agent emergent_domains from s-architectural-analysis.json and R agent leads from r-reconnaissance-data.json. Emergent domains are architectural vulnerability hypotheses — each MUST be dispositioned as captured, elevated, or not-applicable. Security-relevant observations (divergent code paths, missing validation, error-path persistence, silent errors, trust boundary amplification) MUST be elevated to findings or explicitly mapped to existing findings. Silent observation loss is a regression source." skills: - primary: meta/workflow-orchestrator variables[19]: - name: target_submodule type: string diff --git a/work-package/activities/01-start-work-package.toon b/work-package/activities/01-start-work-package.toon index 0ea3b76d..07feefae 100644 --- a/work-package/activities/01-start-work-package.toon +++ b/work-package/activities/01-start-work-package.toon @@ -1,7 +1,7 @@ id: start-work-package -version: 3.3.0 +version: 3.4.0 name: Start Work Package -description: "Initialize the work package: verify or create an issue, set up feature branch and draft PR, and create planning folder. Establishes traceability from requirements through implementation." +description: "Initialize the work package: verify or create an issue, set up feature branch and draft PR (assigned to the current GitHub user), record the PR reference back on the issue via its platform's native PR linkage, and create the planning folder. Establishes traceability from requirements through implementation." problem: User needs to initialize a work package with issue tracking, branch, and PR recognition[6]: - start work package @@ -16,8 +16,13 @@ entryActions[1]: - action: log message: Starting issue management skills: - primary: meta/activity-worker -steps[20]: + supporting[5]: + - atlassian-operations + - create-issue + - github-cli-protocol + - manage-artifacts + - manage-git +steps[21]: - id: detect-review-mode name: Detect Review Mode description: "Check if user request indicates review of existing PR. If detected, set is_review_mode=true and prompt for PR reference." @@ -42,7 +47,6 @@ steps[20]: - id: initialize-target name: Initialize Target Directory description: "cd into target_path. Fetch origin and checkout the default branch (main/master). Pull latest. This ensures the target is at HEAD before creating a feature branch." - skill: manage-git - id: detect-project-type name: Detect Project Type description: "Auto-detect project type inside target_path: Check for Cargo.toml with Substrate dependencies (sp-*, frame-*, pallet-*). Set project_type to 'rust-substrate' if found, otherwise 'other'." @@ -57,7 +61,6 @@ steps[20]: - id: verify-jira-issue name: Verify Jira Issue description: "Load the atlassian-operations supporting skill. Call getAccessibleAtlassianResources to obtain cloudId, then call getJiraIssue to verify the issue exists. Capture issue_number and issue_url." - skill: atlassian-operations condition: type: simple variable: issue_platform @@ -70,7 +73,6 @@ steps[20]: - id: verify-github-issue name: Verify GitHub Issue description: "Run 'gh issue view <number>' to verify the issue exists. Capture issue_number and issue_url." - skill: github-cli-protocol condition: type: simple variable: issue_platform @@ -79,7 +81,6 @@ steps[20]: - id: search-github-issue name: Search for linked GitHub issue description: "When the provided issue is a Jira ticket, search the target repo for a GitHub issue that references the Jira key. Run: gh issue list --search '<jira_issue_key>' --repo <target_repo> --json number,title,url --limit 5 inside target_path. Match against the Jira key appearing in the issue title or body. If a match is found set github_issue_found=true and capture github_issue_number and github_issue_url. If no match is found set github_issue_found=false." - skill: github-cli-protocol condition: type: simple variable: issue_platform @@ -110,7 +111,6 @@ steps[20]: - id: create-github-issue-for-jira name: Create GitHub issue for Jira ticket description: "Create a GitHub issue in the target repo that mirrors the Jira ticket. Set issue_platform to 'github' temporarily so the create-issue skill routes to the GitHub protocol. The issue title should match the Jira ticket summary. The issue body should include a reference to the Jira ticket URL. After creation capture github_issue_number and github_issue_url, then restore issue_platform to 'jira'." - skill: create-issue condition: type: simple variable: needs_github_issue_creation @@ -119,7 +119,6 @@ steps[20]: - id: create-issue name: Create Issue description: "Create issue in selected platform using issue-management skill. Skill routes to GitHub (gh CLI) or Jira (Atlassian MCP) protocol based on issue_platform." - skill: create-issue checkpoint: platform-selection condition: type: simple @@ -129,7 +128,6 @@ steps[20]: - id: activate-issue name: Activate Issue description: "Transition the issue to 'In Progress' and assign it to the current user. (1) For Jira: call atlassianUserInfo to get the current user's account ID, then call editJiraIssue to set the assignee field to { accountId: <current_user_account_id> }. Next, call getTransitionsForJiraIssue to discover available transitions, find the one targeting 'In Progress' (or equivalent active status), and call transitionJiraIssue with that transition ID. (2) For GitHub: run 'gh issue edit <number> --add-assignee @me' to self-assign. Skip transition for GitHub (no built-in status workflow). (3) If the issue is already in progress or already assigned, skip the respective operation silently." - skill: atlassian-operations condition: type: simple variable: issue_skipped @@ -144,11 +142,9 @@ steps[20]: - id: check-branch name: Check Current Branch description: "INSIDE target_path: Check if already on a feature branch (not main/master). Run 'git branch --show-current' and compare against main/master." - skill: manage-git - id: create-branch name: Create Feature Branch description: "INSIDE target_path: Create feature branch from the default branch with naming convention: type/issue-number-short-description." - skill: manage-git checkpoint: branch-check condition: type: and @@ -164,7 +160,6 @@ steps[20]: - id: check-pr name: Check for Existing PR description: "INSIDE target_path: Check if PR already exists for current branch. Run 'gh pr list --head <branch-name>' from target_path. If a PR is found, set pr_exists=true and capture the PR number in existing_pr_number. If no PR is found, pr_exists remains false." - skill: github-cli-protocol checkpoint: pr-check condition: type: simple @@ -177,8 +172,7 @@ steps[20]: description: "Set to true when an existing PR is found for the current branch" - id: create-pr name: Create Draft PR - description: "INSIDE target_path: Create draft PR linked to issue. PR title should reference issue number. The PR is against the target's default branch. Use attached resource 12 (pr-description) for the PR description template — use the 'Initial' template since implementation has not started yet. CRITICAL: Resolve all repository URLs from git remotes — run 'git remote get-url origin' in the parent repo for the engineering link and in target_path for the target repo link. NEVER infer or guess org/repo names." - skill: github-cli-protocol + description: "INSIDE target_path: Create draft PR linked to issue. PR title should reference issue number (for Jira, include the issue key so the Development panel auto-links the PR). The PR is against the target's default branch. Use attached resource 12 (pr-description) for the PR description template — use the 'Initial' template since implementation has not started yet. CRITICAL: Resolve all repository URLs from git remotes — run 'git remote get-url origin' in the parent repo for the engineering link and in target_path for the target repo link. NEVER infer or guess org/repo names. After creation, self-assign the PR to the current GitHub user: run 'gh pr edit <pr_number> --add-assignee @me' inside target_path. Capture pr_number and pr_url for the link-pr-to-ticket step." checkpoint: pr-creation condition: type: and @@ -191,10 +185,37 @@ steps[20]: variable: use_existing_pr operator: == value: false + actions[3]: + - action: set + target: pr_number + description: "PR number captured from gh pr create output" + - action: set + target: pr_url + description: "PR URL captured from gh pr create output" + - action: set + target: pr_exists + value: true + description: "Mark PR as existing once successfully created so downstream activities (validate, strategic-review, submit-for-review) see the correct state" + - id: link-pr-to-ticket + name: Link PR to Ticket + description: "Record the PR reference on the issue using the ticket platform's native mechanism so the PR appears in the issue's linked-PRs view. (1) For Jira: the PR is auto-linked via the Development panel when the branch name and PR title contain the issue key (already enforced upstream) — verify by calling getJiraIssue and confirming the PR is detectable. As a durable fallback that does not depend on the Atlassian-GitHub integration, also add a comment to the issue via addCommentToJiraIssue with body 'Pull Request: <pr_url>'. If the project exposes a custom 'Pull Request URL' field, prefer editJiraIssue to set that field instead of (or in addition to) the comment. (2) For GitHub: the PR body's 'Closes #<issue_number>' reference (from the Initial PR template in resource 12) already creates the native cross-link — verify the issue's timeline shows the PR reference via 'gh issue view <issue_number>'. (3) If issue_skipped is true, skip this step." + condition: + type: and + conditions[3]: + - type: simple + variable: is_review_mode + operator: "!=" + value: true + - type: simple + variable: pr_number + operator: exists + - type: simple + variable: issue_skipped + operator: "!=" + value: true - id: initialize-planning-folder name: Initialize Planning Folder description: "Create planning folder at .engineering/artifacts/planning/YYYY-MM-DD-{initiative-name}/ using artifact-management skill. Derive initiative-name from issue title. Use attached resource 01 (readme) for the README.md template — populate header fields, Executive Summary, Links table, and Progress table from issue context. Leave Problem Overview and Solution Overview as placeholder text." - skill: manage-artifacts - id: determine-next-activity name: Determine Next Activity description: "Based on issue details, determine if requirements elicitation is needed" @@ -480,13 +501,14 @@ transitions[1]: isDefault: true exitActions[1]{action,message}: log,"Issue management complete - issue verified/created, PR ready" -outcome[5]: +outcome[6]: - Issue exists or is created in appropriate platform - Issue transitioned to In Progress and assigned to current user - Feature branch created from main - - Draft PR created and linked to issue + - Draft PR created, assigned to current GitHub user, and linked to issue + - PR reference recorded on the issue via the platform's native PR linkage (Jira Development panel / comment, or GitHub timeline cross-reference) - Planning folder initialized -context_to_preserve[16]: +context_to_preserve[17]: - issue_number - The associated issue number (GitHub #N or Jira KEY-N) - issue_platform - github or jira - issue_type - Type of issue (feature, bug, task, enhancement, epic) @@ -494,6 +516,7 @@ context_to_preserve[16]: - issue_assignee_account_id - Account ID of the assigned user (Jira) - branch_name - Feature branch name - pr_number - Draft PR number (new or existing) + - pr_url - URL to the PR (used to link the PR to the ticket) - project_type - Detected project type (rust-substrate or other) - planning_folder_path - Path to planning artifacts folder - on_feature_branch - Whether already on a feature branch (not main/master) diff --git a/work-package/activities/02-design-philosophy.toon b/work-package/activities/02-design-philosophy.toon index bca86657..661be273 100644 --- a/work-package/activities/02-design-philosophy.toon +++ b/work-package/activities/02-design-philosophy.toon @@ -25,16 +25,17 @@ artifacts[2]: location: planning description: "Log of assumptions made throughout the work package - created here and updated in subsequent activities" skills: - primary: meta/activity-worker + supporting[3]: + - classify-problem + - reconcile-assumptions + - review-assumptions steps[9]: - id: define-problem name: Identify and Define Problem description: "Create clear problem statement with system understanding, impact assessment, success criteria, and constraints." - skill: classify-problem - id: classify-problem name: Classify Problem Type description: "Determine if this is a specific problem (cause known/unknown) or an inventive goal (improvement/prevention). Assess complexity." - skill: classify-problem checkpoint: classification-confirmed - id: determine-path name: Determine Workflow Path @@ -48,26 +49,21 @@ steps[9]: - id: document-philosophy name: Document Design Philosophy description: "Create design-philosophy.md with problem statement, classification, complexity assessment, workflow path rationale, and constraints." - skill: classify-problem actions[1]: - action: message message: "Created: design-philosophy.md" - id: collect-assumptions name: Collect assumptions description: "Identify assumptions made during problem classification and path selection. Categories: Problem Interpretation, Complexity Assessment, Workflow Path." - skill: review-assumptions - id: create-assumptions-log name: Create assumptions log description: "Create the assumptions log with initial assumptions from this activity." - skill: review-assumptions - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions - id: assess-ticket-completeness name: Assess Ticket Completeness description: "Assess associated ticket using Jira Issue Creation Guide checklist (problem statement, goal, scope, acceptance criteria, user stories). Document gaps and offer to refactor." - skill: classify-problem checkpoint: ticket-completeness condition: type: simple @@ -96,7 +92,6 @@ loops[1]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions checkpoints[3]: - id: classification-confirmed name: Classification Checkpoint diff --git a/work-package/activities/03-requirements-elicitation.toon b/work-package/activities/03-requirements-elicitation.toon index 282a4367..289ac064 100644 --- a/work-package/activities/03-requirements-elicitation.toon +++ b/work-package/activities/03-requirements-elicitation.toon @@ -10,34 +10,32 @@ recognition[3]: required: false estimatedTime: 15-30m skills: - primary: meta/activity-worker + supporting[4]: + - elicit-requirements + - manage-artifacts + - reconcile-assumptions + - review-assumptions steps[6]: - id: stakeholder-discussion name: Stakeholder Discussion description: "Prompt user to initiate discussion with key stakeholders. User provides transcript or summary as input for subsequent elicitation." - skill: elicit-requirements checkpoint: stakeholder-transcript - id: elicit-requirements name: Elicit requirements through conversation description: "Iterate through question domains, asking one question at a time. Use stakeholder transcript as context." - skill: elicit-requirements checkpoint: domain-iteration - id: collect-assumptions name: Collect assumptions description: "Identify assumptions made when interpreting user responses. Categories: Requirement Interpretation, Scope Boundaries, Implicit Requirements, Success Criteria Interpretation." - skill: review-assumptions - id: create-document name: Create requirements document description: "Create requirements document using elicitation output template" - skill: manage-artifacts - id: update-assumptions-log name: Update assumptions log description: "Add requirements-phase assumptions to the assumptions log" - skill: review-assumptions - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions checkpoint: elicitation-complete artifacts[1]: - id: requirements-document @@ -57,7 +55,6 @@ loops[2]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions - id: domain-iteration name: Question Domain Iteration type: forEach @@ -68,11 +65,9 @@ loops[2]: - id: ask-question name: Ask domain question description: "Present ONE question from current domain. Wait for response before proceeding." - skill: elicit-requirements - id: record-response name: Record response description: "Capture answer or mark as skipped. Adapt follow-up based on response." - skill: elicit-requirements decisions[1]: - id: user-intent name: User Intent Check diff --git a/work-package/activities/04-research.toon b/work-package/activities/04-research.toon index 791e2125..68e8f264 100644 --- a/work-package/activities/04-research.toon +++ b/work-package/activities/04-research.toon @@ -10,38 +10,36 @@ recognition[3]: required: false estimatedTime: 20-45m skills: - primary: meta/activity-worker + supporting[5]: + - knowledge-base-search + - manage-artifacts + - reconcile-assumptions + - research-knowledge-base + - review-assumptions steps[9]: - id: kb-research name: Knowledge base research description: "Call get_guidance before making concept-rag MCP tool calls. Search for relevant patterns and practices." - skill: knowledge-base-search - id: web-research name: Web research description: "Search web for current information, documentation, and best practices" - skill: research-knowledge-base - id: synthesize name: Synthesize findings description: "Connect findings to requirements: which patterns apply, what modifications needed, risks, success metrics" - skill: research-knowledge-base checkpoint: research-findings - id: collect-assumptions name: Collect assumptions description: "Identify assumptions made during research synthesis. Categories: Pattern Applicability, Source Relevance, Synthesis Decisions, Risk Assessment." - skill: review-assumptions checkpoint: research-focus - id: document name: Create research document description: "Create knowledge base research document" - skill: manage-artifacts - id: update-assumptions-log name: Update assumptions log description: "Add research-phase assumptions to the assumptions log" - skill: review-assumptions - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions - id: present-resolved-assumptions name: Present resolved assumptions description: "Display all code-resolved assumptions as a message to the user (non-interactive). Show each assumption's ID, statement, evidence, and resolution status. This provides context before the interview loop." @@ -51,7 +49,6 @@ steps[9]: - id: interview-open-assumptions name: Interview open assumptions description: "For each open (stakeholder-dependent) assumption, present it individually to the user via the research-assumption-interview checkpoint. The user can resolve it inline or defer it to stakeholder review. Update the assumptions log after each response." - skill: review-assumptions loops[2]: - id: assumption-reconciliation name: Assumption Reconciliation Loop @@ -66,7 +63,6 @@ loops[2]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions - id: assumption-interview name: Assumption Interview Loop type: forEach @@ -78,12 +74,10 @@ loops[2]: - id: present-assumption name: Present assumption to user description: "Present the current open assumption via the research-assumption-interview checkpoint. Include the assumption statement, category, and any partial evidence." - skill: review-assumptions checkpoint: research-assumption-interview - id: record-response name: Record user response description: "Update assumptions-log.md with the user's response: if resolved inline, mark as Resolved with the user's explanation. If deferred, mark as Deferred-to-Stakeholder." - skill: review-assumptions artifacts[1]: - id: research-document name: kb-research.md diff --git a/work-package/activities/05-implementation-analysis.toon b/work-package/activities/05-implementation-analysis.toon index 3b13ffb0..e7f883fb 100644 --- a/work-package/activities/05-implementation-analysis.toon +++ b/work-package/activities/05-implementation-analysis.toon @@ -10,7 +10,11 @@ recognition[3]: required: false estimatedTime: 10-20m skills: - primary: meta/activity-worker + supporting[4]: + - analyze-implementation + - manage-artifacts + - reconcile-assumptions + - review-assumptions steps[12]: - id: checkout-baseline name: Checkout Baseline State @@ -23,7 +27,6 @@ steps[12]: - id: document-expected-changes name: Document Expected Changes description: "Based on ticket requirements and baseline analysis, document what changes SHOULD be made to fulfill requirements. This becomes the reference for evaluating the actual PR." - skill: analyze-implementation condition: type: simple variable: is_review_mode @@ -40,32 +43,25 @@ steps[12]: - id: review-implementation name: Review implementation description: "Understand where and how the feature/component is used: location, usage, dependencies, architecture." - skill: analyze-implementation - id: evaluate-effectiveness name: Evaluate effectiveness description: "Gather evidence of existing performance: logs, metrics, tests, issues, comments" - skill: analyze-implementation - id: establish-baselines name: Establish baseline metrics description: "Establish quantitative measurements: performance, quality, usage, reliability" - skill: analyze-implementation - id: collect-assumptions name: Collect assumptions description: "Identify assumptions made during analysis. Categories: Current Behavior, Gap Identification, Baseline Interpretation, Dependency Understanding." - skill: review-assumptions - id: document name: Create analysis document description: "Create implementation analysis document" - skill: manage-artifacts checkpoint: analysis-confirmed - id: update-assumptions-log name: Update assumptions log description: "Add analysis-phase assumptions to the assumptions log" - skill: manage-artifacts - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions - id: present-resolved-assumptions name: Present resolved assumptions description: "Display all code-resolved assumptions as a message to the user (non-interactive). Show each assumption's ID, statement, evidence, and resolution status." @@ -75,7 +71,6 @@ steps[12]: - id: interview-open-assumptions name: Interview open assumptions description: "For each open (stakeholder-dependent) assumption, present it individually to the user via the analysis-assumption-interview checkpoint. The user can resolve it inline or defer it to stakeholder review. Update the assumptions log after each response." - skill: review-assumptions loops[2]: - id: assumption-reconciliation name: Assumption Reconciliation Loop @@ -90,7 +85,6 @@ loops[2]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions - id: assumption-interview name: Assumption Interview Loop type: forEach @@ -102,12 +96,10 @@ loops[2]: - id: present-assumption name: Present assumption to user description: "Present the current open assumption via the analysis-assumption-interview checkpoint." - skill: review-assumptions checkpoint: analysis-assumption-interview - id: record-response name: Record user response description: "Update assumptions-log.md: if resolved inline, mark Resolved. If deferred, mark Deferred-to-Stakeholder." - skill: manage-artifacts artifacts[1]: - id: analysis-document name: implementation-analysis.md diff --git a/work-package/activities/06-plan-prepare.toon b/work-package/activities/06-plan-prepare.toon index ac1e5756..b3498f7a 100644 --- a/work-package/activities/06-plan-prepare.toon +++ b/work-package/activities/06-plan-prepare.toon @@ -10,50 +10,48 @@ recognition[3]: required: true estimatedTime: 20-45m skills: - primary: meta/activity-worker + supporting[7]: + - classify-problem + - create-plan + - create-test-plan + - manage-git + - reconcile-assumptions + - review-assumptions + - update-pr steps[10]: - id: apply-design name: Apply design framework description: Use design framework skill to structure the approach - skill: classify-problem - id: create-plan name: Create work package plan description: "Create work package plan document" - skill: create-plan - id: create-test-plan name: Create test plan description: "Create test plan document" - skill: create-test-plan - id: present-solution-overview name: Present Solution Overview description: "Synthesize and present a plain-language solution overview to the user. Write exactly two paragraphs in simple, accessible language suitable for non-technical stakeholders. The first paragraph should describe what the solution does and how it addresses the problem. The second paragraph should explain how the fix works at a high level — what changes are made and what guarantees they provide. Do not use jargon without explanation. Base the overview on the work package plan, test plan, and design decisions made during this activity. After generating the overview, write it into the planning folder README.md by replacing the placeholder text under the '## Solution Overview' section." - skill: create-plan actions[1]: - action: message message: "**Solution Overview** (plain-language summary for stakeholder reference)" - id: collect-assumptions name: Collect assumptions description: "Identify assumptions made during planning. Categories: Design Approach, Task Breakdown, Dependency Assumptions, Test Strategy, Scope Decisions." - skill: review-assumptions - id: update-assumptions-log name: Update assumptions log description: "Add planning-phase assumptions to the assumptions log" - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions - id: create-todos name: Create TODO list from plan description: "Break down plan into actionable tasks and add to assumptions log for review" - skill: create-plan - id: sync-branch name: Sync feature branch with main description: Ensure feature branch is up to date with main - skill: manage-git - id: update-pr name: Update PR description description: "Update PR description with planning information. Use attached resource 12 (pr-description) for the PR description template — use the 'Initial' template and populate with planning details (summary, motivation, planned changes, checklist, fork strategy)." - skill: update-pr checkpoint: approach-confirmed loops[1]: - id: assumption-reconciliation @@ -69,7 +67,6 @@ loops[1]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions artifacts[2]: - id: plan-document name: work-package-plan.md diff --git a/work-package/activities/07-assumptions-review.toon b/work-package/activities/07-assumptions-review.toon index f4dde73a..e18a2096 100644 --- a/work-package/activities/07-assumptions-review.toon +++ b/work-package/activities/07-assumptions-review.toon @@ -10,16 +10,17 @@ recognition[3]: required: true estimatedTime: 10-20m skills: - primary: meta/activity-worker + supporting[3]: + - atlassian-operations + - manage-artifacts + - review-assumptions steps[4]: - id: evaluate-open-assumptions name: Evaluate which assumptions are open description: "Read assumptions-log.md from the planning folder. Collect all assumptions with status 'open' or 'partially-validated' that require user input. If none remain, set has_open_assumptions=false and stakeholder_review_complete=true — the interview loop will be skipped. Otherwise, set has_open_assumptions=true and prepare the list of assumptions to review." - skill: review-assumptions - id: interview-assumptions name: Interview user on each assumption description: "For each open assumption, yield a checkpoint_pending with: (1) the assumption ID and statement, (2) a rationale paragraph explaining why the assumption was made, what evidence exists for and against it, and what the consequences are if it's wrong — written to help the user make an informed decision, (3) the assumption-decision checkpoint options. After the user responds, record the decision (accepted, rejected with correction, or deferred) and continue to the next assumption. After all assumptions are reviewed, update the assumptions log with all decisions." - skill: review-assumptions condition: type: and conditions[2]: @@ -34,11 +35,9 @@ steps[4]: - id: update-assumptions-log name: Update assumptions log with decisions description: "Update assumptions-log.md with the user's decisions for each reviewed assumption. Mark accepted assumptions as 'validated', rejected as 'invalidated' with the user's correction, and deferred as 'deferred'. Set stakeholder_review_complete=true." - skill: manage-artifacts - id: post-summary name: Post resolution summary to issue tracker description: "Post a brief summary of assumption resolutions to the issue tracker ONLY when deferred assumptions exist that require external stakeholder attention. If all assumptions were accepted or rejected during the interview, skip posting — the decisions are recorded in the assumptions log and no external review is needed. Uses GitHub gh CLI or Jira API depending on issue_platform." - skill: atlassian-operations checkpoint: post-summary-review condition: type: and @@ -64,12 +63,10 @@ loops[1]: - id: present-assumption name: Present assumption with rationale description: "Yield checkpoint_pending for the current assumption. The context must include: the assumption ID, the assumption statement, and a rationale paragraph (2-4 sentences) that explains why this assumption was made, what evidence supports it, and what happens if it's wrong." - skill: review-assumptions checkpoint: assumption-decision - id: record-decision name: Record user decision description: "Record the user's response for this assumption. If rejected, capture the correction text." - skill: manage-artifacts artifacts[1]: - id: assumptions-log name: assumptions-log.md diff --git a/work-package/activities/08-implement.toon b/work-package/activities/08-implement.toon index 6188463d..15826736 100644 --- a/work-package/activities/08-implement.toon +++ b/work-package/activities/08-implement.toon @@ -1,5 +1,5 @@ id: implement -version: 2.6.2 +version: 2.6.4 name: Implement Tasks description: "Execute the implementation plan task by task. Each task follows a cycle of implement → test → commit. Assumptions are collected during each task, reconciled through code analysis after all tasks complete, and only unresolvable assumptions are presented to the user." problem: User needs to implement the planned tasks @@ -18,7 +18,13 @@ artifacts[1]: entryActions[1]{action,target,message}: validate,branch,Verify on correct feature branch before any code changes skills: - primary: meta/activity-worker + supporting[6]: + - implement-task + - manage-git + - reconcile-assumptions + - review-assumptions + - validate-build + - cargo-operations loops[3]: - id: task-cycle name: Task Implementation Cycle @@ -28,23 +34,19 @@ loops[3]: steps[5]: - id: implement-task name: Implement task - skill: implement-task checkpoint: switch-model-pre-impl - id: run-tests name: Run tests - skill: validate-build + description: "cargo-operations::test(scope: '-p {current_task.crate}')" - id: commit name: Commit changes - skill: manage-git - id: self-review name: Self-review description: "Perform task completion review: (1) Symbol verification — confirm all new/referenced symbols have provenance in codebase or dependencies; (2) Quality checks — code follows patterns, tests pass, no debug prints, no untracked TODOs. Use attached resource 14 for verification checklist." - skill: implement-task checkpoint: symbol-provenance-confirmed - id: collect-assumptions name: Collect assumptions description: "Identify all assumptions made during this task. Accumulate — do not review yet." - skill: review-assumptions - id: assumption-reconciliation name: Assumption Reconciliation Loop type: while @@ -58,7 +60,6 @@ loops[3]: - id: reconcile-iteration name: Execute Reconciliation Iteration description: "Execute one iteration of the reconcile-assumptions protocol: classify resolvability, perform targeted analysis, update logs, and reclassify for convergence." - skill: reconcile-assumptions - id: assumption-interview name: Assumption Interview Loop type: forEach @@ -70,17 +71,14 @@ loops[3]: - id: present-assumption name: Present assumption to user description: "Present the current open assumption via the implementation-assumption-interview checkpoint." - skill: review-assumptions checkpoint: implementation-assumption-interview - id: record-response name: Record user response description: "Update assumptions-log.md: if resolved inline, mark Resolved. If deferred, mark Deferred-to-Stakeholder." - skill: review-assumptions steps[4]: - id: reconcile-assumptions name: Reconcile assumptions description: "Classify all accumulated implementation assumptions by resolvability (code-analyzable vs stakeholder-dependent). Iteratively resolve code-analyzable assumptions through targeted codebase analysis using the reconcile-assumptions skill. Continue until no code-resolvable assumptions remain (convergence). Update assumptions-log.md and comprehension artifact with findings." - skill: reconcile-assumptions checkpoint: confirm-implementation - id: present-resolved-assumptions name: Present resolved assumptions @@ -91,7 +89,6 @@ steps[4]: - id: interview-open-assumptions name: Interview open assumptions description: "For each open (stakeholder-dependent) assumption, present it individually to the user via the implementation-assumption-interview checkpoint. The user can resolve it inline or defer it to stakeholder review. Update the assumptions log after each response." - skill: review-assumptions - id: update-assumptions-log name: Update assumptions log description: "Record all implementation assumptions, reconciliation outcomes, and user interview responses in the assumptions log." diff --git a/work-package/activities/09-post-impl-review.toon b/work-package/activities/09-post-impl-review.toon index 3b1b6445..301ae98a 100644 --- a/work-package/activities/09-post-impl-review.toon +++ b/work-package/activities/09-post-impl-review.toon @@ -17,7 +17,13 @@ rules[4]: entryActions[1]{action,message}: log,Starting post-implementation review skills: - primary: meta/activity-worker + supporting[6]: + - prism/structural-analysis + - review-code + - review-diff + - review-test-suite + - summarize-architecture + - version-control artifacts[6]: - id: change-block-index name: "change-block-index.md" @@ -47,18 +53,15 @@ steps[7]: - id: manual-diff-review name: Manual Diff Review description: "Structured manual review using external diff tool. Generate file index, collect flagged rows from user, interview for each finding. See manual-diff-review resource for detailed procedure." - skill: review-diff required: true checkpoint: file-index-table - id: code-review name: Code Review description: "Perform comprehensive code review of all implementation changes. Create code-review.md report." - skill: review-code required: true - id: structural-analysis-inline name: Structural Analysis (Single Pass) description: "Load the L12 structural lens from the prism workflow (prism resource 00 — attached to skill response via get_skill) and apply it to the changed files. Produces conservation law, meta-law, and classified bug table. Write findings to structural-findings.md. This inline pass runs for simple and moderate complexity work packages." - skill: prism/structural-analysis required: true condition: type: not @@ -86,12 +89,10 @@ steps[7]: - id: test-suite-review name: Test Suite Review description: "Review test quality and create test-suite-review.md report. Covers coverage gaps, anti-patterns, missing edge cases." - skill: review-test-suite required: true - id: architecture-summary name: Architecture Summary description: "Create architecture-summary.md if the diff introduces new modules, changes dependency structure, or modifies public interfaces. Skipped for minor changes, documentation, or configuration." - skill: summarize-architecture required: false condition: type: simple @@ -192,7 +193,6 @@ loops[1]: - id: apply-fixes name: Apply Fixes description: "Implement the code review findings (needs_code_fixes) and/or test improvements (needs_test_improvements) selected by the user. Commit changes." - skill: version-control required: true - id: reset-fix-flags name: Reset Fix Flags @@ -201,22 +201,18 @@ loops[1]: - id: regenerate-index name: Regenerate Change Block Index description: "Re-parse git diff and regenerate change-block-index.md reflecting the new changes." - skill: version-control required: true - id: re-manual-diff-review name: Re-run Manual Diff Review description: "Present updated file index to user for manual diff review of the fix changes." - skill: review-diff required: true - id: re-code-review name: Re-run Code Review description: "Re-run code review on the updated diff to verify fixes resolved prior findings. May set needs_code_fixes if new issues are found." - skill: review-code required: true - id: re-test-suite-review name: Re-run Test Suite Review description: "Re-run test suite review to verify fix quality. May set needs_test_improvements if new issues are found." - skill: review-test-suite required: true decisions[1]: - id: blocker-gate diff --git a/work-package/activities/10-validate.toon b/work-package/activities/10-validate.toon index e9c01b4e..415d38a4 100644 --- a/work-package/activities/10-validate.toon +++ b/work-package/activities/10-validate.toon @@ -1,7 +1,7 @@ id: validate -version: 2.5.0 +version: 3.0.0 name: Verify & Validate Design -description: "Validate the implementation through testing and build verification. Test suite quality was already reviewed in implement phase." +description: "Validate the implementation by running tests, build, format, and lint via cargo-operations (Rust/Substrate) or project-equivalent commands, then aggregate results via validate-build. Test suite quality was reviewed at the implement phase." problem: User needs to validate the implementation passes all tests recognition[3]: - validate implementation @@ -9,41 +9,42 @@ recognition[3]: - verify build required: true estimatedTime: 15-30m -skills: - primary: meta/activity-worker -steps[9]: - - id: run-tests - name: Run all tests - description: "Execute unit, integration, e2e tests. Observe and record results." - skill: validate-build - - id: verify-build - name: Verify build succeeds - description: "Run build. Observe and record result." - skill: validate-build - - id: check-format - name: Check formatting - description: "Run the canonical formatting check (e.g. cargo fmt --all -- --check for Rust). This must match the exact CI command. Formatting diffs are treated as failures." - skill: validate-build - - id: check-lint - name: Check for linter errors - description: "Run linter. Observe and record results." - skill: validate-build +operations[7]: + - "cargo-operations::preflight" + - "cargo-operations::run-suite" + - "cargo-operations::build-release" + - "validate-build::analyze-failure" + - "validate-build::apply-fix" + - "validate-build::aggregate-results" + - "manage-artifacts::verify-readme-conforms" +steps[7]: + - id: preflight + name: Toolchain preflight + description: "cargo-operations::preflight() — fail fast when toolchain prerequisites (protoc, openssl headers, pkg-config, etc.) are missing, BEFORE attempting any workspace cargo command. Surfaces missing dependencies as an environment finding rather than a partial workspace compile." + when: "project_type == 'rust-substrate'" + actions[1]: + - action: validate + target: "missing_prerequisites.length == 0" + message: "Install missing toolchain prerequisites before validation: {missing_prerequisites}" + - id: run-suite + name: Run validation suite + description: "cargo-operations::run-suite(scope: '--workspace') — runs check, clippy, test, and fmt-check concurrently and emits a single validation_results envelope. Replaces the four previous serial steps." + when: "project_type == 'rust-substrate'" - id: evaluate-results name: Evaluate validation results - description: "Set has_failures to true if any test, build, format, or lint check failed. Set validation_passed to true if all checks passed." + description: "Read validation_results from cargo-operations::run-suite. Set has_failures and validation_passed from it." actions[2]: - action: set target: has_failures value: true - message: "Set to true if any test/build/lint failure was observed; false otherwise" + message: "true when validation_results.validation_passed is false; false otherwise" - action: set target: validation_passed value: true - message: "Set to true if all checks passed; false otherwise" + message: "Mirrors validation_results.validation_passed" - id: document-failures name: Document Failures as Findings description: "Document all test/build/lint failures as review findings with severity (critical for test failures, high for build failures). Do NOT attempt to fix." - skill: validate-build condition: type: simple variable: is_review_mode @@ -52,7 +53,6 @@ steps[9]: - id: assess-test-coverage name: Assess Test Coverage description: "Evaluate whether the tests added are sufficient for the changes made. Check coverage of edge cases and error paths." - skill: validate-build condition: type: simple variable: is_review_mode @@ -60,8 +60,7 @@ steps[9]: value: true - id: fix-failures name: Fix any failures - description: "Analyze root cause of failures, fix, and re-validate." - skill: validate-build + description: "Enter the fix-revalidate-cycle loop. Each iteration calls validate-build::analyze-failure for a failed check, validate-build::apply-fix for the chosen strategy, and re-runs the affected cargo-operations op." condition: type: and conditions[2]: @@ -76,7 +75,6 @@ steps[9]: - id: scan-commit-signatures-for-strategic name: Scan PR commit signatures (preflight) description: "In target_path, resolve MERGE_BASE against the default branch (try origin/main, origin/master, main, master in order). Run git log --format='%h %G? %s' MERGE_BASE..HEAD. If ANY line has %G? of N (no signature) or B (bad), set unsigned_commits_in_pr to true and populate unsigned_commit_list_summary with a concise list of affected commits; otherwise set unsigned_commits_in_pr to false and clear the summary. Review mode uses the same branch/PR under review. This runs before strategic-review so the orchestrator can resolve the unsigned-commits checkpoint with accurate state." - skill: manage-git actions[2]: - action: set target: unsigned_commits_in_pr @@ -97,16 +95,13 @@ loops[1]: steps[3]: - id: analyze-failure name: Analyze Failure Root Cause - description: "Identify the root cause of each test/build/lint failure." - skill: validate-build + description: "validate-build::analyze-failure(check_id: {failed_check_id}, diagnostics: {failed_check_diagnostics}, target_path: {target_path})" - id: apply-fix name: Apply Fix - description: "Implement the fix for the identified root cause." - skill: validate-build + description: "validate-build::apply-fix(check_id: {failed_check_id}, fix_strategy: {fix_strategy})" - id: revalidate name: Re-run Validation - description: "Re-run the failing checks. Update has_failures based on results." - skill: validate-build + description: "Re-run cargo-operations::run-suite(scope: '--workspace') to re-validate after fix application. validation_results is updated atomically; has_failures = !validation_results.validation_passed. (run-suite already covers all four sub-checks concurrently, so a single re-run captures the full post-fix state.)" transitions[1]: - to: strategic-review isDefault: true diff --git a/work-package/activities/11-strategic-review.toon b/work-package/activities/11-strategic-review.toon index 80dd18bf..09e6bc5f 100644 --- a/work-package/activities/11-strategic-review.toon +++ b/work-package/activities/11-strategic-review.toon @@ -10,7 +10,9 @@ recognition[3]: required: true estimatedTime: 15-30m skills: - primary: meta/activity-worker + supporting[2]: + - manage-git + - review-strategy artifacts[2]: - id: strategic-review-doc name: "strategic-review-{n}.md" @@ -20,16 +22,14 @@ artifacts[2]: name: "architecture-summary.md" location: planning description: "High-level architecture summary for management stakeholders. Uses UML-style diagrams (system context, package, sequence) to visualize changes. See architecture-summary resource for template." -steps[9]: +steps[11]: - id: diff-review name: Review diff description: "Examine all changes in the PR for scope and relevance" - skill: review-strategy checkpoint: unsigned-commits-prompt - id: resign-unsigned-pr-commits name: Re-sign unsigned commits description: "Only when resign_unsigned_commits_requested is true. In target_path, rebase onto MERGE_BASE (same resolution as validate scan) and re-sign each commit: e.g. git rebase --exec 'git commit --amend --no-edit -S' MERGE_BASE (or equivalent interactive rebase) so every commit in MERGE_BASE..HEAD ends with a good GPG signature. Then git log --format='%h %G?' MERGE_BASE..HEAD to confirm no N/B remains. If push is required, use git push --force-with-lease. Set unsigned_commits_in_pr to false and resign_unsigned_commits_requested to false on success; document any failure in strategic-review-{n}.md." - skill: manage-git condition: type: simple variable: resign_unsigned_commits_requested @@ -38,19 +38,28 @@ steps[9]: - id: identify-artifacts name: Identify artifacts description: "Find investigation artifacts, over-engineering, orphaned infrastructure" - skill: review-strategy + - id: verify-readme + name: Verify README conforms to template + description: "manage-artifacts::verify-readme-conforms(planning_folder_path: {planning_folder_path}). When readme_conformance.conforms is false, surface the missing_sections / extra_top_level_headings / header_block_drift entries as an informational strategic finding to be documented in document-findings. This catches template drift that would otherwise only be flagged late by a human reviewer at submit-for-review." - id: ensure-changes-folder-entry name: Ensure changes/ fragment when required - description: "If a directory named changes exists at the repository root of target_path (Towncrier, release notes fragments, or similar), inspect existing fragment filenames and bodies. Determine whether this work package already has a matching fragment (same issue/ticket id in the name or clearly linked content). If not, add one new fragment under changes/ that matches the naming pattern and structure (sections, bullets, RST/Markdown style) of the existing files. Commit it on the feature branch if appropriate. If there is no changes/ directory, skip this step." - skill: review-strategy + description: "If a directory named changes exists at the repository root of target_path (Towncrier, release notes fragments, or similar), inspect existing fragment filenames and bodies. Determine whether this work package already has a matching fragment (same issue/ticket id in the name or clearly linked content). If not, add one new fragment under changes/ that matches the naming pattern and structure (sections, bullets, RST/Markdown style) of the existing files. The fragment MUST reference the GitHub issue for this work package — use the issue_number, issue_url, and issue_platform variables already captured in start-work-package, do not re-search. When issue_platform=github, include a 'Closes: #{issue_number}' or 'Fixes: #{issue_number}' line in the body (or the full {issue_url} form when the existing fragments use that style). When issue_platform=jira and no paired GitHub tracker exists, warn the user that CI check-changes may fail and suggest creating a tracking GitHub issue or applying a skip-changes-check label. Commit it on the feature branch if appropriate. If there is no changes/ directory, skip this step." + - id: verify-change-fragment + name: Verify change fragment references the issue + description: "If target_path has a changes/ directory: locate the change fragment for this work package (matched by issue_number / pr_number in filename or body) and read it. Set fragment_references_issue = true when the body contains issue_url verbatim, false when it does not, null when no changes/ directory exists at target_path root. The validate action below blocks the activity when the reference is missing — fix the fragment and re-run rather than deferring to human review." + actions[2]: + - action: set + target: fragment_references_issue + description: "true when the located fragment body contains issue_url verbatim; false when it does not; null when no changes/ directory exists at target_path root (skip)" + - action: validate + target: "fragment_references_issue != false" + message: "Change fragment for this work package does not reference issue_url ({issue_url}). Add a 'Closes: #{issue_number}' line (GitHub) or the full issue_url (when sibling fragments use that style) to the fragment body, commit, and re-run." - id: document-findings name: Document findings - description: "Create strategic-review-{n}.md with items that should be removed or simplified" - skill: review-strategy + description: "Create strategic-review-{n}.md with items that should be removed or simplified, plus any informational findings from verify-readme and verify-change-fragment" - id: document-cleanup-recommendations name: Document Cleanup Recommendations description: "Document recommended cleanup actions as review feedback. Do NOT apply changes." - skill: review-strategy condition: type: simple variable: is_review_mode @@ -59,7 +68,6 @@ steps[9]: - id: apply-cleanup name: Apply cleanup description: "If cleanup needed, remove identified artifacts and update review document with actions taken" - skill: review-strategy condition: type: simple variable: is_review_mode @@ -68,15 +76,17 @@ steps[9]: - id: create-architecture-summary name: Create architecture summary description: "Create architecture-summary.md using the architecture-summary resource template. Include system context diagram, package diagram (if module structure affected), and sequence diagrams for key flows." - skill: review-strategy - id: analyze-strategic-findings name: Analyze Strategic Findings - description: "Analyze the severity of strategic review findings. If significant scope issues, over-engineering, or investigation artifacts are found, recommend fix-findings. If findings are minor, recommend acceptable. Set recommended_strategic_option accordingly." + description: "Analyze the severity of strategic review findings. If significant scope issues, over-engineering, or investigation artifacts are found, recommend fix-findings. If findings are minor, recommend acceptable. Set recommended_strategic_option accordingly. Also produce a concise multi-line strategic_findings_summary so the review-findings checkpoint message shows findings inline with the options — this saves the user a 'what are the findings?' round-trip." checkpoint: review-findings - actions[1]: + actions[2]: - action: set target: recommended_strategic_option description: "Set to the recommended strategic review option based on findings analysis" + - action: set + target: strategic_findings_summary + description: "Concise multi-line summary of strategic-review findings (severity tag + one-line description per finding). Empty string when no findings. Interpolated into the review-findings checkpoint message so the user sees findings alongside the options without an extra question." checkpoints[2]: - id: unsigned-commits-prompt name: Unsigned or unverified commits @@ -102,7 +112,7 @@ checkpoints[2]: resign_unsigned_commits_requested: false - id: review-findings name: Strategic Review Findings Checkpoint - message: "Strategic review complete. Based on findings analysis, the recommended action is {recommended_strategic_option}. Auto-advancing in 30s." + message: "Strategic review complete.\n\nFindings:\n{strategic_findings_summary}\n\nRecommended action: {recommended_strategic_option}. Auto-advancing in 30s." blocking: false defaultOption: acceptable autoAdvanceMs: 30000 @@ -152,9 +162,11 @@ outcome[6]: - Architecture summary created in architecture-summary.md for stakeholder communication - PR commit GPG signature expectations addressed (resign completed or user declined with documentation) - Changelog fragment added when target repo uses root changes/ and none existed for this work -context_to_preserve[5]: +context_to_preserve[7]: - review_findings - Findings from strategic review - review_passed - Whether review passed - items_removed - List of items removed during cleanup - unsigned_commits_in_pr - Whether any unsigned commits remained after strategic review - resign_unsigned_commits_requested - Whether user requested resign at checkpoint + - strategic_findings_summary - Concise multi-line summary of findings interpolated into the review-findings checkpoint message + - fragment_references_issue - Whether the change fragment references issue_url (true/false/null per verify-change-fragment) diff --git a/work-package/activities/12-submit-for-review.toon b/work-package/activities/12-submit-for-review.toon index 210b735a..59ec2efd 100644 --- a/work-package/activities/12-submit-for-review.toon +++ b/work-package/activities/12-submit-for-review.toon @@ -13,12 +13,16 @@ estimatedTime: 30-60m entryActions[1]{action,message}: log,Submitting PR for review skills: - primary: meta/activity-worker + supporting[5]: + - github-cli-protocol + - manage-git + - respond-to-pr-review + - review-code + - update-pr steps[12]: - id: consolidate-review-findings name: Consolidate Review Findings description: "Gather all findings from code review, test review, validation, and strategic review. Categorize by severity and type." - skill: review-code condition: type: simple variable: is_review_mode @@ -27,7 +31,6 @@ steps[12]: - id: generate-review-summary name: Generate Review Summary description: "Use attached resource 24 (review-mode) via get_skill (resources attached). Create structured review summary using the Consolidated Review Format template defined in that resource." - skill: review-code condition: type: simple variable: is_review_mode @@ -45,7 +48,6 @@ steps[12]: - id: post-pr-review name: Post PR Review description: "Post review to GitHub PR using 'gh pr review'. Include consolidated findings with severity ratings." - skill: github-cli-protocol condition: type: simple variable: is_review_mode @@ -54,12 +56,10 @@ steps[12]: - id: verify-commit-signatures name: Verify and sign commits description: "BEFORE pushing, check all commits on the feature branch for GPG signatures. Run 'git log main...HEAD --format=\"%h %G? %s\"' in target_path. If ANY commit shows 'N' (no signature), the agent MUST rebase and sign them: 'git rebase --exec \"git commit --amend --no-edit -S\" main' followed by 'git push --force-with-lease'. This ensures all commits are verified before review. If the target repo's AGENTS.md requires signed commits, this step is mandatory." - skill: manage-git required: true - id: push-commits name: Push all commits description: "Push all local commits to remote branch." - skill: manage-git condition: type: simple variable: is_review_mode @@ -68,7 +68,6 @@ steps[12]: - id: update-description name: Update PR description description: "Update PR description with final implementation details. Apply automatically — user can edit the PR directly in GitHub/Jira if adjustments are needed." - skill: update-pr condition: type: simple variable: is_review_mode @@ -77,7 +76,6 @@ steps[12]: - id: mark-ready name: Mark PR ready for review description: "Mark the draft PR as ready for review using gh pr ready." - skill: github-cli-protocol condition: type: simple variable: is_review_mode @@ -86,16 +84,13 @@ steps[12]: - id: await-review name: Await Manual Review description: "Wait for PR to receive manual review from team members." - skill: respond-to-pr-review checkpoint: review-received - id: process-review-comments name: Process Review Comments description: "Analyze and respond to PR review feedback." - skill: respond-to-pr-review - id: determine-review-outcome name: Determine Review Outcome description: "Based on review feedback, determine whether changes are needed." - skill: respond-to-pr-review - id: analyze-review-outcome name: Analyze Review Outcome description: "Analyze the PR review comments and classify the overall outcome. If all comments are minor/nit, recommend minor-changes. If comments indicate approval, recommend approved. If comments require significant rework, recommend significant-changes. Set recommended_outcome accordingly." diff --git a/work-package/activities/13-complete.toon b/work-package/activities/13-complete.toon index 12140278..244ac1e2 100644 --- a/work-package/activities/13-complete.toon +++ b/work-package/activities/13-complete.toon @@ -1,5 +1,5 @@ id: complete -version: 1.3.0 +version: 1.3.1 name: Complete Work Package description: "After PR is merged, wrap up the work package: create ADR (if applicable), finalize documentation, conduct retrospective, update status, and prepare for next work package." problem: User needs to finalize all documentation and close out the work package after PR merge @@ -28,12 +28,16 @@ artifacts[4]: location: reviews description: "PR review analysis document" skills: - primary: meta/activity-worker + supporting[5]: + - conduct-retrospective + - create-adr + - finalize-documentation + - manage-git + - cargo-operations steps[10]: - id: create-adr name: Create Architecture Decision Record description: "Create ADR at .engineering/artifacts/adr/ documenting the architectural decision, rationale, and alternatives." - skill: create-adr condition: type: and conditions[2]: @@ -54,7 +58,6 @@ steps[10]: - id: update-adr-status name: Update ADR status to Accepted description: "Update ADR status from Proposed to Accepted." - skill: create-adr condition: type: and conditions[2]: @@ -75,7 +78,6 @@ steps[10]: - id: finalize-test-plan name: Finalize test plan with source links description: "Add hyperlinks to actual test source file locations in the test plan." - skill: finalize-documentation condition: type: simple variable: is_review_mode @@ -84,7 +86,6 @@ steps[10]: - id: create-complete-doc name: Create completion document description: "Create COMPLETE.md summarizing deliverables, test coverage, deferred items, and known limitations." - skill: finalize-documentation condition: type: simple variable: is_review_mode @@ -93,7 +94,6 @@ steps[10]: - id: ensure-docs name: Ensure inline documentation on public APIs description: "Verify public APIs have inline documentation — add missing doc comments." - skill: finalize-documentation condition: type: simple variable: is_review_mode @@ -102,19 +102,15 @@ steps[10]: - id: capture-history name: Capture session history description: "If metadata repository exists, capture session history. Private — never committed." - skill: conduct-retrospective - id: retrospective name: Workflow retrospective description: "Conduct retrospective: what went well, what could improve, lessons learned. Skip if trivial session." - skill: conduct-retrospective - id: update-status name: Update work package plan status description: "After PR merged, update work package plan status to reflect completion." - skill: conduct-retrospective - id: resign-artifact-commits name: Re-sign all planning artifact commits description: "Apply gpg-resign-range to the parent (engineering) repo to re-sign every unsigned artifact commit made during this work package. Resolve MERGE_BASE as the point where the current engineering branch diverged from its default branch. Run: git rebase --exec 'git commit --amend --no-edit -S' MERGE_BASE in the engineering repo root. Verify all commits show G with git log --format='%h %G? %s' MERGE_BASE..HEAD, then push with --force-with-lease. This converts the full unsigned artifact history to a signed history in one operation. Requires the GPG agent to be unlocked — the user is present at this stage for post-review work." - skill: manage-git condition: type: simple variable: is_review_mode @@ -123,7 +119,6 @@ steps[10]: - id: select-next name: Select next work package description: "Identify and select next work package if applicable. Prepare context for transition." - skill: conduct-retrospective exitActions[1]{action,message}: log,Work package workflow complete outcome[6]: diff --git a/work-package/activities/14-codebase-comprehension.toon b/work-package/activities/14-codebase-comprehension.toon index c8b8b0a6..9c6312c5 100644 --- a/work-package/activities/14-codebase-comprehension.toon +++ b/work-package/activities/14-codebase-comprehension.toon @@ -12,7 +12,10 @@ recognition[5]: required: false estimatedTime: 20-45m skills: - primary: meta/activity-worker + supporting[3]: + - build-comprehension + - manage-artifacts + - portfolio-analysis rules[3]: - "The initial deep-dive is mandatory and always performed — it attempts to resolve every open question from the first pass without user selection" - "Comprehension is sufficient when all open questions have been resolved through code analysis. If unresolved questions remain after the initial deep-dive, present them with the 30s auto-advance pattern — the user can intervene to explore further or let it proceed." @@ -21,31 +24,24 @@ steps[12]: - id: check-existing-artifacts name: Check Existing Comprehension Artifacts description: "Search .engineering/artifacts/comprehension/ for existing artifacts related to this codebase area. Match by project name, module names, or domain concepts from the problem statement." - skill: manage-artifacts - id: review-existing name: Review Existing Artifacts description: "Silently review any relevant existing comprehension artifacts as baseline context. Incorporate prior knowledge into the architecture survey. If none exist, proceed to fresh analysis." - skill: build-comprehension - id: architecture-survey name: Architecture Survey description: "Perform a top-down survey of the codebase: project structure, key modules and their responsibilities, dependency graph between modules, entry points, and overarching design patterns (e.g., layered architecture, event-driven, actor model). Use a hypothesis-driven approach — form initial hypotheses about structure and verify them by examining code." - skill: build-comprehension - id: key-abstractions name: Key Abstractions and Data Model description: "Identify core types, traits, interfaces, data structures, error handling patterns, and state management approaches. Document what each key abstraction represents in domain terms and how abstractions relate to each other." - skill: build-comprehension - id: design-rationale name: Design Rationale Mapping description: "For each significant design choice observed (patterns used, architecture decisions, abstraction boundaries), infer the likely rationale — why was it built this way? What constraints or trade-offs does this design address? Document these as 'design rationale hypotheses' that the user can validate." - skill: build-comprehension - id: domain-concept-mapping name: Domain Concept Mapping description: "Map technical constructs to domain concepts: what does each module or subsystem accomplish in business/domain terms? Create a glossary of domain-specific terminology found in the codebase." - skill: build-comprehension - id: create-comprehension-artifact name: Create or Augment Comprehension Artifact description: "Write the comprehension artifact to .engineering/artifacts/comprehension/{codebase-area-name}.md. If an existing artifact covers this area, augment it with new sections rather than replacing. Include a metadata header with date, work package reference, and coverage summary. Initialize the 'Open Questions' section (markdown table with columns: #, Question, Status, Resolution, Deep-Dive Section) between Domain Concept Mapping and Deep-Dive Sections. Populate it with questions and gaps identified during the architecture survey — do not leave it empty." - skill: manage-artifacts checkpoint: architecture-confirmed actions[1]: - action: message @@ -53,23 +49,18 @@ steps[12]: - id: initial-deep-dive name: Initial Deep-Dive (Mandatory) description: "Systematically investigate every open question identified during the first pass (architecture survey, key abstractions, design rationale, domain mapping). This step is always performed — do not skip it and do not ask the user to select areas. For each open question, trace relevant data flows, examine implementation details, and resolve the question through targeted code analysis." - skill: build-comprehension - id: initial-lens-pass name: Apply Portfolio Lenses to Initial Deep-Dive description: "Apply pedagogy (prism resource 06) and rejected-paths (prism resource 09) lenses to the key modules examined during the initial deep-dive. Pedagogy reveals where inherited patterns create silent problems; rejected-paths reveals hidden design trade-offs. Apply each lens independently. Append findings to the comprehension artifact under the 'Initial Deep-Dive' section." - skill: portfolio-analysis - id: update-artifact-initial name: Update Artifact with Initial Deep-Dive Findings description: "Append the initial deep-dive findings and portfolio lens findings to the comprehension artifact under a dedicated 'Initial Deep-Dive' section, organized by the open question each finding addresses." - skill: manage-artifacts - id: revise-initial-questions name: Revise Open Questions after Initial Deep-Dive description: "Review findings from the initial deep-dive against the 'Open Questions' section. Mark investigated questions as Resolved with a one-line resolution summary and deep-dive section reference. Add any new questions surfaced during investigation. Write the updated section to the artifact. Then evaluate sufficiency: if all open questions are now Resolved, set has_open_questions to false and needs_comprehension to false — comprehension is complete, skip the checkpoint. If unresolved questions remain, set has_open_questions to true and present the revised table as context for the comprehension-sufficient checkpoint." - skill: build-comprehension - id: deep-dive-loop name: Further Deep-Dive Exploration (Optional) description: "If the user requests further exploration at the comprehension-sufficient checkpoint, enter interactive loop: present remaining open questions and areas available for deeper exploration (specific modules, patterns, data flows, error handling, etc.) and ask the user which area they want to understand better. For each selection, perform targeted analysis and append findings to the comprehension artifact." - skill: build-comprehension artifacts[1]: - id: comprehension-artifact name: "{codebase-area}.md" @@ -133,19 +124,15 @@ loops[1]: - id: targeted-analysis name: Perform targeted analysis description: "Dive into the selected area: trace data flows, examine implementation details, identify edge cases, document internal design decisions and their implications." - skill: build-comprehension - id: portfolio-lens-pass name: Apply portfolio lenses to deep-dive area description: "Load portfolio lenses from the prism workflow and apply them independently to the code under examination. Use pedagogy (prism resource 06 — attached to skill response via get_skill) to trace where inherited patterns create silent problems, and rejected-paths (prism resource 09 — attached to skill response via get_skill) to reveal what design paths were rejected and what problems they would swap. Apply each lens independently to the key files in the deep-dive area. Append per-lens findings and a cross-lens synthesis (convergent vs unique) to the comprehension artifact under the current deep-dive section." - skill: portfolio-analysis - id: update-artifact name: Update comprehension artifact description: "Append deep-dive findings and portfolio lens findings to the comprehension artifact under a dedicated section for this area." - skill: manage-artifacts - id: revise-open-questions name: Revise open questions description: "Review findings from this iteration (including portfolio lens findings) against the 'Open Questions' section in the comprehension artifact. Mark investigated questions as Resolved with a one-line resolution summary and deep-dive section reference. Add any new questions surfaced during investigation — including structural properties revealed by the lenses. Write the updated section to the artifact. If all questions are now Resolved, set has_open_questions to false and needs_comprehension to false — loop exits. Otherwise present the revised table as context for the sufficiency checkpoint." - skill: build-comprehension checkpoint: comprehension-sufficient transitions[4]: - to: requirements-elicitation diff --git a/work-package/resources/10-wp-plan.md b/work-package/resources/10-wp-plan.md index 9ee74134..dd6e16c5 100644 --- a/work-package/resources/10-wp-plan.md +++ b/work-package/resources/10-wp-plan.md @@ -1,6 +1,6 @@ --- id: plan -version: 1.0.0 +version: 1.1.0 --- # Work Package Plan Guide @@ -281,7 +281,7 @@ Break down into discrete, estimable tasks. Each task should: - `tests/search/fusion_test.rs` - Unit tests (8+ cases) ``` -**Bad:** +**Bad — vague:** ```markdown ### Task 1: Implement search improvements @@ -289,6 +289,16 @@ Break down into discrete, estimable tasks. Each task should: - Add tests ``` +**Bad — verification-as-task / raw cargo (forbidden):** + +```markdown +### Task 2: Verify compilation +Run `cargo check` on the pallet to confirm the change compiles. + +### Task 3: Verify existing tests pass +Run `cargo test -p pallet-foo`. +``` + ### Success Criteria Link criteria to baselines from analysis. Make all criteria measurable: diff --git a/work-package/resources/12-pr-description.md b/work-package/resources/12-pr-description.md index 50773dfb..dddc2507 100644 --- a/work-package/resources/12-pr-description.md +++ b/work-package/resources/12-pr-description.md @@ -27,7 +27,7 @@ A well-written PR description serves multiple audiences: - Fix bugs or address issues - Refactor existing code - Make architectural changes -- Update dependencies with breaking changes +- Update dependencies with breaking changes/ **Simplified descriptions are acceptable for:** - Documentation-only changes @@ -47,7 +47,7 @@ A well-written PR description serves multiple audiences: [1-2 sentence summary of the change and key benefit] -🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering](link-to-start-here) 🧪 [Test Plan](link-to-test-plan) +🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering](link-to-start-here) --- @@ -140,7 +140,7 @@ A well-written PR description serves multiple audiences: [1-2 sentence summary with key benefit/metric achieved] -🎫 [Ticket](link) 📐 [Engineering](eng-repo-link) 🧪 [Test Plan](branch-link) +🎫 [Ticket](link) 📐 [Engineering](eng-repo-link) --- @@ -216,7 +216,7 @@ This PR adds some improvements to search. Always link to related artifacts on the same line for easy scanning: ```markdown -🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering]({ENG_REPO_URL}/blob/{ENG_BRANCH}/.engineering/artifacts/planning/{PLANNING_FOLDER}/README.md) 🧪 [Test Plan]({TARGET_REPO_URL}/blob/{BRANCH_NAME}/docs/tests/test-plan.md) +🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering]({ENG_REPO_URL}/blob/{ENG_BRANCH}/.engineering/artifacts/planning/{PLANNING_FOLDER}/README.md) ``` #### CRITICAL: Resolving Link Placeholders @@ -245,10 +245,6 @@ The `ENG_REPO_URL` comes from the **parent repo** (the repo containing `.enginee - **ADR** - Include for architectural decisions committed to the target repo (see [Architecture Review Guide](15-architecture-review.md)) - **Test Plan** - Include when formal test documentation exists (see [Test Plan Creation Guide](11-test-plan.md)) -**Important:** Link to ADRs and test plans on the *feature branch*, not main: -- ✅ `https://github.com/OWNER/REPO/blob/feat/hybrid-search/docs/decisions/adr-hybrid-search.md` -- ❌ `docs/decisions/adr-hybrid-search.md` (resolves to main, which won't have the file yet) - **Note:** Engineering links point to the engineering artifacts repository (not the target repo), on whatever branch the parent repo uses for engineering artifacts. Resolve the branch from `git branch --show-current` in the parent repo — do not assume `main`. ### Motivation @@ -364,116 +360,6 @@ Track remaining items before the PR can be merged: --- -### Initial PR (ADR-only) - -Template for a PR with just the ADR (before implementation): - -```markdown -## Summary - -[1-2 sentence summary of the proposed work] - - -🎫 [Ticket](link) 📐 [Engineering](eng-repo-link) - ---- - -## Motivation - -[Why this change is needed] - ---- - -## Changes - -**Implementation (coming next):** -- [Task 1 description] -- [Task 2 description] - ---- - -## 📌 Submission Checklist - -- [ ] Changes are backward-compatible (or flagged if breaking) -- [ ] Pull request description explains why the change is needed -- [ ] Self-reviewed the diff -- [ ] I have included a change file, or skipped for this reason: [reason] -- [ ] If the changes introduce a new feature, I have bumped the node minor version -- [ ] Update documentation (if relevant) -- [ ] No new todos introduced - ---- - -## 🔱 Fork Strategy - -- [ ] Node Runtime Update -- [ ] Node Client Update -- [ ] Other -- [ ] N/A - ---- - -## 🗹 TODO before merging - -- [ ] Ready for review -``` - -### Final PR (After Implementation) - -Update the description to reflect completed work: - -```markdown -## Summary - -[1-2 sentence summary with key benefit/metric achieved] - - -🎫 [Ticket](link) 📐 [Engineering](eng-repo-link) 🧪 [Test Plan](branch-link) - ---- - -## Motivation - -[Why this change was needed - can keep from initial PR] - ---- - -## Changes - -- **Component A** - [What was implemented] -- **Component B** - [What was modified] -- **Tests** - [Coverage summary] - ---- - -## 📌 Submission Checklist - -- [x] Changes are backward-compatible (or flagged if breaking) -- [x] Pull request description explains why the change is needed -- [x] Self-reviewed the diff -- [x] I have included a change file, or skipped for this reason: [reason] -- [x] If the changes introduce a new feature, I have bumped the node minor version -- [x] Update documentation (if relevant) -- [x] No new todos introduced - ---- - -## 🔱 Fork Strategy - -- [x] Node Runtime Update -- [ ] Node Client Update -- [ ] Other -- [ ] N/A - ---- - -## 🗹 TODO before merging - -- [x] Ready for review -``` - ---- - ## Updating PR Descriptions Always use the GitHub API for PR updates (`gh pr edit` uses GraphQL which fails due to Projects Classic deprecation): @@ -527,7 +413,7 @@ gh pr ready Implement content-aware chunking that preserves semantic boundaries, reducing retrieval errors by 40% on the evaluation dataset. -🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering](https://github.com/{ENG_REPO_OWNER}/{ENG_REPO_NAME}/blob/{ENG_BRANCH}/.engineering/artifacts/planning/{PLANNING_FOLDER}/README.md) 🧪 [Test Plan](https://github.com/{REPO_OWNER}/{REPO_NAME}/blob/feat/smart-chunking/docs/tests/test-plan-content-chunking.md) +🎫 [Ticket](https://{JIRA_DOMAIN}/browse/{TICKET_ID}) 📐 [Engineering](https://github.com/{ENG_REPO_OWNER}/{ENG_REPO_NAME}/blob/{ENG_BRANCH}/.engineering/artifacts/planning/{PLANNING_FOLDER}/README.md) ``` ### Good Motivation Section @@ -587,5 +473,4 @@ Before submitting a PR, verify: ## Related Guides - [Architecture Review Guide](15-architecture-review.md) -- [Test Plan Creation Guide](11-test-plan.md) - [Complete Guide](21-complete-wp.md) diff --git a/work-package/skills/08-create-plan.toon b/work-package/skills/08-create-plan.toon index 2f8dbd98..0ce3da53 100644 --- a/work-package/skills/08-create-plan.toon +++ b/work-package/skills/08-create-plan.toon @@ -1,5 +1,5 @@ id: create-plan -version: 2.0.0 +version: 2.1.0 capability: Create work package plan with task breakdown, dependencies, and ordering description: "Design the implementation approach and produce work-package-plan.md. Applies design framework to structure the approach, breaks work into atomic tasks with explicit dependencies, and documents design decisions and assumptions. Test plan creation is handled by the separate create-test-plan skill." @@ -48,6 +48,10 @@ output[1]: resources[1]: - "10" +rules: + tasks-are-code-changes-only: "Plan tasks describe CODE OR ARTIFACT CHANGES — the source edits, schema changes, doc updates, etc. that must be made to satisfy the goal. Tasks MUST NOT describe verification work (compile, test, lint, format) as separate items: verification runs after every task automatically via the implement activity's task-cycle (run-tests step → cargo-operations::test) and at the validate activity (cargo-operations::check / ::fmt-check / ::clippy). Adding 'Verify compilation', 'Verify tests pass', 'Run cargo X', or similar as a task duplicates that built-in cycle and is forbidden." + no-raw-commands-in-plan: "Plan content MUST NEVER contain raw command invocations/specification" + errors: missing_inputs: cause: Design philosophy or analysis not completed diff --git a/work-package/skills/10-implement-task.toon b/work-package/skills/10-implement-task.toon index fab268a2..b1c23b28 100644 --- a/work-package/skills/10-implement-task.toon +++ b/work-package/skills/10-implement-task.toon @@ -1,5 +1,5 @@ id: implement-task -version: 2.0.0 +version: 2.1.1 capability: Implement a single task from the work package plan by writing code changes description: "Atomic code implementation capability. Reads a task from the plan, understands the context (affected files, dependencies, requirements), and writes the code changes. Testing, committing, and assumption review are handled by other skills (validate-build, manage-git, review-assumptions) orchestrated by the activity's loop." @@ -16,13 +16,11 @@ protocol: - Read the task description and requirements from the plan - Identify affected files, dependencies, and related code - Review test plan for acceptance criteria relevant to this task - write-code[4]: + write-code[3]: - Implement the code changes for this task - Follow existing code patterns and conventions in the target codebase - - For Rust projects, follow TDD approach per resource 23 - - "For Rust projects, follow TDD best practices from resource 23 — Red-Green-Refactor, FIRST principles, test doubles, boundary testing" - verify-locally[2]: - - Verify the change compiles and basic tests pass + - "For Rust projects, follow TDD best practices from resource 23 (tdd-concepts-rust)" + verify-locally[1]: - Check for obvious regressions in affected code output[1]: diff --git a/work-package/skills/12-review-strategy.toon b/work-package/skills/12-review-strategy.toon index e26c308f..b34660e8 100644 --- a/work-package/skills/12-review-strategy.toon +++ b/work-package/skills/12-review-strategy.toon @@ -27,7 +27,7 @@ protocol: - If changes/ exists at target_path repository root, read sibling fragments as the format template - Create one new fragment only when none already ties to this issue/PR/work package - Match filename convention (e.g. type.issue.ext) and section structure of existing entries - - "REQUIRED: search for a matching GitHub issue (gh search issues using JIRA ID, PR title, or keywords). Include a Closes: #NNN or Fixes: #NNN line referencing the issue. Many repos enforce this via CI (check-changes). If no GitHub issue exists, warn the user that CI may fail without one — suggest creating an issue or adding a skip-changes-check label." + - "REQUIRED: reference the GitHub issue for this work package using the variables already captured in start-work-package — do NOT re-search. When issue_platform=github, include 'Closes: #{issue_number}' or 'Fixes: #{issue_number}' (or the full {issue_url} form when sibling fragments use that style). When issue_platform=jira, search for a paired GitHub tracker issue and reference it the same way; if none exists, warn the user that the project's CI check-changes may fail and suggest creating a tracking GitHub issue or applying a skip-changes-check label." - "Validate the completed fragment against CI requirements: must contain a GitHub issue reference matching the regex github\\.com/.+/issues/[0-9]+ or (Fixes|Closes|Resolves):?\\s+#[0-9]+" identify-artifacts[4]: - "Look for investigation artifacts: extra logging, debug messages, temporary workarounds" diff --git a/work-package/skills/14-manage-artifacts.toon b/work-package/skills/14-manage-artifacts.toon index ce45aa2b..1c175450 100644 --- a/work-package/skills/14-manage-artifacts.toon +++ b/work-package/skills/14-manage-artifacts.toon @@ -35,6 +35,29 @@ output[1]: folder_path: "Full path to planning folder" artifact_index: "Map of activity prefix to artifact filenames" +operations: + verify-readme-conforms: + description: "Verify the planning folder's README.md still matches the resource 01 template structure (header block, executive summary, problem/solution overview, progress table, links). Catches template drift that would otherwise only be flagged late in the workflow by a human reviewer." + inputs[1]: + - planning_folder_path: "Absolute path to the planning folder containing README.md" + output[1]: + - readme_conformance: "{ conforms: bool, missing_sections: [], extra_top_level_headings: [], header_block_drift: [] } — conforms is true iff missing_sections, extra_top_level_headings, and header_block_drift are all empty" + procedure[3]: + - "Read {planning_folder_path}/README.md and load resource 01 (the README template) via get_resource." + - "Extract H1/H2/H3 sections from each. Compare H2 sections against the template's required set: Executive Summary, Problem Overview, Solution Overview, Progress, Links. Compare the header block (Created/Status/Type fields) against the template's header fields." + - "Compose readme_conformance: missing_sections lists template H2s absent from the README; extra_top_level_headings lists H1s beyond the single title H1; header_block_drift lists header fields missing or renamed (e.g., a custom 'Issue:' line in place of the canonical 'Status:'/'Type:' rows). conforms is true iff all three arrays are empty." + tools: + harness[1]: + - Read + workflow-server[1]: + - get_resource + resources[1]: + - "01" + errors: + readme_missing: + cause: "No README.md found in planning_folder_path" + recovery: "Re-run manage-artifacts::create-readme protocol to seed the README from resource 01 before continuing" + rules: activity-prefix: "Artifact filenames are prefixed with the producing activity's artifactPrefix (server-computed from the activity filename). Skills declare bare names (e.g., 'code-review.md'); the prefix is applied at write time (e.g., '09-code-review.md'). This groups artifacts by activity and sorts them in workflow order." committed-to-parent: "Planning artifacts are regular files in the parent repo (.engineering/artifacts/). They MUST be committed and pushed to the parent repo before any PR or issue references them via URL, otherwise the link will 404." diff --git a/work-package/skills/16-validate-build.toon b/work-package/skills/16-validate-build.toon index 611ebf2b..a5533b35 100644 --- a/work-package/skills/16-validate-build.toon +++ b/work-package/skills/16-validate-build.toon @@ -1,52 +1,69 @@ id: validate-build -version: 1.1.0 -capability: Validate implementation through test execution, build verification, and lint checking +version: 2.0.0 +capability: Triage validation failures and aggregate cross-check results for the validate activity -description: "Runs the full validation suite: unit/integration/e2e tests, build verification, and linter checks. Analyzes failures, applies fixes, and re-runs until all pass. Provides observable results — does not ask user about test/build outcomes." +description: "Provides the orchestration operations the validate activity needs OUTSIDE of cargo execution: analysing the root cause of a failed check, applying a fix, and aggregating per-check outcomes into a single validation_results envelope. Cargo command execution lives entirely in cargo-operations — this skill never invokes cargo and never describes cargo invocations; it operates on the OUTPUTS of cargo-operations operations and on source files." -inputs[2]: - - id: project-type - description: "Project type (rust-substrate, other) — determines commands" - - id: target-submodule - description: "Target submodule path (e.g., midnight-node, midnight-ledger)" +operations: + analyze-failure: + description: "Identify the root cause of a single failed validation check" + inputs[3]: + - check_id: "Identifier of the failed check (one of: run-tests, verify-build, check-format, check-lint)" + - diagnostics: "stdout/stderr or structured diagnostics emitted by the underlying tool" + - target_path: "Path the check ran against (used to read source files referenced in diagnostics)" + output[3]: + - failure_class: "One of: compile-error, test-assertion, lint-violation, formatting-diff, environment, flaky" + - root_cause: "One-line statement of the root cause" + - fix_strategy: "Concrete fix approach (file edit, fmt-fix invocation, dependency install, etc.)" + procedure[3]: + - "Parse the diagnostics; classify into failure_class. Compile and test failures cite a file:line — read that location via the harness Read tool." + - "Distinguish flaky from real failures by inspecting the diagnostic surface (e.g., timing-related panics, network errors). Mark flaky only when there is a clear signal." + - "Map failure_class to fix_strategy. compile-error / test-assertion → source edit; formatting-diff → cargo-operations::fmt-fix; lint-violation → either source edit or an explicit allow with justification; environment → surface to the user (do not auto-install)." + tools: + harness[2]: + - Read + - Grep + errors: + ambiguous_diagnostics: + cause: "Diagnostics do not pinpoint a file or symbol" + recovery: "Surface raw diagnostics to the user as a checkpoint via the activity" -protocol: - run-tests[3]: - - Execute unit, integration, and e2e tests - - Observe and record results - - Do not ask user about test outcomes — results are observable - verify-build[2]: - - Run build command - - Observe and record result - check-format[3]: - - "Run the canonical formatting check: nice -n 19 cargo fmt --all -- --check (Rust) or equivalent for the project type" - - "This MUST match the exact command CI runs — for Rust/Substrate projects, this is cargo fmt --all -- --check which checks ALL workspace members" - - Record any formatting diffs as failures - check-lint[2]: - - Run linter - - Observe and record results - fix-failures[4]: - - If any check failed — analyze root cause - - Apply fix - - Re-run failed check - - Repeat until all pass + apply-fix: + description: "Apply the chosen fix strategy and prepare for re-validation" + inputs[2]: + - check_id: "Identifier of the originally failed check" + - fix_strategy: "fix_strategy from analyze-failure" + output[1]: + - fix_applied: "Boolean — true if the fix was applied; false if the fix requires user input or external action" + procedure[2]: + - "Execute the fix per fix_strategy: source edits go through harness Edit/Write; formatting fixes go through cargo-operations::fmt-fix; dependency or environment fixes are surfaced to the user." + - "Set fix_applied = true on success. Set fix_applied = false when the fix requires user input — the activity loop will surface this via its checkpoint." + tools: + harness[2]: + - Edit + - Write -output[1]: - - id: validation-results - description: "Validation outcomes from tests, build, and lint" - components: - test_results: "Test execution results (pass/fail, output)" - build_status: "Build success or failure" - lint_results: "Linter output and any issues" - validation_passed: "Boolean — all checks passed" + aggregate-results: + description: "Combine per-check outcomes into a single validation_results envelope" + inputs[4]: + - test_results: "Pass/fail and output captured from cargo-operations::test (or the project-equivalent test command)" + - build_status: "Pass/fail captured from cargo-operations::check or build-release (or the project-equivalent build command)" + - format_status: "Pass/fail captured from cargo-operations::fmt-check (or the project-equivalent format check)" + - lint_results: "Pass/fail and output captured from cargo-operations::clippy (or the project-equivalent linter)" + output[1]: + - validation_results: "{ test_results, build_status, format_status, lint_results, validation_passed } — validation_passed is true iff ALL inputs passed" + procedure[1]: + - "validation_passed = test_results.passed AND build_status.passed AND format_status.passed AND lint_results.passed. Emit the envelope; do not mutate any input." rules: - no-duplicate-review: "Test suite quality was already reviewed in post-impl-review — this activity validates execution only" + no-cargo-here: "This skill MUST NOT invoke cargo, describe cargo invocations, or duplicate cargo command-line text. Cargo execution belongs entirely to cargo-operations. validate-build operates on the OUTPUTS of cargo-operations operations." + no-duplicate-review: "Test suite quality was already reviewed in post-impl-review. analyze-failure focuses on root cause of execution failures, not test design." + do-not-mask-flaky: "When analyze-failure classifies a failure as flaky, surface that classification — do not silently retry. The activity loop decides whether to retry or escalate." errors: persistent_failure: - cause: Tests fail repeatedly after fixes - recovery: Present analysis to user for guidance + cause: "A check fails repeatedly after analyze-failure / apply-fix iterations" + recovery: "Surface the latest analysis to the user via the activity's checkpoint mechanism" build_environment: - cause: Missing dependencies or toolchain issues - recovery: Check project setup instructions + cause: "Diagnostics indicate a missing toolchain, dependency, or external service" + recovery: "Refer the user to the project's setup instructions; do not attempt to install or configure toolchain" diff --git a/work-package/skills/17-finalize-documentation.toon b/work-package/skills/17-finalize-documentation.toon index bda388fa..26f7e0b6 100644 --- a/work-package/skills/17-finalize-documentation.toon +++ b/work-package/skills/17-finalize-documentation.toon @@ -1,5 +1,5 @@ id: finalize-documentation -version: 1.0.0 +version: 1.2.1 capability: Finalize documentation — update ADRs, complete test plans, create completion document, ensure API documentation description: "Handles the finalization of all documentation after implementation is complete. Updates ADR status, adds source links to test plans, creates a COMPLETE.md summary document, and verifies public APIs have inline documentation." @@ -50,7 +50,7 @@ resources[1]: rules: completion-timing: "COMPLETE.md is created after implementation is complete and PR is merged. It captures the final delivered state — what was built, tested, and deferred. Update if post-merge changes occur." - tool-usage: "use shell to run cargo doc or similar to check documentation" + tool-usage: "Rust/Substrate: invoke cargo-operations.doc (scope='--workspace --no-deps') to verify documentation builds. Other project types: run the equivalent doc command for the project. This skill does not invoke cargo directly." errors: no_adr: cause: No ADR was created for this work package diff --git a/work-package/skills/24-cargo-operations.toon b/work-package/skills/24-cargo-operations.toon new file mode 100644 index 00000000..728ea582 --- /dev/null +++ b/work-package/skills/24-cargo-operations.toon @@ -0,0 +1,188 @@ +id: cargo-operations +version: 1.1.0 +capability: Resource-constrained operations for the cargo subcommands used during the work-package workflow + +description: "Operations wrapping each cargo subcommand invoked by work-package skills (check, test, build, clippy, fmt, doc). Every operation embeds the inline resource budget — nice -n 19, CARGO_BUILD_JOBS cap (default 4), RUST_TEST_THREADS cap (default 4), and SKIP_WASM_BUILD=1 for non-release commands — to prevent OOM/host-hang on memory-constrained hosts. Defaults assume ≤32 GiB RAM and ≤16 cores; raise the env caps on larger hosts." + +operations: + check: + description: "Type-check without producing binaries; the cheapest validation pass" + inputs[2]: + - scope: "'--workspace' for the full workspace, or '-p <crate>' to scope to one crate (preferred during inner loops)" + - features: "Optional --features flags (empty string when none)" + output[1]: + - check_status: "Pass/fail and the rustc diagnostics emitted" + procedure[1]: + - "nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo check {scope} {features}" + tools: + shell[1]: + - cargo + errors: + out_of_memory: + cause: "Compile peaked above available RAM even with the budget" + recovery: "Halve CARGO_BUILD_JOBS (export CARGO_BUILD_JOBS=2) and retry; if still failing, narrow scope to -p <crate>" + compile_error: + cause: "Type-check failed in the source" + recovery: "Address the rustc errors and retry" + + test: + description: "Run tests with bounded test parallelism; prefer nextest when configured" + inputs[3]: + - scope: "'--workspace' or '-p <crate>'" + - features: "Optional --features flags (empty string when none)" + - test_filter: "Optional test name filter (e.g., 'test_foo' or '--test integration'); empty string when none" + output[2]: + - test_status: "Pass/fail summary" + - failures: "Per-test failure detail when any failed" + procedure[2]: + - "If cargo nextest is configured (.config/nextest.toml present in the project): nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo nextest run {scope} {features} --test-threads=${RUST_TEST_THREADS:-4} {test_filter}" + - "Otherwise: nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo test {scope} {features} {test_filter} -- --test-threads=${RUST_TEST_THREADS:-4}" + tools: + shell[1]: + - cargo + errors: + out_of_memory: + cause: "Test compile or test runtime peaked above available RAM" + recovery: "Halve CARGO_BUILD_JOBS and RUST_TEST_THREADS and retry; consider nextest for lower per-test peak" + test_failure: + cause: "One or more tests failed" + recovery: "Investigate the reported failure; do not mask via --no-fail-fast" + + build-dev: + description: "Workspace dev build; skips the runtime wasm artifact" + inputs[2]: + - scope: "'--workspace' or '-p <crate>'" + - features: "Optional --features flags (empty string when none)" + procedure[1]: + - "nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo build {scope} {features}" + tools: + shell[1]: + - cargo + errors: + out_of_memory: + cause: "Link or codegen step exceeded available RAM" + recovery: "Halve CARGO_BUILD_JOBS and retry" + + build-release: + description: "Release build; produces the final binary AND the runtime wasm artifact" + inputs[2]: + - scope: "'--workspace' or '-p <crate>'" + - features: "Optional --features flags (empty string when none)" + procedure[2]: + - "Do NOT set SKIP_WASM_BUILD here — the wasm runtime artifact is required for release" + - "nice -n 19 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo build --release {scope} {features}" + tools: + shell[1]: + - cargo + errors: + out_of_memory: + cause: "Release link/LTO and the nested wasm build together exceeded available RAM" + recovery: "Halve CARGO_BUILD_JOBS; on tight hosts, run -p <crate> for the binary first, then a separate workspace pass for the runtime" + + clippy: + description: "Run the linter against all targets, denying warnings" + inputs[2]: + - scope: "'--workspace' or '-p <crate>'" + - features: "Optional --features flags (empty string when none)" + output[2]: + - clippy_status: "{ passed: boolean } — true when no denied warnings emitted" + - lint_diagnostics: "Captured stdout/stderr (used by validate-build::analyze-failure)" + procedure[1]: + - "nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo clippy {scope} --all-targets {features} -- -D warnings" + tools: + shell[1]: + - cargo + errors: + lint_violations: + cause: "clippy emitted denied warnings" + recovery: "Address the diagnostics; do not blanket-allow without justification" + + fmt-check: + description: "Canonical formatting check; matches CI exactly. Does not compile, so does not need build-jobs caps" + inputs[1]: + - scope: "'--all' for the full workspace (default and CI parity), or omit for the local crate" + output[2]: + - fmt_status: "{ passed: boolean } — true when no formatting diffs" + - fmt_diff_summary: "Concise summary of files needing formatting (when not passed)" + procedure[1]: + - "nice -n 19 cargo fmt {scope} -- --check" + tools: + shell[1]: + - cargo + errors: + formatting_diffs: + cause: "Source files do not match rustfmt configuration" + recovery: "Run cargo-operations::fmt-fix to apply formatting, then commit the result" + + fmt-fix: + description: "Apply rustfmt formatting in place" + inputs[1]: + - scope: "'--all' for the full workspace, or omit for the local crate" + procedure[1]: + - "nice -n 19 cargo fmt {scope}" + tools: + shell[1]: + - cargo + + doc: + description: "Generate API documentation to verify inline doc comments compile" + inputs[1]: + - scope: "'--workspace --no-deps' for the full workspace, or '-p <crate> --no-deps' to scope" + procedure[1]: + - "nice -n 19 SKIP_WASM_BUILD=1 CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4} cargo doc {scope}" + tools: + shell[1]: + - cargo + errors: + broken_doc_link: + cause: "rustdoc detected a broken intra-doc link" + recovery: "Fix the link target or remove the broken reference" + + preflight: + description: "Probe required toolchain prerequisites before running any workspace cargo command. Surfaces missing system dependencies (protoc, openssl headers, pkg-config, ...) as a structured environment finding so the validate activity fails fast rather than mid-workspace-compile." + output[1]: + - missing_prerequisites: "Array of {name, install_hint} for any unmet prerequisite. Empty array when all prerequisites are present." + procedure[3]: + - "Inspect target_path for build-script signals indicating system-dependency requirements. Common: protoc (libp2p / litep2p crates), libssl-dev / openssl headers (openssl-sys), pkg-config. Walk Cargo.toml and any build.rs files for these crates." + - "For each candidate, probe via 'which <name>' and (where applicable) 'pkg-config --exists <name>'. Collect any unresolved entries with a one-line install_hint (e.g., 'apt-get install -y protobuf-compiler' for protoc)." + - "Return missing_prerequisites. Do NOT attempt installation — environment changes always require user consent." + tools: + shell[2]: + - which + - pkg-config + errors: + missing_prerequisite: + cause: "A required toolchain component is not installed" + recovery: "Surface missing_prerequisites to the user as an environment finding via the activity's validate action; do not auto-install" + + run-suite: + description: "Run check, clippy, test, and fmt-check concurrently against the same scope and aggregate their statuses into a single validation_results envelope. Replaces the four serial validate-class operations and is the canonical entry point for the validate activity on rust-substrate projects." + inputs[2]: + - scope: "'--workspace' for full validation parity with CI; '-p <crate>' to scope to one crate (faster but does not match CI)" + - features: "Optional --features flags (empty string when none)" + output[1]: + - validation_results: "{ check_status, clippy_status, test_status, fmt_status, validation_passed } — validation_passed is true iff all four sub-statuses passed" + procedure[3]: + - "Fan out four concurrent shells invoking cargo-operations::check, ::clippy, ::test, and ::fmt-check against the same {scope}. Each carries its own resource budget (nice -n 19 + CARGO_BUILD_JOBS cap), so suite peak memory is bounded by the per-op cap, NOT by 4× a single op (fmt-check uses no compile budget at all)." + - "Wait for ALL four to finish before composing results. Do NOT short-circuit on the first failure — collect every per-op status and diagnostics so a single pass surfaces every issue rather than forcing serial discovery." + - "Compose validation_results = { check_status, clippy_status, test_status, fmt_status, validation_passed: check_status.passed AND clippy_status.passed AND test_status.passed AND fmt_status.passed }." + tools: + shell[1]: + - cargo + errors: + out_of_memory: + cause: "Combined peak of concurrent cargo invocations exceeded available RAM despite per-op budgets" + recovery: "Halve CARGO_BUILD_JOBS for all (export CARGO_BUILD_JOBS=2) and retry. On very tight hosts, fall back to running check/clippy/test sequentially via the per-op operations." + +rules: + resource-budget: "Every cargo invocation made by work-package skills MUST use one of these operations. Do NOT call bare `cargo ...` from skill protocols. The inline budget — nice -n 19, CARGO_BUILD_JOBS=${CARGO_BUILD_JOBS:-4}, RUST_TEST_THREADS=${RUST_TEST_THREADS:-4}, SKIP_WASM_BUILD=1 (non-release only) — is what prevents host hang on ≤32 GiB hosts. Override caps via env on larger hosts." + + foreground-only: "Cargo operations MUST run synchronously in the foreground of the caller. Never invoke them with run_in_background inside an activity worker — when the worker exits, the OS process group is killed and the build is lost (this is what forced the worker re-spawn pattern observed in past runs). If the activity's wall-clock budget cannot accommodate a foreground run, the orchestrator (not the worker) owns the invocation; spawn a new worker only AFTER the cargo result is in hand." + + scope-narrow-then-wide: "During inner loops (TDD red/green in implement-task) prefer scope='-p <crate>'. Run --workspace once at the validate activity to match CI." + + release-builds-keep-wasm: "build-release is the ONLY operation that produces the runtime wasm artifact and is therefore the ONLY operation that omits SKIP_WASM_BUILD=1. Do not 'optimise' build-release by adding it." + + prefer-nextest: "When cargo nextest is configured for the project (.config/nextest.toml present), the test operation MUST use nextest — it isolates failures into separate processes, giving lower peak RAM and clearer reporting." + + fmt-uses-only-nice: "fmt-check and fmt-fix do not compile, so only nice -n 19 applies; do not paste the full env budget there — it is misleading." diff --git a/work-package/skills/README.md b/work-package/skills/README.md index 82c85a02..d340a4f6 100644 --- a/work-package/skills/README.md +++ b/work-package/skills/README.md @@ -2,9 +2,9 @@ > Part of the [Work Package Implementation Workflow](../README.md) -## Skills (24 workflow-specific + 6 cross-workflow) +## Skills (25 workflow-specific + 6 cross-workflow) -The workflow uses 24 workflow-specific skills organized by capability, plus 6 cross-workflow skill references. Universal meta skills are auto-included on the first `get_skills` call. Skills are referenced by activities through `primary` and `supporting` roles. +The workflow uses 25 workflow-specific skills organized by capability, plus 6 cross-workflow skill references. Universal meta skills are auto-included on the first `get_skills` call. Skills are referenced by activities through `primary` and `supporting` roles. | # | Skill ID | Capability | Used By | |---|----------|------------|---------| @@ -24,7 +24,7 @@ The workflow uses 24 workflow-specific skills organized by capability, plus 6 cr | 13 | `review-assumptions` | Assumption collection, classification, and structured review | All planning and implementation activities | | 14 | `manage-artifacts` | Planning folder creation and artifact numbering management | Start Work Package, Requirements Elicitation, Implementation Analysis | | 15 | `manage-git` | Git branching, PR lifecycle, branch sync, GPG re-sign | Start Work Package, Implement, Validate, Strategic Review | -| 16 | `validate-build` | Test execution, build verification, lint checking | Validate, Implement | +| 16 | `validate-build` | Failure-analysis, fix-application, and result-aggregation operations (cargo execution lives in `cargo-operations`) | Validate, Implement | | 17 | `finalize-documentation` | ADR updates, test plan finalization, COMPLETE.md creation | Complete | | 18 | `update-pr` | PR description update, push commits, mark ready for review | Submit for Review | | 19 | `conduct-retrospective` | Workflow retrospective and lessons learned capture | Complete | @@ -32,6 +32,7 @@ The workflow uses 24 workflow-specific skills organized by capability, plus 6 cr | 21 | `create-adr` | Architecture Decision Record creation for significant decisions | Complete | | 22 | `build-comprehension` | Codebase comprehension via hierarchical analysis and persistent knowledge artifacts | Codebase Comprehension | | 23 | `reconcile-assumptions` | Iterative assumption reconciliation through targeted code analysis | Design Philosophy, Requirements Elicitation, Research, Implementation Analysis, Plan & Prepare, Implement | +| 24 | `cargo-operations` | Resource-constrained cargo subcommand operations (check, test, build, clippy, fmt, doc) with inline budget to prevent host hang | Implement, Validate, Complete | > Skills `meta-orchestrator`, `workflow-orchestrator`, and `activity-worker` are **universal skills** in [meta/skills/](../../meta/skills/). They provide the core orchestration and execution protocols used across all workflows. diff --git a/work-package/skills/classify-problem.toon b/work-package/skills/classify-problem.toon new file mode 100644 index 00000000..4916cedd --- /dev/null +++ b/work-package/skills/classify-problem.toon @@ -0,0 +1,76 @@ +id: classify-problem +version: 1.0.0 +capability: Problem classification, complexity assessment, and workflow path determination + +description: "Protocol for identifying and classifying a problem as specific (cause known or unknown) or inventive (improvement or prevention), assessing complexity (simple, moderate, complex), and determining which workflow activities are needed based on the classification." + +operations: + define-problem: + description: "Create a clear problem statement with system understanding, impact assessment, success criteria, and constraints" + inputs[1]: + - user_request: "User's free-form request or ticket description" + output[4]: + - problem_statement: "Clear one-sentence problem definition" + - impact_assessment: "Description of what is affected and why it matters" + - success_criteria: "Measurable criteria for a successful resolution" + - constraints: "Known limitations and boundaries" + procedure[3]: + - "Extract the core problem from the user request, ticket, or issue — strip framing and focus on what needs to change" + - "Assess impact: which components, users, or behaviors are affected" + - "Define success criteria: what does 'done' look like" + rules: + no-embedding: "NEVER embed constraints or scope decisions into the problem statement. The problem statement describes WHAT, not HOW." + + classify-type: + description: "Determine if this is a specific problem or an inventive goal" + inputs[2]: + - problem_statement: "Output from define-problem" + - codebase_context: "Current understanding of the target codebase area" + output[2]: + - problem_type: "One of: specific-cause-known, specific-cause-unknown, inventive-improvement, inventive-prevention" + - rationale: "Explanation for the classification" + procedure[2]: + - "If the problem has a clear location and expected behavior, classify as specific (cause-known if the root cause is evident, cause-unknown if investigation is needed)" + - "If the problem is about making something better or preventing future issues without a concrete failing, classify as inventive" + tools: + harness[2]: + - Read + - Grep + + assess-complexity: + description: "Evaluate the complexity of the problem to determine workflow path" + inputs[2]: + - problem_type: "Classification from classify-type" + - codebase_context: "Understanding of the codebase, affected components, and dependencies" + output[2]: + - complexity: "One of: simple, moderate, complex" + - rationale: "Explanation for the complexity rating" + procedure[4]: + - "Simple: well-defined scope, single component, clear fix — e.g. a typo, a missing null check, a config update" + - "Moderate: multiple components or some uncertainty — may need research but requirements are clear" + - "Complex: cross-cutting concern, unclear requirements, significant architectural change, or risk of regression" + - "If the classification is inventive-improvement or inventive-prevention with broad scope, default to complex" + rules: + err-on-the-side-of-complexity: "When uncertain, rate complexity one level higher. It is better to perform unnecessary research than to miss a critical dependency." + + determine-path: + description: "Map complexity to required workflow activities" + inputs[2]: + - complexity: "simple, moderate, or complex" + - ticket_context: "Whether a ticket exists and how complete it is" + output[4]: + - needs_elicitation: "Whether requirements elicitation is needed" + - needs_research: "Whether research is needed" + - needs_comprehension: "Whether codebase comprehension is needed" + - skip_optional_activities: "Whether to skip optional discovery activities" + procedure[3]: + - "Simple: skip optional (elicitation=false, research=false, comprehension may be needed for unfamiliar code)" + - "Moderate: research only (elicitation=false, research=true)" + - "Complex: full workflow (elicitation=true, research=true, comprehension=true)" + rules: + comprehension-always-when-unknown: "If the target area is unfamiliar or the problem type is specific-cause-unknown, set needs_comprehension=true regardless of complexity." + review-mode-override: "In review mode, force needs_elicitation=false and path to review-appropriate activities." + +rules: + classification-informs-everything: "The problem type and complexity classification drive all subsequent activity decisions. Revisit the classification if new information emerges during the workflow." + ticket-completeness-check: "When a ticket exists, assess its completeness (problem statement, goal, scope, acceptance criteria, user stories). Document gaps in assumptions-log.md." diff --git a/work-package/skills/reconcile-assumptions.toon b/work-package/skills/reconcile-assumptions.toon new file mode 100644 index 00000000..142f372a --- /dev/null +++ b/work-package/skills/reconcile-assumptions.toon @@ -0,0 +1,56 @@ +id: reconcile-assumptions +version: 1.0.0 +capability: Iterative assumption classification and codebase-driven resolution with convergence tracking + +description: "Protocol for classifying assumptions by resolvability and iteratively resolving code-analyzable assumptions through targeted codebase analysis. Runs as a while loop until no code-resolvable assumptions remain (convergence). Each iteration classifies resolvability, performs targeted analysis, updates logs, and reclassifies." + +operations: + classify-resolvability: + description: "Classify each open assumption as code-analyzable or stakeholder-dependent" + inputs[2]: + - assumptions: "Array of open assumptions from assumptions-log.md" + - codebase_context: "Current understanding of the codebase structure and target paths" + output[1]: + - classification: "Map of assumption -> { resolvable: boolean, strategy: string }" + procedure[2]: + - "For each assumption, evaluate whether the codebase can answer it definitively" + - "Mark as resolvable when the answer exists in source code, tests, configs, or docs; mark as stakeholder-dependent when it requires domain knowledge, business decisions, or user input" + rules: + no-speculation: "NEVER mark an assumption as resolved without code evidence. If uncertain, classify as stakeholder-dependent." + strategy-required: "Every resolvable assumption must have a strategy describing WHERE in the codebase to look." + + resolve-iteration: + description: "Execute one resolution pass: pick the highest-confidence resolvable assumption and investigate" + inputs[2]: + - classification: "Output from classify-resolvability" + - codebase_context: "Current understanding of the codebase" + output[2]: + - findings: "Resolved assumption text and evidence" + - updated_assumptions: "Assumptions log with resolved items marked" + procedure[4]: + - "Pick the resolvable assumption with the clearest investigation strategy" + - "Perform targeted codebase analysis using the strategy (read source, grep patterns, trace calls, check tests)" + - "Record findings: the resolved answer and the evidence trail (files read, patterns matched)" + - "Update assumptions-log.md: mark the assumption resolved with its finding" + tools: + harness[3]: + - Read + - Grep + - Glob + rules: + evidence-trail: "Every resolution MUST cite the file path and line(s) that provided the answer." + one-at-a-time: "Resolve one assumption per iteration. Do not batch." + + check-convergence: + description: "Evaluate whether any code-resolvable assumptions remain" + inputs[1]: + - assumptions: "Current assumptions log" + output[1]: + - converged: "true when no code-resolvable assumptions remain" + procedure[1]: + - "Re-classify all open assumptions; return converged=true only when every remaining assumption is stakeholder-dependent" + +rules: + convergence-before-continue: "Do NOT proceed past the assumption reconciliation loop until check-convergence returns true. Lingering resolvable assumptions indicate incomplete analysis." + log-fidelity: "Every assumption in assumptions-log.md must have a status: open, resolved, or stakeholder-dependent. Never leave assumptions unclassified." + reclassify-after-resolve: "After resolving an assumption, re-run classify-resolvability — a resolution may unlock or change the resolvability of other assumptions." diff --git a/work-package/workflow.toon b/work-package/workflow.toon index 4c362b62..10cf5ee5 100644 --- a/work-package/workflow.toon +++ b/work-package/workflow.toon @@ -18,7 +18,6 @@ rules[5]: - "Explicit approval - Get clear 'yes' or 'proceed' before major actions (within activity checkpoints only — NOT between activities)" - "Decision points require user choice - When issues are found, user decides whether to proceed or loop back" skills: - primary: meta/workflow-orchestrator artifactLocations: planning: path: "{planning_folder_path}" diff --git a/work-packages/activities/01-scope-assessment.toon b/work-packages/activities/01-scope-assessment.toon index 4ad5e6de..75b70a01 100644 --- a/work-packages/activities/01-scope-assessment.toon +++ b/work-packages/activities/01-scope-assessment.toon @@ -9,7 +9,6 @@ recognition[4]: - Multi-package initiative - Related work items needing coordination skills: - primary: meta/activity-worker supporting[1]: - assess-initiative-scope entryActions[1]: diff --git a/work-packages/activities/02-folder-setup.toon b/work-packages/activities/02-folder-setup.toon index 87231fbb..5ccfb031 100644 --- a/work-packages/activities/02-folder-setup.toon +++ b/work-packages/activities/02-folder-setup.toon @@ -4,7 +4,6 @@ name: Planning Folder Setup description: Create planning folder structure with initial documentation skeletons problem: Need organized folder structure for multi-package planning artifacts skills: - primary: meta/activity-worker supporting[1]: - workflow-execution steps[4]: diff --git a/work-packages/activities/03-analysis.toon b/work-packages/activities/03-analysis.toon index 152e20bb..752e9ea6 100644 --- a/work-packages/activities/03-analysis.toon +++ b/work-packages/activities/03-analysis.toon @@ -4,7 +4,6 @@ name: Analysis description: Perform completion or context analysis depending on whether continuing previous work or starting new initiative problem: Need to understand context before detailed work package planning skills: - primary: meta/activity-worker supporting[1]: - analyze-initiative-context steps[3]: diff --git a/work-packages/activities/04-package-planning.toon b/work-packages/activities/04-package-planning.toon index 1246629d..fe14adb7 100644 --- a/work-packages/activities/04-package-planning.toon +++ b/work-packages/activities/04-package-planning.toon @@ -4,7 +4,6 @@ name: Work Package Planning description: Define scope, dependencies, effort, and success criteria for each work package problem: Each work package needs detailed planning before prioritization skills: - primary: meta/activity-worker supporting[1]: - plan-work-package-scope steps[1]: diff --git a/work-packages/activities/05-prioritization.toon b/work-packages/activities/05-prioritization.toon index a2d232fb..0e5a09f8 100644 --- a/work-packages/activities/05-prioritization.toon +++ b/work-packages/activities/05-prioritization.toon @@ -4,7 +4,6 @@ name: Prioritization description: Prioritize work packages based on dependencies, value, risk, and effort problem: Need to determine execution order for work packages skills: - primary: meta/activity-worker supporting[1]: - prioritize-packages steps[4]: diff --git a/work-packages/activities/06-finalize-roadmap.toon b/work-packages/activities/06-finalize-roadmap.toon index c6f31c9e..1ca2464f 100644 --- a/work-packages/activities/06-finalize-roadmap.toon +++ b/work-packages/activities/06-finalize-roadmap.toon @@ -4,7 +4,6 @@ name: Finalize Roadmap description: Complete roadmap documentation with timeline, navigation, and success criteria problem: Need to finalize planning documentation before implementation begins skills: - primary: meta/activity-worker supporting[1]: - document-roadmap steps[5]: diff --git a/work-packages/activities/07-implementation.toon b/work-packages/activities/07-implementation.toon index 83440a59..15b2fa9a 100644 --- a/work-packages/activities/07-implementation.toon +++ b/work-packages/activities/07-implementation.toon @@ -4,7 +4,6 @@ name: Implementation description: Execute each planned work package in priority order by triggering the work-package workflow problem: Planned work packages need to be implemented one at a time according to the roadmap skills: - primary: meta/activity-worker supporting[1]: - orchestrate-package-execution triggers[1]: diff --git a/work-packages/workflow.toon b/work-packages/workflow.toon index 07ead38a..a1531937 100644 --- a/work-packages/workflow.toon +++ b/work-packages/workflow.toon @@ -16,7 +16,6 @@ rules[5]: - User controls priorities - Never assume priority order without confirmation - "Explicit approval - Get clear 'yes' or 'proceed' before creating documents" skills: - primary: meta/workflow-orchestrator artifactLocations: planning: path: "{planning_folder_path}" diff --git a/workflow-design/activities/01-intake.toon b/workflow-design/activities/01-intake.toon index b90f3dd1..67095046 100644 --- a/workflow-design/activities/01-intake.toon +++ b/workflow-design/activities/01-intake.toon @@ -11,7 +11,6 @@ recognition[6]: - update workflow - modify workflow skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/02-context-and-literacy.toon b/workflow-design/activities/02-context-and-literacy.toon index 66274121..0da7b640 100644 --- a/workflow-design/activities/02-context-and-literacy.toon +++ b/workflow-design/activities/02-context-and-literacy.toon @@ -4,7 +4,6 @@ name: Context and Literacy description: "Load the schema system, read existing workflows to understand conventions, and verify TOON format comprehension. This activity gates all subsequent content production." problem: Agent must internalize the schema system and format conventions before producing any workflow content skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/03-requirements-refinement.toon b/workflow-design/activities/03-requirements-refinement.toon index d8eb9456..04116389 100644 --- a/workflow-design/activities/03-requirements-refinement.toon +++ b/workflow-design/activities/03-requirements-refinement.toon @@ -4,7 +4,6 @@ name: Requirements Refinement description: "Systematically elicit workflow design details from the user, one question at a time. Each design dimension has its own checkpoint to ensure atomic, sequential elicitation." problem: The user's free-form description needs to be refined into a complete workflow specification skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/04-pattern-analysis.toon b/workflow-design/activities/04-pattern-analysis.toon index a4d9dbb8..ac87e29e 100644 --- a/workflow-design/activities/04-pattern-analysis.toon +++ b/workflow-design/activities/04-pattern-analysis.toon @@ -4,7 +4,6 @@ name: Pattern Analysis description: "Audit existing workflows of similar type to extract reusable structural patterns. Present extracted patterns alongside the proposed structure for the new workflow." problem: New workflows must follow established conventions and reuse proven structural patterns skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: false diff --git a/workflow-design/activities/05-impact-analysis.toon b/workflow-design/activities/05-impact-analysis.toon index 89e6130f..c6a64f61 100644 --- a/workflow-design/activities/05-impact-analysis.toon +++ b/workflow-design/activities/05-impact-analysis.toon @@ -4,7 +4,6 @@ name: Impact Analysis description: "For update mode: enumerate all files in the existing workflow, identify which are affected by the change, check for side-effects, and flag content that will be removed." problem: Modifying an existing workflow can break transition chains, invalidate checkpoint assumptions, or orphan skills and resources skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: false diff --git a/workflow-design/activities/06-scope-and-structure.toon b/workflow-design/activities/06-scope-and-structure.toon index 5f39be20..648c736b 100644 --- a/workflow-design/activities/06-scope-and-structure.toon +++ b/workflow-design/activities/06-scope-and-structure.toon @@ -4,7 +4,6 @@ name: Scope and Structure description: "Define the complete file manifest and structural design for the workflow. Enumerates every file to be created, modified, or removed, and proposes the folder structure, activity decomposition, and file layout." problem: Incomplete scope coverage is the most frequent misalignment pattern — every affected file must be enumerated before execution begins skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/07-content-drafting.toon b/workflow-design/activities/07-content-drafting.toon index 63c2eb54..73a6ee7a 100644 --- a/workflow-design/activities/07-content-drafting.toon +++ b/workflow-design/activities/07-content-drafting.toon @@ -4,7 +4,6 @@ name: Content Drafting description: "Draft or modify each file in the scope manifest. Each file gets an approach checkpoint before drafting and a review checkpoint after. All TOON files are validated against the schema immediately after drafting." problem: Content must be drafted using formal schema constructs, validated per-file, and reviewed before proceeding skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/08-quality-review.toon b/workflow-design/activities/08-quality-review.toon index b508c4ae..3ef9141f 100644 --- a/workflow-design/activities/08-quality-review.toon +++ b/workflow-design/activities/08-quality-review.toon @@ -4,7 +4,6 @@ name: Quality Review description: "Create/update mode: four review passes over drafted content — schema expressiveness, convention conformance, rule hygiene (restatements, contradictions, cross-level duplications, prefix patterns), and rule-to-structure — each with a checkpoint. Review mode: six audit areas on the existing workflow (principles, anti-patterns, schema validation, tool-skill-doc consistency, compliance report, disposition) per resources/04-review-mode-guide.md." problem: Drafted content may contain prose that should be formal constructs, diverge from conventions, or have critical rules without structural enforcement skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/09-validate-and-commit.toon b/workflow-design/activities/09-validate-and-commit.toon index 22b3e898..f7049808 100644 --- a/workflow-design/activities/09-validate-and-commit.toon +++ b/workflow-design/activities/09-validate-and-commit.toon @@ -4,7 +4,6 @@ name: Validate and Commit description: "Run schema validation on all TOON files, re-verify the scope manifest, generate README if creating a new workflow, and commit all changes to the workflows worktree." problem: All workflow content must pass validation and the complete scope must be verified before committing skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/activities/10-post-update-review.toon b/workflow-design/activities/10-post-update-review.toon index 9db1d7a8..6a968c38 100644 --- a/workflow-design/activities/10-post-update-review.toon +++ b/workflow-design/activities/10-post-update-review.toon @@ -4,7 +4,6 @@ name: Post-Update Review description: "Automatically runs after an update commit. Reloads the updated workflow from the workflow-server and runs the 5 audit passes (principle compliance, anti-pattern scan, schema validation, expressiveness, conformance, rule enforcement) to verify the update did not introduce new compliance issues." problem: Updates can introduce new compliance issues that are invisible without a post-commit audit against the full design principles and anti-pattern catalog skills: - primary: meta/activity-worker supporting[1]: - workflow-design required: true diff --git a/workflow-design/workflow.toon b/workflow-design/workflow.toon index 763de4d5..415a45a4 100644 --- a/workflow-design/workflow.toon +++ b/workflow-design/workflow.toon @@ -28,7 +28,6 @@ rules[14]: - "Non-destructive updates — compare new content against existing content and flag any material being removed" - "Every workflow must include a README.md at the root and in each subfolder (activities/, skills/, resources/). Root README documents the workflow overview, modes, activity sequence, variables, and file structure. Subfolder READMEs document the contents of that folder with tables and protocol details. Follow the style established by the prism workflow." skills: - primary: meta/workflow-orchestrator artifactLocations: planning: path: "{planning_folder_path}"