forge

name	forge
description	Execute multi-project workflows through agent teams. Reads workflow definitions from workflows/ and project interfaces from registry/, then spawns a team to run the steps. Use when asked to "forge", "run workflow", "dispatch fleet", "orchestrate", or to execute any cross-project chain.
argument-hint	<workflow-name> [--arg value]

Forge

Execute a multi-project workflow by reading its definition and spawning an agent team to carry it out.

Process

1. Parse the request

Resolve the workflow name from $ARGUMENTS. If no workflow is named, list available workflows from workflows/*.yaml and ask which to run.

Read the workflow YAML from workflows/{name}.yaml. Parse:

• steps[] — ordered actions or prompts with dependencies
• arguments — required inputs from the user
• trigger — how the workflow starts

2. Load the registry

For each project referenced in the workflow steps, read its registry entry from registry/{project}.yaml. This tells you:

• Where the project lives (path)
• What CLI commands it exposes (cli[])
• What it provides and consumes

3. Plan the team

Map workflow steps to agents:

• Independent steps (no depends_on overlap) can run in parallel agents
• Sequential steps run in the same agent or with blockedBy dependencies
• Each agent gets: the step definition, the project's registry entry, and any upstream output it needs

Choose agent routing based on step type:

• Steps with action → forge-conductor (CLI execution)
• Steps with prompt (no agent) → general-purpose agent with the prompt
• Steps with prompt + agent → named agent (e.g., council-synthesis)
• Steps that need codebase exploration → Explore

4. Execute

Use the agent-teams pattern:

1. TeamCreate with name derived from the workflow
2. TaskCreate for each step, with blockedBy for dependencies
3. Spawn agents, passing the step definition and registry context
4. Monitor and route data between steps as they complete
5. Handle condition gates (skip steps whose conditions aren't met)

5. Report

After all steps complete (or a step fails):

• Summarize each step's outcome
• Report the final workflow status
• If any step produced artifacts, list them
• Invoke lore-scribe to capture durable decisions

Listing Workflows

If invoked with no arguments or with list:

ls workflows/*.yaml

Display each workflow's name and description from its YAML frontmatter.

Error Handling

• If a step fails, report which step and why. Do not retry automatically.
• If a depends_on step failed, skip downstream steps and report the chain.
• If a condition is not met, skip the step (this is normal, not an error).

See Also

• /agent-teams — the underlying team orchestration mechanism
• registry/ — project interface declarations
• workflows/ — workflow definitions