@phnx-labs/agents-cli 1.17.5 → 1.17.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.17.6
+
+**Workflows**
+
+- New `workflows` skill — author-and-run guide for workflow bundles (`WORKFLOW.md` frontmatter, `subagents/` directory for multi-agent pipelines, scoped `skills/` and `plugins/`, sharing via `agents repo push` or GitHub install). Calls out the `--mode plan` deadlock that bites workflows which need to post comments or edit files.
+- `agents workflows --help` rewritten with a structure diagram, project > user > system resolution order, and an explicit note that workflows mutating state need `--mode edit` or `--mode full` to avoid a headless deadlock at `ExitPlanMode`.
+- README gains a `Workflows` section between Teams and Browser covering the bundle layout, frontmatter, subagents/skills/plugins, and the `--mode` requirement.
+
 ## 1.17.4
 
 **Browser**

package/README.md

@@ -47,6 +47,7 @@ Also available as `ag` -- all commands work with both `agents` and `ag`.
 - [Sessions across agents](#sessions-across-agents)
 - [Run open models through Claude Code](#run-open-models-through-claude-code)
 - [Teams](#teams)
+- [Workflows](#workflows)
 - [Browser](#browser)
 - [Secrets](#secrets)
 - [Routines](#routines)
@@ -244,6 +245,57 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ---
 
+## Workflows
+
+Bundle an orchestrator prompt with optional subagents, skills, and plugins into a named, reusable pipeline. One bundle, one invocation.
+
+```bash
+# Use a workflow — workflow name goes in the agent slot
+agents run code-review "review PR #42 on acme/api"
+
+# List + inspect
+agents workflows list
+agents workflows view code-review
+
+# Install from GitHub or local
+agents workflows add gh:yourteam/code-review
+agents workflows add ./my-workflow
+```
+
+A workflow is a directory:
+
+```
+~/.agents/workflows/code-review/
+  WORKFLOW.md          # YAML frontmatter + orchestrator system prompt
+  subagents/           # optional: *.md files exposed to the orchestrator
+    security.md
+    style.md
+  skills/              # optional: knowledge packs scoped to this workflow
+  plugins/             # optional: plugin bundles
+```
+
+`WORKFLOW.md`'s Markdown body is the orchestrator's system prompt. Files under `subagents/` get copied to `~/.claude/agents/` at run time so the built-in Agent tool can dispatch to them by name — including in parallel. `skills/` and `plugins/` sync into the version home just for the run.
+
+```yaml
+# WORKFLOW.md frontmatter
+---
+name: Code Review
+description: Evidence-grounded PR review with file:line citations.
+model: claude-opus-4-7
+tools:
+  - Read
+  - Grep
+  - Bash
+  - WebFetch
+---
+```
+
+Workflows that need to write — post PR comments, edit files, send Slack — should run with `--mode edit` or `--mode full`. `agents run` defaults to `--mode plan` (read-only), which deadlocks at `ExitPlanMode` in headless runs.
+
+Resolution is project > user > system: a `<repo>/.agents/workflows/<name>/` overrides a same-named workflow in `~/.agents/workflows/`. Commit project workflows with your repo so teammates get the same pipeline.
+
+---
+
 ## Browser
 
 Give agents access to a real browser — no relay extension, no cloud service, no Playwright getting blocked.

package/dist/commands/workflows.js

@@ -17,21 +17,42 @@ export function registerWorkflowsCommands(program) {
         .command('workflows')
         .description('Manage multi-agent pipeline workflows (WORKFLOW.md bundles)')
         .addHelpText('after', `
-Workflows are directory bundles (WORKFLOW.md + subagents/) that define multi-agent pipelines run via:
-  agents run <workflow-name>
+Workflows are directory bundles that define reusable named agent pipelines.
+Run a workflow with:
+  agents run <workflow-name> [prompt]
+
+Structure:
+  ~/.agents/workflows/<name>/
+    WORKFLOW.md        required: YAML frontmatter + orchestrator system prompt
+    subagents/*.md     optional: subagents the orchestrator can dispatch to
+    skills/            optional: knowledge packs scoped to this workflow
+    plugins/           optional: plugin bundles scoped to this workflow
+
+Resolution: project (.agents/workflows/) > user (~/.agents/workflows/) > system.
+
+Note: agents run defaults to --mode plan (read-only). For workflows that
+write files, post comments, or otherwise mutate state, pass --mode edit or
+--mode full or the run will deadlock at ExitPlanMode.
 
 Examples:
   # See what workflows are available
   agents workflows list
 
-  # Install from GitHub
+  # Install from GitHub or a local directory
   agents workflows add gh:user/workflows
+  agents workflows add ./code-review
 
-  # Install a local workflow directory
-  agents workflows add ./rdev
+  # Inspect a workflow's frontmatter and subagents
+  agents workflows view code-review
 
-  # Remove a workflow
-  agents workflows remove rdev
+  # Run it (workflow name goes in the agent slot)
+  agents run code-review "review PR #42"
+
+  # Run a workflow that posts comments / edits files
+  agents run code-review --mode full "review PR #42 and post the review"
+
+  # Remove from version homes (and central storage on second run)
+  agents workflows remove code-review
 `);
     workflowsCmd
         .command('list [agent]')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.17.5",
+  "version": "1.17.6",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",