feat: compose reusable workflow definitions

.agents/skills/forge-workflow-authoring/SKILL.md

@@ -10,17 +10,22 @@ Help the user express a Forge process as readable YAML. Treat canonical JSON as
 ## Start here
 
 1. Read [references/workflow-format.md](references/workflow-format.md).
-2. For a new workflow, copy [assets/workflow.yaml](assets/workflow.yaml). For a change, start from the active definition or the closest built-in workflow and convert it to YAML if needed.
+2. For a small local example, copy [assets/workflow.yaml](assets/workflow.yaml). For a publishable workflow, start from the closest full built-in definition and convert it to YAML if needed; publication requires the state profile's mandatory gates.
 3. Establish the intended stages, decisions, loops, human pauses, and external commands before editing fields.
 4. Run `forge workflow catalog STATE` and use only the nodes and routers it reports. Never invent catalog names.
-5. Keep the definition flow-only. Do not add node kinds, station contracts, effect capabilities, required or mandatory policies, extension declarations, observation policies, or external-entry flags. Forge derives and enforces those concerns from its trusted catalog and publication policy.
+   For reusable steps, inspect the built-in `github_pr_review` subworkflow or an active
+   project definition. Bind every `@exit/name` in `spec.includes` and keep node names unique.
+5. Keep the definition flow-only. Do not add step kinds, station contracts, effect capabilities, required or mandatory policies, extension declarations, observation policies, or external-entry flags. Forge derives and enforces those concerns from its trusted catalog and publication policy.
 6. Validate and render before presenting the result:
 
    ```bash
    forge workflow validate WORKFLOW.yaml
    forge workflow render WORKFLOW.yaml
    ```
 
+   Add `--project-key PROJECT` to these commands when the source includes active project
+   definitions. Built-in includes resolve locally. Render a subworkflow to inspect its exits.
+
 Explain the rendered process in plain language when the user is trying to understand an existing definition.
 
 ## Changing an existing workflow
@@ -43,11 +48,14 @@ Do not claim migration safety based only on successful validation.
 
 Before publication, verify:
 
-- all transitions and router outcomes resolve to existing steps or `__end__`;
+- workflow transitions resolve to existing steps or `__end__`; subworkflow exits use
+  `@exit/name` and every caller binds them;
 - expected human and CI pause points remain present;
 - cycles cross an approved pause boundary;
 - exceptional commands such as PR rebasing are absent from graph topology;
 - revision and resume mappings protect in-flight instances.
+- dependency references resolve to active definitions in the same Jira project or to built-ins,
+  and the expanded graph has no node-name collisions.
 
 Report review problems with the affected step and a concrete correction. Distinguish topology, execution-policy, and migration findings; catalog and governance concerns are Forge implementation findings, not fields to add to the workflow.
 

.agents/skills/forge-workflow-authoring/references/workflow-format.md

@@ -9,7 +9,14 @@ A definition has four important parts:
 - `spec.entry` names the first ordinary step.
 - `spec.steps` maps registered node names to their transitions.
 
-Start at `entry`. Follow `next` for a fixed transition. At a step with `route`, follow every target in `branches`. A branch key is a possible router result; its value is the next step. `__end__` stops the current invocation and is not itself a declared step.
+Reusable `Subworkflow` definitions use the same registered nodes and may end a transition
+at `@exit/name`. A caller binds each exit through `spec.includes`; it may also include a
+complete workflow with `returnTo` and `returnFrom` for selected normal completion edges. Use `source: builtin` or
+`source: project`. Project references resolve to active definitions in the caller's Jira
+project. Nodes remain canonical and cannot collide. New runs pin the fully expanded graph;
+active runs keep their existing pin.
+
+Start at `entry`. Follow `next` for a fixed transition. At a step with `route`, follow every target in `branches`. A branch key is a possible router result; its value is the next step. `__end__` stops the current invocation and is not itself a declared step. In an included full workflow, `returnFrom` lists the terminal edges that return to the caller's `returnTo` target. Write `step_name` for a fixed `next: __end__` edge or `step_name:outcome` for a routed branch targeting `__end__`. Unlisted terminal edges keep their pause or stop behavior.
 
 Use `forge workflow render FILE` instead of tracing a large definition manually.
 
@@ -42,7 +49,7 @@ Dynamic fan-out uses `dynamicRoute: true` and an explicit `maxConcurrency`. Forg
 
 The workflow owns topology and flow-level execution choices. `retryBound`, `maxConcurrency`, and join behavior remain valid because they change how the graph advances.
 
-Do not author `kind`, `stationContract`, `stationContractVersion`, `requiredPolicies`, `allowedEffects`, `externalEntry`, `observationPolicy`, `mandatoryPolicies`, or `extensionPoints`. Forge derives node identity, authority, reconciliation, and mandatory governance from the selected state profile. Exceptional commands such as PR rebasing execute through the command-operation boundary and do not appear as workflow steps. Older pinned definitions containing catalog metadata remain readable for compatibility.
+Do not author step `kind`, `stationContract`, `stationContractVersion`, `requiredPolicies`, `allowedEffects`, `externalEntry`, `observationPolicy`, `mandatoryPolicies`, or `extensionPoints`. The top-level `kind` is `Workflow` or `Subworkflow`. Forge derives node identity, authority, reconciliation, and mandatory governance from the selected state profile. Exceptional commands such as PR rebasing execute through the command-operation boundary and do not appear as workflow steps. Older pinned definitions containing catalog metadata remain readable for compatibility.
 
 Run `forge workflow catalog STATE` when you need to inspect the derived node metadata; do not copy that metadata into the workflow.
 
@@ -72,4 +79,10 @@ forge workflow diff previous.yaml workflow.yaml
 forge workflow simulate-migration previous.yaml workflow.yaml instances.json
 ```
 
-`validate --json` emits canonical storage JSON. `render --format json` emits a compact process manifest. These outputs serve different purposes.
+Use `--project-key PROJECT` when a source file includes an active project definition. For a
+historical diff or migration check, use the exact expanded artifacts pinned by the instances;
+resolving old source files against today's active dependencies can change the graph being compared.
+
+For a workflow, `validate --json` emits the resolved canonical runtime JSON and
+`render --format json` emits a process manifest. For a subworkflow, render JSON emits the
+resolved subworkflow definition with its exit targets.

README.md

@@ -231,7 +231,7 @@ See [Getting Started](https://Forge-sdlc.github.io/forge/getting-started/) for t
 - [Architecture](https://Forge-sdlc.github.io/forge/architecture/): Versioned workflows,
   reconciliation, typed stations, durable effects, and execution inspection.
 - [Declarative Workflows](https://Forge-sdlc.github.io/forge/reference/declarative-workflows/):
-  Author and govern constrained project workflow definitions.
+  Author, reuse, and govern constrained project workflow definitions.
 - [Skills System](https://Forge-sdlc.github.io/forge/skills/): Customize Forge for your team and stack.
 - [Developer Guide](https://Forge-sdlc.github.io/forge/developer-guide/): Local testing, debugging, Prometheus metrics, Langfuse tracing, and Grafana dashboards.
 

docs/architecture/control-plane.md

@@ -49,9 +49,11 @@ are then checked against the active definition's transition policy.
 ### Pinned declarative definitions
 
 Definitions provide the workflow topology: entry, nodes, edges, routed
-branches, joins, and flow execution settings. Each workflow instance pins its
-name, revision, digest, and canonical definition. Publishing a new definition
-changes future selection only; it cannot silently alter an in-flight ticket.
+branches, joins, includes, and flow execution settings. Forge expands built-in
+and same-project active dependencies into one validated graph before a new run.
+Each instance pins the expanded artifact and dependency identities. Activating
+a new definition or dependency changes new runs only; it cannot silently alter
+an in-flight ticket.
 
 The trusted catalog provides authority: node identity, station contracts,
 allowed effects, mandatory policies, preconditions, and observation behavior.
@@ -88,8 +90,8 @@ There are two distinct extension paths.
 ### Project administrators: declarative configuration
 
 Project configuration can select a built-in or published workflow and compose
-catalog-registered nodes, routers, transitions, joins, concurrency, and resume
-mappings. It can configure repositories, proposal review, skills, and model
+catalog-registered nodes, routers, transitions, reusable definitions, joins,
+concurrency, and resume mappings. It can configure repositories, proposal review, skills, and model
 policy. It cannot execute Python or shell code, store credentials, make provider
 calls, add an effect operation, or relax trusted policies.
 

docs/architecture/reference.md

@@ -31,9 +31,10 @@ Run implementation tasks in rootless Podman containers on the Worker host instea
 
 ### Golden paths by issue type
 
-Forge ships versioned Feature, Bug, and Task Takeover definitions. They have distinct planning
-stages and reuse registered implementation, CI, and review stations. Project definitions may compose
-the registered catalog but cannot add arbitrary executable logic.
+Forge ships versioned Feature, Bug, and Task Takeover definitions. Their distinct planning
+stages share a reusable GitHub PR, CI, and review response subworkflow. Project definitions may
+include built-in or same-project active definitions and compose the registered catalog, but
+cannot add arbitrary executable logic. New instances pin the expanded graph.
 
 ### Human Approval Gates
 

docs/index.md

@@ -51,7 +51,7 @@ graph TD
 - [Operations](operations.md) — Services, execution inspection, recovery, and incident response
 - [Developer Guide](developer-guide.md) — Full local development reference
 - [Architecture](architecture/index.md) — How workflow state, reconciliation, stations, and effects fit together
-- [Declarative Workflows](reference/declarative-workflows.md) — Compose registered Forge stages safely
+- [Declarative Workflows](reference/declarative-workflows.md) — Compose and reuse registered Forge stages safely
 - [Configuration](reference/config.md) — Repository, model, proposal, and deployment settings
 - [Skills System](skills/index.md) — Customize Forge for your stack
 - [Contributing](dev/contributing.md) — How to contribute