@phnx-labs/agents-cli 1.17.5 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+**Plugins**
+
+- `~/.agents/plugins/` is now a first-class user-resource location, alongside `skills/`, `commands/`, `hooks/`, etc. — git-tracked as source of truth. Previously, `migrateRuntimeToCache` moved `~/.agents/plugins/` into `~/.agents/.cache/plugins/` on every CLI version bump, silently destroying user-authored plugins in the working tree. Fixed by (1) removing the destructive move, (2) restoring discovery to the user-root, (3) a one-shot reverse migration that moves any cached plugins back to the user-root without overwriting an existing user-root copy, and (4) decoupling the migration sentinel from the binary version so migrations only re-run on real schema bumps. ([#20](https://github.com/phnx-labs/agents-cli/issues/20))
+- `agents view <agent>@<version>` gains a `Plugins` section listing each plugin that supports the agent, with a `(N skills, N commands, …)` content summary and an OSC 8 hyperlink to the plugin source.
+
+**Hooks**
+
+- `getAvailableResources` and the version-home sync now treat only executable files in `hooks/` as hooks. Docs (`README.md`) and data files (`promptcuts.yaml`) that live alongside hooks no longer get synced into version homes as hooks, and the orphan-pruner trusts the manifest's declared hook list rather than re-scanning every source dir.
+
+## 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/exec.js

@@ -22,6 +22,7 @@ import { readBundle, resolveBundleEnv, describeBundle } from '../lib/secrets/bun
 import { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES, } from '../lib/rotate.js';
 import { getGlobalDefault, getVersionHomePath, resolveVersionAlias } from '../lib/versions.js';
 import { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion } from '../lib/plugins.js';
+import { parseWorkflowFrontmatter } from '../lib/workflows.js';
 import * as fs from 'fs';
 import * as path from 'path';
 const VALID_AGENTS = Object.keys(AGENT_COMMANDS);
@@ -46,6 +47,7 @@ export function registerRunCommand(program) {
         .option('--model <model>', 'Override the model directly (e.g., claude-opus-4-6)')
         .option('--env <key=value>', 'Pass environment variable to the agent (repeatable, e.g., --env DEBUG=1 --env API_KEY=xyz)', (val, prev) => [...prev, val], [])
         .option('--secrets <bundle>', 'Inject a secrets bundle (repeatable). Values resolve from macOS Keychain at run time. See `agents secrets`.', (val, prev) => [...prev, val], [])
+        .option('--no-auto-secrets', 'Skip auto-injection of secrets declared by a workflow\'s frontmatter `secrets:` field. Has no effect on bare-agent runs.')
         .option('--cwd <dir>', 'Working directory for the agent (defaults to current directory)')
         .option('--add-dir <dir>', 'Grant access to an additional directory outside the project (Claude only, repeatable)', (val, prev) => [...prev, val], [])
         .option('--json', 'Stream events as JSON lines (for parsing by other tools)')
@@ -186,6 +188,26 @@ Examples:
                     syncPluginToVersion(buildDiscoveredPlugin(pluginRoot, manifest), 'claude', versionHome);
                 }
             }
+            // Auto-inject secrets bundles declared in the workflow's frontmatter `secrets:` field.
+            // Union with any --secrets flags the user passed; dedupe. Skip when --no-auto-secrets is set.
+            if (!options.noAutoSecrets) {
+                const fm = parseWorkflowFrontmatter(workflowDir);
+                const declared = fm?.secrets ?? [];
+                if (declared.length > 0) {
+                    const existing = new Set(options.secrets);
+                    const added = [];
+                    for (const b of declared) {
+                        if (!existing.has(b)) {
+                            options.secrets.push(b);
+                            existing.add(b);
+                            added.push(b);
+                        }
+                    }
+                    if (added.length > 0) {
+                        process.stderr.write(chalk.gray(`[workflow] auto-injecting secrets from ${rawAgent}: ${added.join(', ')}\n`));
+                    }
+                }
+            }
             const subagentCount = fs.existsSync(subagentsDir)
                 ? fs.readdirSync(subagentsDir).filter(f => f.endsWith('.md')).length
                 : 0;

package/dist/commands/view.js

@@ -9,6 +9,8 @@ import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getV
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
+import { discoverPlugins, pluginSupportsAgent } from '../lib/plugins.js';
+import { PLUGINS_CAPABLE_AGENTS } from '../lib/agents.js';
 import { getAgentsDir, getUserAgentsDir, getEffectivePromptcutsPath, readMergedPromptcuts } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
@@ -20,6 +22,27 @@ function termLink(text, filePath) {
     const url = `file://${filePath}`;
     return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
 }
+/**
+ * Resolve a resource path to something the IDE can open inline. When `p` is a
+ * directory, OSC 8 file:// links cause IDEs (Cursor/VS Code) to open it as a
+ * new workspace window; pointing at the bundle's marker file (SKILL.md /
+ * WORKFLOW.md / AGENT.md) opens in the current window instead.
+ */
+function linkTarget(p) {
+    try {
+        if (!fs.statSync(p).isDirectory())
+            return p;
+    }
+    catch {
+        return p;
+    }
+    for (const marker of ['SKILL.md', 'WORKFLOW.md', 'AGENT.md']) {
+        const candidate = path.join(p, marker);
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return p;
+}
 function formatLastActive(date) {
     if (!date)
         return '';
@@ -508,7 +531,7 @@ async function showAgentResources(agentId, requestedVersion) {
                 nameColor = chalk.yellow;
             else if (r.syncState === 'deleted')
                 nameColor = chalk.red;
-            const linkedName = r.path ? termLink(r.name, r.path) : r.name;
+            const linkedName = r.path ? termLink(r.name, linkTarget(r.path)) : r.name;
             let display = nameColor(linkedName);
             if (r.ruleCount !== undefined)
                 display += chalk.gray(` (${r.ruleCount} rules)`);
@@ -571,6 +594,34 @@ async function showAgentResources(agentId, requestedVersion) {
     if (WORKFLOW_CAPABLE_AGENTS.includes(agentId)) {
         renderSection('Workflows', agentData.workflows);
     }
+    if (PLUGINS_CAPABLE_AGENTS.includes(agentId)) {
+        const plugins = discoverPlugins().filter(p => pluginSupportsAgent(p, agentId));
+        console.log(chalk.bold('\nPlugins\n'));
+        if (plugins.length === 0) {
+            console.log(`  ${chalk.gray('none')}`);
+        }
+        else {
+            const versionStr = agentData.version ? ` (${agentData.version})` : '';
+            const agentHeader = home ? termLink(agentData.agentName, home) : agentData.agentName;
+            console.log(`  ${chalk.bold(agentHeader)}${chalk.gray(versionStr)}:`);
+            for (const p of plugins) {
+                const linkedName = termLink(p.name, linkTarget(p.root));
+                const parts = [];
+                if (p.skills.length > 0)
+                    parts.push(`${p.skills.length} skill${p.skills.length === 1 ? '' : 's'}`);
+                if (p.commands.length > 0)
+                    parts.push(`${p.commands.length} command${p.commands.length === 1 ? '' : 's'}`);
+                if (p.hooks.length > 0)
+                    parts.push(`${p.hooks.length} hook${p.hooks.length === 1 ? '' : 's'}`);
+                if (p.agentDefs.length > 0)
+                    parts.push(`${p.agentDefs.length} subagent${p.agentDefs.length === 1 ? '' : 's'}`);
+                if (p.hasMcp)
+                    parts.push('mcp');
+                const contents = parts.length > 0 ? chalk.gray(` (${parts.join(', ')})`) : '';
+                console.log(`    ${chalk.cyan(linkedName)}${contents} ${chalk.cyan('[user]')}`);
+            }
+        }
+    }
     // Rules section with subrules breakdown
     function renderRulesSection() {
         console.log(chalk.bold('\nRules\n'));
@@ -600,7 +651,7 @@ async function showAgentResources(agentId, requestedVersion) {
                 nameColor = chalk.yellow;
             else if (r.syncState === 'deleted')
                 nameColor = chalk.red;
-            const linkedName = r.path ? termLink(r.name, r.path) : r.name;
+            const linkedName = r.path ? termLink(r.name, linkTarget(r.path)) : r.name;
             let display = nameColor(linkedName);
             if (r.ruleCount !== undefined)
                 display += chalk.gray(` (${r.ruleCount} rules)`);

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]')
@@ -373,14 +394,16 @@ Examples:
             lines.push(`  ${fm.description}`);
         lines.push('');
         if (fm.model)
-            lines.push(`  Model:  ${fm.model}`);
+            lines.push(`  Model:   ${fm.model}`);
         if (fm.tools?.length)
-            lines.push(`  Tools:  ${fm.tools.join(', ')}`);
+            lines.push(`  Tools:   ${fm.tools.join(', ')}`);
         if (fm.mcpServers?.length)
-            lines.push(`  MCP:    ${fm.mcpServers.join(', ')}`);
+            lines.push(`  MCP:     ${fm.mcpServers.join(', ')}`);
         if (fm.skills?.length)
-            lines.push(`  Skills: ${fm.skills.join(', ')}`);
-        lines.push(`  Path:   ${workflow.path}`);
+            lines.push(`  Skills:  ${fm.skills.join(', ')}`);
+        if (fm.secrets?.length)
+            lines.push(`  Secrets: ${fm.secrets.join(', ')}  ${chalk.gray('(auto-injected at run time — pass --no-auto-secrets to skip)')}`);
+        lines.push(`  Path:    ${workflow.path}`);
         if (fm.allowedAgents?.length) {
             lines.push(chalk.bold(`\n  Subagents (${workflow.subagentCount}):`));
             for (const a of fm.allowedAgents) {

package/dist/index.js

@@ -666,7 +666,11 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
     try {
         const { runMigration } = await import('./lib/migrate.js');
         const sentinel = getMigratedSentinelPath();
-        const sentinelValue = `${VERSION}-v8`;
+        // Sentinel is keyed to the migration SCHEMA version, not the binary version.
+        // Bumping the suffix re-runs migrations for every user; binary releases that
+        // don't change the schema must NOT re-run (they would destroy user content
+        // when migration steps overlap with user-authored paths). See issue #20.
+        const sentinelValue = 'v9';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/migrate.js

@@ -740,6 +740,62 @@ function migrateRuntimeToHistory() {
         catch { /* best-effort */ }
     }
 }
+/**
+ * Restore plugins from the cache bucket back to the user-root.
+ *
+ * Earlier releases moved ~/.agents/plugins/ → ~/.agents/.cache/plugins/ as part
+ * of `migrateRuntimeToCache`. That was wrong: plugins are user-authored
+ * resources (alongside skills/, commands/, hooks/) and belong at the user-root
+ * so they're git-tracked. See issue #20.
+ *
+ * For each ~/.agents/.cache/plugins/<name>/ that the user already has at
+ * ~/.agents/plugins/<name>/, the cache copy is left alone — the user-root copy
+ * wins. For plugins only present in the cache, the directory is moved back to
+ * the user-root. Idempotent.
+ */
+function migratePluginsBackToUserRoot() {
+    const cachePlugins = path.join(CACHE_DIR, 'plugins');
+    const userPlugins = path.join(USER_DIR, 'plugins');
+    if (!fs.existsSync(cachePlugins))
+        return;
+    let entries;
+    try {
+        entries = fs.readdirSync(cachePlugins, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    try {
+        fs.mkdirSync(userPlugins, { recursive: true, mode: 0o700 });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const src = path.join(cachePlugins, entry.name);
+        const dest = path.join(userPlugins, entry.name);
+        if (fs.existsSync(dest))
+            continue;
+        try {
+            fs.renameSync(src, dest);
+        }
+        catch {
+            try {
+                copyDirSkipExisting(src, dest);
+                fs.rmSync(src, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    // Drop the cache plugins dir if we emptied it.
+    try {
+        if (fs.readdirSync(cachePlugins).length === 0)
+            fs.rmdirSync(cachePlugins);
+    }
+    catch { /* best-effort */ }
+}
 /**
  * Move regenerable runtime data into ~/.agents/.cache/.
  *
@@ -747,7 +803,6 @@ function migrateRuntimeToHistory() {
  *   ~/.agents/shims/         -> ~/.agents/.cache/shims/
  *   ~/.agents/bin/           -> ~/.agents/.cache/bin/
  *   ~/.agents/packages/      -> ~/.agents/.cache/packages/
- *   ~/.agents/plugins/       -> ~/.agents/.cache/plugins/
  *   ~/.agents/cloud/         -> ~/.agents/.cache/cloud/
  *   ~/.agents/drive/         -> ~/.agents/.cache/drive/
  *   ~/.agents/terminals/     -> ~/.agents/.cache/terminals/
@@ -772,7 +827,10 @@ function migrateRuntimeToCache() {
     moveDirOnce(path.join(USER_DIR, 'shims'), path.join(CACHE_DIR, 'shims'));
     moveDirOnce(path.join(USER_DIR, 'bin'), path.join(CACHE_DIR, 'bin'));
     moveDirOnce(path.join(USER_DIR, 'packages'), path.join(CACHE_DIR, 'packages'));
-    moveDirOnce(path.join(USER_DIR, 'plugins'), path.join(CACHE_DIR, 'plugins'));
+    // ~/.agents/plugins/ is intentionally NOT migrated — it is user-authored
+    // content (git-tracked), alongside skills/, commands/, hooks/. The reverse
+    // migration `migratePluginsBackToUserRoot` reclaims any plugins/ that prior
+    // releases moved into ~/.agents/.cache/plugins/. See issue #20.
     moveDirOnce(path.join(USER_DIR, 'cloud'), path.join(CACHE_DIR, 'cloud'));
     moveDirOnce(path.join(USER_DIR, 'drive'), path.join(CACHE_DIR, 'drive'));
     // terminals/ stays at the top level: the agents-cli IDE extension publishes
@@ -1405,6 +1463,10 @@ export async function runMigration() {
     // Bucket moves: collapse runtime state into ~/.agents/.history and ~/.agents/.cache.
     migrateRuntimeToHistory();
     migrateRuntimeToCache();
+    // Restore plugins (user-authored) from cache back to user-root. Runs AFTER
+    // migrateRuntimeToCache so any legacy plugins/ still at the user-root from
+    // very-old layouts have already been handled.
+    migratePluginsBackToUserRoot();
     // System-repo sweep: move every remaining operational dir into its canonical
     // user-bucket location, then drop known-dead artifacts and warn about
     // anything we don't recognize. Order: durable (sessions/teams/trash/repos/

package/dist/lib/plugins.d.ts

@@ -1,14 +1,16 @@
 /**
  * Plugin discovery, validation, and syncing.
  *
- * Plugins are bundles in ~/.agents/.cache/plugins/ that package skills, hooks,
+ * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
  * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). This module discovers plugins, validates their
- * manifests, and syncs their contents into agent version homes.
+ * manifest (plugin.json). They are user-authored resources, sitting alongside
+ * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
+ * module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes.
  */
 import type { AgentId, DiscoveredPlugin, PluginManifest } from './types.js';
 /**
- * Discover all plugins in ~/.agents/.cache/plugins/.
+ * Discover all plugins in ~/.agents/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
  */
 export declare function discoverPlugins(): DiscoveredPlugin[];
@@ -131,7 +133,7 @@ export declare function parseInstallSpec(spec: string): {
 };
 /**
  * Install a plugin from a git URL or local path.
- * Clones/copies to ~/.agents/.cache/plugins/<name>/.
+ * Clones/copies to ~/.agents/plugins/<name>/.
  * Returns the installed plugin name and root path.
  */
 export declare function installPlugin(spec: string): Promise<{

package/dist/lib/plugins.js

@@ -1,10 +1,12 @@
 /**
  * Plugin discovery, validation, and syncing.
  *
- * Plugins are bundles in ~/.agents/.cache/plugins/ that package skills, hooks,
+ * Plugins are bundles in ~/.agents/plugins/ that package skills, hooks,
  * commands, agents, bin scripts, MCP servers, and settings under a single
- * manifest (plugin.json). This module discovers plugins, validates their
- * manifests, and syncs their contents into agent version homes.
+ * manifest (plugin.json). They are user-authored resources, sitting alongside
+ * skills/, commands/, hooks/, etc. — git-tracked as source of truth. This
+ * module discovers plugins, validates their manifests, and syncs their
+ * contents into agent version homes.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -17,7 +19,7 @@ const PLUGIN_MANIFEST_FILE = 'plugin.json';
 const USER_CONFIG_FILE = '.user-config.json';
 const SOURCE_FILE = '.source';
 /**
- * Discover all plugins in ~/.agents/.cache/plugins/.
+ * Discover all plugins in ~/.agents/plugins/.
  * A valid plugin has a .claude-plugin/plugin.json manifest.
  */
 export function discoverPlugins() {
@@ -1034,7 +1036,7 @@ export function parseInstallSpec(spec) {
 }
 /**
  * Install a plugin from a git URL or local path.
- * Clones/copies to ~/.agents/.cache/plugins/<name>/.
+ * Clones/copies to ~/.agents/plugins/<name>/.
  * Returns the installed plugin name and root path.
  */
 export async function installPlugin(spec) {

package/dist/lib/state.d.ts

@@ -111,7 +111,7 @@ export declare function getShimsDir(): string;
 export declare function getBinDir(): string;
 /** Path to config backups (~/.agents/.history/backups/). */
 export declare function getBackupsDir(): string;
-/** Path to plugin bundles (~/.agents/.cache/plugins/). */
+/** Path to plugin bundles (~/.agents/plugins/) — user-authored resource. */
 export declare function getPluginsDir(): string;
 /** Path to synced remote session data (~/.agents/.cache/drive/). */
 export declare function getDriveDir(): string;

package/dist/lib/state.js

@@ -65,7 +65,9 @@ const TRASH_DIR = path.join(HISTORY_DIR, 'trash');
 const SHIMS_DIR = path.join(CACHE_DIR, 'shims');
 const BIN_DIR = path.join(CACHE_DIR, 'bin');
 const PACKAGES_DIR = path.join(CACHE_DIR, 'packages');
-const PLUGINS_DIR = path.join(CACHE_DIR, 'plugins');
+// Plugins are user-authored resources, alongside skills/, commands/, hooks/.
+// They live at the user-root so they're git-tracked as source of truth.
+const PLUGINS_DIR = path.join(USER_AGENTS_DIR, 'plugins');
 const CLOUD_DIR = path.join(CACHE_DIR, 'cloud');
 const DRIVE_DIR = path.join(CACHE_DIR, 'drive');
 const TERMINALS_DIR = path.join(CACHE_DIR, 'terminals');
@@ -266,7 +268,7 @@ export function getShimsDir() { return SHIMS_DIR; }
 export function getBinDir() { return BIN_DIR; }
 /** Path to config backups (~/.agents/.history/backups/). */
 export function getBackupsDir() { return BACKUPS_DIR; }
-/** Path to plugin bundles (~/.agents/.cache/plugins/). */
+/** Path to plugin bundles (~/.agents/plugins/) — user-authored resource. */
 export function getPluginsDir() { return PLUGINS_DIR; }
 /** Path to synced remote session data (~/.agents/.cache/drive/). */
 export function getDriveDir() { return DRIVE_DIR; }

package/dist/lib/versions.js

@@ -109,15 +109,24 @@ export function getAvailableResources(cwd = process.cwd()) {
         }
     }
     result.skills = Array.from(skillNames);
-    // Hooks (files)
+    // Hooks (files). Only executable files in hooks/ count as hooks. Auxiliary
+    // files like README.md (docs) or promptcuts.yaml (data read directly by a
+    // hook script) live alongside hooks but are not hooks themselves and must
+    // not be synced as such.
     const hookNames = new Set();
     for (const { base } of resourceBases) {
         const hooksDir = path.join(base, 'hooks');
         if (!fs.existsSync(hooksDir))
             continue;
-        const names = fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'));
-        for (const name of names) {
-            hookNames.add(name);
+        for (const name of fs.readdirSync(hooksDir)) {
+            if (name.startsWith('.'))
+                continue;
+            try {
+                const stat = fs.statSync(path.join(hooksDir, name));
+                if (stat.isFile() && (stat.mode & 0o111) !== 0)
+                    hookNames.add(name);
+            }
+            catch { /* ignore unreadable */ }
         }
     }
     result.hooks = Array.from(hookNames);
@@ -1674,29 +1683,15 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
                     fs.chmodSync(destFile, 0o755);
                     syncedHooks.push(hook);
                 }
-                // Remove orphan hook files that exist in version home but not in any trusted source.
-                const centralHookNames = new Set(fs.existsSync(getHooksDir())
-                    ? fs.readdirSync(getHooksDir()).filter(f => !f.startsWith('.'))
-                    : []);
-                {
-                    const hooksDir = path.join(userAgentsDir, 'hooks');
-                    if (fs.existsSync(hooksDir)) {
-                        for (const file of fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'))) {
-                            centralHookNames.add(file);
-                        }
-                    }
-                }
-                for (const extra of extraRepos) {
-                    const hooksDir = path.join(extra.dir, 'hooks');
-                    if (fs.existsSync(hooksDir)) {
-                        for (const file of fs.readdirSync(hooksDir).filter(f => !f.startsWith('.'))) {
-                            centralHookNames.add(file);
-                        }
-                    }
-                }
+                // Remove orphan files from version home. The trusted set is the
+                // manifest-declared hook list (`available.hooks`) — auxiliary files
+                // like README.md or promptcuts.yaml may exist alongside hooks at the
+                // source but are not hooks and must not linger in version homes from
+                // older syncs.
+                const trustedHookNames = new Set(available.hooks);
                 if (fs.existsSync(hooksTarget)) {
                     for (const file of fs.readdirSync(hooksTarget).filter(f => !f.startsWith('.'))) {
-                        if (!centralHookNames.has(file)) {
+                        if (!trustedHookNames.has(file)) {
                             removePath(safeJoin(hooksTarget, file));
                         }
                     }

package/dist/lib/workflows.d.ts

@@ -17,6 +17,13 @@ export interface WorkflowFrontmatter {
     skills?: string[];
     mcpServers?: string[];
     allowedAgents?: string[];
+    /**
+     * Secrets bundle names this workflow needs (e.g. `linear.app`, `github.com`).
+     * When `agents run <workflow>` resolves a workflow, these are unioned into the
+     * effective `--secrets` list and resolved from the macOS Keychain before spawn.
+     * Pass `--no-auto-secrets` to skip this injection.
+     */
+    secrets?: string[];
 }
 /** A workflow found during repo discovery. */
 export interface DiscoveredWorkflow {

package/dist/lib/workflows.js

@@ -37,6 +37,7 @@ export function parseWorkflowFrontmatter(workflowDir) {
             skills: parsed.skills,
             mcpServers: parsed.mcpServers,
             allowedAgents: parsed.allowedAgents,
+            secrets: parsed.secrets,
         };
     }
     catch {

package/package.json

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