feat: operation-focused skills + ops bundling on get_workflow / get_activity

.cursor/rules/workflow-server.mdc

@@ -5,4 +5,4 @@ alwaysApply: true
 
 # Workflow Server Integration
 
-For any start workflow or create or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure.
+For any start workflow or create or resume work package request, call the `discover` tool on the workflow-server MCP server to learn the bootstrap procedure. Complete the procedure before any other action.

docs/architecture.md

@@ -16,8 +16,8 @@ The orchestration engine strictly enforces deterministic state transitions. Rath
 ## 4. [Artifact & Workspace Isolation](artifact_management_model.md)
 The system enforces strict boundaries between orchestration metadata (the workflow engine, plans, and state) and the user's domain codebase. This document outlines the purpose of the `.engineering` directory, the mandatory updates to the planning folder's `README.md`, the `artifactPrefix` naming conventions, the `ArtifactSchema` with `create`/`update` actions, and the specific Git submodule procedures agents must follow when committing orchestration artifacts.
 
-## 5. [Skill & Resource Resolution Architecture](resource_resolution_model.md)
-To preserve the precious context windows of Large Language Models, the system uses a lazy-loading resource architecture. Instead of injecting massive prompts, the server utilizes Canonical IDs and a Universal Skill Fallback mechanism. This document explains how `.toon` skill files declare lightweight `resources` arrays, prompting agents to call the `get_resource` tool only when they need to read large, specialized markdown guides (like Git or Atlassian API tutorials). It also covers the workflow-level primary skill loaded via `get_skills`.
+## 5. [Skill, Operation & Resource Resolution Architecture](resource_resolution_model.md)
+To preserve the precious context windows of Large Language Models, the system pairs a lazy-loading resource architecture with an operation-focused skill model. Skills are containers for named **operations**, **rules**, and **errors**; activities and workflows compose behaviour by listing flat `skill-id::operation-name` references. The server pre-resolves these refs (alongside core orchestrator and worker op sets) and bundles them into the responses of `get_workflow` and `get_activity`. Lightweight `resources` arrays — at the skill or per-operation level — defer loading of large markdown guides (Git CLI tutorials, API references, templates) until an agent calls `get_resource`. This document explains the resolution pipeline, the universal `meta/` skill fallback, the operation bundles, and the canonical ID convention.
 
 ## 6. [Workflow Fidelity](workflow-fidelity.md)
 Because agents are autonomous, they must be audited to ensure they actually followed the instructions defined in the workflow's TOON files. This document details the Step Completion Manifest (a structured summary of what the agent did), the Activity Manifest (tracking the workflow journey), and the cryptographic Trace Tokens. It explains how mechanical and semantic traces are recorded, validated against the workflow schema, and appended to the permanent audit log.

docs/development.md

@@ -62,15 +62,17 @@ workflow-server/
 │   ├── loaders/              # File loaders (filesystem → validated objects)
 │   │   ├── workflow-loader.ts
 │   │   ├── activity-loader.ts
-│   │   ├── skill-loader.ts
+│   │   ├── skill-loader.ts   # Includes resolveOperations (skill::element ref resolver)
 │   │   ├── resource-loader.ts
-│   │   ├── rules-loader.ts
+│   │   ├── core-ops.ts       # CORE_ORCHESTRATOR_OPS / CORE_WORKER_OPS (op refs bundled into get_workflow / get_activity)
 │   │   ├── schema-loader.ts
 │   │   ├── schema-preamble.ts
-│   │   └── filename-utils.ts
+│   │   ├── filename-utils.ts
+│   │   └── index.ts          # Barrel exports
 │   ├── tools/                # MCP tool implementations
 │   │   ├── workflow-tools.ts # discover, list_workflows, get_workflow, next_activity, get_activity, yield_checkpoint, resume_checkpoint, present_checkpoint, respond_checkpoint, get_trace, health_check, get_workflow_status
-│   │   └── resource-tools.ts # start_session, get_skills, get_skill, get_resource
+│   │   ├── resource-tools.ts # start_session, get_skills, get_skill, get_resource, resolve_operations
+│   │   └── index.ts          # Tool registration entry point
 │   ├── resources/            # MCP resource registration
 │   │   └── schema-resources.ts # workflow-server://schemas
 │   └── utils/                # Utility functions
@@ -130,18 +132,20 @@ npm test -- --run --coverage
 
 ### Test Suites
 
-| Test Suite | Tests | Coverage |
-|------------|-------|----------|
-| `workflow-loader.test.ts` | 17 | Workflow loading, transitions, validation |
-| `schema-validation.test.ts` | 23 | All Zod schemas |
-| `mcp-server.test.ts` | 62 | All MCP tools, trace lifecycle, activity manifest |
-| `activity-loader.test.ts` | 10 | Activity loading and dynamic index |
-| `skill-loader.test.ts` | 13 | Skill loading and dynamic index |
-| `session.test.ts` | 22 | Token create/decode/advance, sid, aid, parent context |
-| `trace.test.ts` | 20 | TraceStore, trace token encode/decode |
-| `validation.test.ts` | 15 | Transition, manifest, condition validation |
-| `dispatch.test.ts` | 8 | Workflow dispatch, status, parent-child trace correlation |
-| **Total** | **190+** | All passing |
+| Test Suite | Coverage |
+|------------|----------|
+| `workflow-loader.test.ts` | Workflow loading, transitions, validation |
+| `schema-validation.test.ts` | All Zod schemas |
+| `schema-loader.test.ts` | JSON Schema loading and serving |
+| `mcp-server.test.ts` | All MCP tools, trace lifecycle, activity manifest, operation bundles |
+| `activity-loader.test.ts` | Activity loading and dynamic index |
+| `skill-loader.test.ts` | Skill loading, dynamic index, `resolveOperations` |
+| `session.test.ts` | Token create/decode/advance, sid, aid, parent context |
+| `trace.test.ts` | TraceStore, trace token encode/decode |
+| `validation.test.ts` | Transition, manifest, condition validation |
+| `dispatch.test.ts` | Workflow dispatch, status, parent-child trace correlation |
+
+Run `npm test -- --run` for the live count and pass/fail summary.
 
 ### Test Infrastructure
 

docs/orchestra-specification.md

@@ -20,9 +20,9 @@ Orchestra defines the grammar and semantic constraints for the four workflow pri
 
 | Primitive | Description | Orchestra Status |
 |-----------|-------------|----------------|
-| **Workflow** | Top-level container: metadata, variables, activity sequencing | Legacy — Orchestra variant TBD |
-| **Activity** | Execution unit: steps, decisions, loops composed into flows | **Defined in this specification** |
-| **Skill** | Agent capability: inputs, outputs, rules, protocol, tools | Legacy — Orchestra variant TBD |
+| **Workflow** | Top-level container: metadata, variables, activity sequencing, orchestrator `operations:` refs | Legacy — Orchestra variant TBD |
+| **Activity** | Execution unit: steps, decisions, loops composed into flows; declares worker `operations:` refs | **Defined in this specification** |
+| **Skill** | Container for named `operations`, `rules`, and `errors` | Legacy — Orchestra variant TBD |
 | **Resource** | Reference material: documentation, templates, guides | Legacy — Orchestra variant TBD |
 
 This specification fully defines the Orchestra grammar and constraints for **activities**. The workflow, skill, and resource primitives continue to use the prior schema definitions (see `schemas/*.schema.json`) until their Orchestra variants are designed.
@@ -47,11 +47,11 @@ The activity is the primary execution unit. It defines steps, decisions, and loo
 
 #### 3.1.1 Steps
 
-A step is a unit of work. Trivial steps are performed directly by the agent. Non-trivial steps declare a `skill:` reference — just the skill ID, nothing more.
+A step is a unit of work. Trivial steps are performed directly by the agent. Non-trivial steps invoke a named operation — either by listing the activity-level `operations:` array (a flat list of `skill-id::operation-name` refs) and writing a plain step description, or by inlining the invocation in the step's description (`skill-id::operation-name(arg: {var}, ...)`). The legacy `skill:` reference (just the skill ID) is still accepted and is resolved through `get_skill(step_id)`, but new activities should prefer operation references.
 
-**Input/output resolution**: The skill's own definition declares its inputs and outputs by name. At runtime, the agent resolves each input name by pattern-matching against variables in the scoping chain (local flow > loop variable > activity-level > workflow-level). If a name is ambiguous across scopes, the skill's input definition uses a qualified reference (`NN.step-id.name`) to select explicitly. The step does not redeclare inputs or outputs — that would be redundant with the skill definition. Skill outputs are injected into the current scope after execution.
+**Input/output resolution**: An operation declares its inputs and outputs by name in the skill definition. At runtime, the agent resolves each input by pattern-matching against variables in the scoping chain (local flow > loop variable > activity-level > workflow-level). Inline invocations may supply arguments explicitly (`skill-id::operation-name(arg: {var}, ...)`), overriding scope resolution for those names. Outputs are injected into the current scope after execution.
 
-**Rules live in skills**: Steps do not carry rules. If a step requires behavioral constraints, that signals a skill is needed — the skill definition houses the rules. This keeps steps as pure references and rules co-located with the procedural knowledge that enforces them.
+**Rules live in skills**: Steps do not carry rules. If a step requires behavioural constraints, that signals an operation or rule is needed — both live in the skill definition and are pulled into the activity's bundled response when the activity references at least one element of the source skill (auto-included rules). This keeps steps as pure references and rules co-located with the procedural knowledge that enforces them.
 
 **Deterministic vs. dynamic questions**: Fixed-option questions with known branches are handled by interactive decisions (see Section 2.2). Dynamic questions — where the content, phrasing, or follow-up logic depends on runtime context — are steps backed by a skill. The skill declares its own context inputs (current domain, prior responses, etc.) and produces structured outputs (question text, user response, adaptation signals). These resolve from the environment automatically.
 
@@ -898,7 +898,13 @@ Machine-interpretable rules derived from the Alloy constraints. Each rule has an
 
 ## 4. Skill
 
-TBD — Orchestra grammar and constraints for the skill primitive (agent capability: inputs, outputs, rules, protocol, tools) are not yet defined. See `schemas/skill.schema.json` for the current legacy schema.
+TBD — Orchestra grammar and constraints for the skill primitive are not yet defined. See `schemas/skill.schema.json` for the current legacy schema. In that schema, a skill is a container for three element kinds:
+
+* **`operations`** — named procedures with `inputs`, `output`, `procedure`, `tools`, optional per-operation `resources`, `errors`, `rules`, and `prose`. Referenced from activities/workflows as `skill-id::operation-name`. The discrete `harness` field has been dropped — implementation hints fold into `procedure`, `prose`, and `tools` instead.
+* **`rules`** — named behavioural invariants (string or grouped string array). Referenced as `skill-id::rule-name` and auto-included when any element from the same skill is resolved.
+* **`errors`** — named error definitions with `cause`, `recovery`, `detection`, and `resolution`. Referenced as `skill-id::error-name`.
+
+See [Skill, Operation & Resource Resolution Architecture](resource_resolution_model.md) for resolution semantics.
 
 ---