@markjaquith/agency 3.6.2 → 3.8.0

package/README.md

@@ -564,7 +564,11 @@ agency validate
 ### Interactive Actions
 
 `agency` with no subcommand (or `agency act`) opens on **Workstream**, a flat list
-of non-archived tasks and phases; select an item to see its available actions.
+of non-archived tasks and phases. When run inside an epic, task, phase, or one of
+its checkout descendants, it opens that item's actions first; Escape returns to
+Workstream, where **Tab** reaches global Workbase actions. `agency .` is shorthand
+for `agency act .` and explicitly focuses the item containing the current path.
+Otherwise, select an item to see its available actions.
 Press **Tab** to cycle to **Workbase** for workbase actions. Both tabs have a blank
 row above a chevron-prefixed filter with the placeholder “type to filter”.
 Each tab remembers its filter and selection. The active
@@ -612,18 +616,21 @@ handoffs restore the terminal before starting the interactive worker, then reope
 the TUI when the worker returns. A configured
 external chooser continues to offer goals and **Browse items** through that chooser.
 
-| Goal                                 | Choose in `act`                                                                                   | Discovery/action ID                   |
-| ------------------------------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| Add a repository                     | Add from a remote, or link an existing local repository                                           | `repo-add`, `repo-link`               |
-| Create a task                        | Create a task → standard task or investigation; describe the outcome                              | `task-create`, `investigation-create` |
-| Split work                           | Add a phase / split this task; name the existing work's first phase                               | `split`                               |
-| Work on a task or phase              | Work on this item                                                                                 | `work`                                |
-| Move from investigation to execution | Create implementation follow-up                                                                   | `handoff`                             |
-| Review someone else's work           | Review a PR, or a remote branch/commit                                                            | `review`, `review-ref`                |
-| Close finished work                  | Close or reopen work → complete without a PR, drop abandoned work, refresh a merged PR, or reopen | `complete`, `drop`, `sync`, `reopen`  |
-| Update PR status                     | Refresh Agency state from the provider, create a PR, mark a GitHub PR ready, or close it          | `sync`, `pr`, `pr-ready`, `pr-close`  |
-| Archive terminal work                | Archive                                                                                           | `archive`                             |
-| See current work                     | See current work                                                                                  | `current-work`                        |
+| Goal                                 | Choose in `act`                                                                                   | Discovery/action ID                                                                                                                                |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Manage repositories                  | Add, link, set up, materialize, fetch, verify, rename, update, unlink, or remove aliases          | `repo-add`, `repo-link`, `repo-setup`, `repo-materialize`, `repo-fetch`, `repo-verify`, `repo-rename`, `repo-remote`, `repo-unlink`, `repo-remove` |
+| Create work                          | Create a standard task, multi-phase task, investigation, epic, or a task inside an epic           | `task-create`, `multi-phase-create`, `investigation-create`, `epic-create`, `task-create-in-epic`                                                  |
+| Split work                           | Add a phase / split this task; name the existing work's first phase                               | `split`                                                                                                                                            |
+| Work on a task or phase              | Work on this item                                                                                 | `work`                                                                                                                                             |
+| Move from investigation to execution | Create implementation follow-up                                                                   | `handoff`                                                                                                                                          |
+| Review someone else's work           | Review a PR, or a remote branch/commit                                                            | `review`, `review-ref`                                                                                                                             |
+| Close finished work                  | Close or reopen work → complete without a PR, drop abandoned work, refresh a merged PR, or reopen | `complete`, `drop`, `sync`, `reopen`                                                                                                               |
+| Publish or update PR status          | Push without a PR, refresh provider state, create a PR, mark a GitHub PR ready, or close it       | `push`, `sync`, `pr`, `pr-ready`, `pr-close`                                                                                                       |
+| Maintain review work                 | Fetch and repin a review task to its current source                                               | `review-refresh`                                                                                                                                   |
+| Organize work                        | Rename an item, move a task into/out of an epic, or add/remove a sibling dependency               | `rename`, `move-to-epic`, `remove-from-epic`, `dependency-add`, `dependency-remove`                                                                |
+| Archive terminal work                | Archive                                                                                           | `archive`                                                                                                                                          |
+| See work status                      | See current or ready work                                                                         | `current-work`, `ready-work`                                                                                                                       |
+| Check or refresh the workbase        | Validate, diagnose, reconcile all state, or inspect/update managed integration files              | `validate`, `doctor`, `sync-all`, `integration-status`, `integration-sync`                                                                         |
 
 After creating a task, phase, review, or implementation follow-up, choose **Work
 on the new item now** or **Finish**. Only choosing Work prepares checkouts and
@@ -659,6 +666,8 @@ For agents, `--json` never prompts or executes. Its compact, runtime-validated
 result includes workbase actions and repository aliases, current working items,
 and matching targets with readiness, document revisions, available `actions`,
 and `blockedActions` with reasons. `--action` filters discovery to one scenario.
+Every action includes a concise `description`, Nerd Font `icon`, and semantic
+hex `color`, in addition to its label and availability.
 Targets and current working items share the same identity and metadata fields:
 `id`, `kind`, `key`, `status`, `description`, `repo` (the declared main repository,
 when present), `repositories`, `readiness`, and `revision`. Descriptions retain

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "3.6.2",
+  "version": "3.8.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/act-schema.ts

@@ -6,6 +6,9 @@ const Argv = Schema.Array(Schema.String)
 const Action = Schema.Struct({
 	id: Schema.String,
 	label: Schema.optional(Schema.String),
+	description: Schema.String,
+	icon: Schema.String,
+	color: Schema.String,
 	available: Schema.Boolean,
 	blockedReason: Schema.optional(Schema.NullOr(Schema.String)),
 	inputs: Schema.optional(

package/src/cli-parser.ts

@@ -499,7 +499,14 @@ const commands = {
 				usage: "agency task status <id> <status> [options] [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json", "task", "no-pull-request", "summary", "evidence-url"],
+				options: [
+					"json",
+					"task",
+					"if-revision",
+					"no-pull-request",
+					"summary",
+					"evidence-url",
+				],
 			},
 			update: {
 				usage: "agency task update <id> [options] [--json]",
@@ -630,6 +637,7 @@ const commands = {
 					"json",
 					"task",
 					"phase",
+					"if-revision",
 					"no-pull-request",
 					"summary",
 					"evidence-url",
@@ -1355,12 +1363,13 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		return { commandPath: "root", args: [], values: parsed.values }
 	}
 
-	const commandName = args[commandIndex]!
+	const suppliedCommandName = args[commandIndex]!
+	const commandName = suppliedCommandName === "." ? "act" : suppliedCommandName
 	const definition: CommandDefinition | undefined =
 		commands[commandName as keyof typeof commands]
 	if (!definition) {
 		throw usageError(
-			`Unknown command '${commandName}'.`,
+			`Unknown command '${suppliedCommandName}'.`,
 			"agency <command> [options]",
 		)
 	}
@@ -1405,6 +1414,7 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	}
 	const commandArgs = [
 		...args.slice(0, commandIndex),
+		...(suppliedCommandName === "." ? ["."] : []),
 		...args.slice(commandIndex + 1),
 	]
 	const parsed = parse(commandArgs, definition.options, definition.usage)

package/src/commands/act-actions.ts

@@ -1,15 +1,23 @@
 import { Effect } from "effect"
+import { join } from "node:path"
 import type { GraphNode } from "../graph-schema"
 import type { BaseCommandOptions } from "../utils/command"
 import type { ActionPrompts } from "./act-prompts"
 import { archive } from "./archive"
+import { doctor } from "./doctor"
+import { epic } from "./epic"
+import { integration } from "./integration"
 import { repo } from "./repo"
+import { review } from "./review"
 import { task } from "./task"
 import { phase } from "./phase"
+import { push } from "./push"
 import { sync } from "./sync"
 import { status } from "./status"
 import { pr, prCreate } from "./pr"
+import { validate } from "./validate"
 import { work as startWork, type StartWork } from "./work"
+import { macchiato } from "../utils/theme"
 
 export type ActEntity = Extract<
 	GraphNode,
@@ -18,9 +26,15 @@ export type ActEntity = Extract<
 type NativeOperation =
 	| ReturnType<typeof task>
 	| ReturnType<typeof phase>
+	| ReturnType<typeof epic>
 	| ReturnType<typeof repo>
+	| ReturnType<typeof review>
+	| ReturnType<typeof push>
 	| ReturnType<typeof sync>
 	| ReturnType<typeof status>
+	| ReturnType<typeof doctor>
+	| ReturnType<typeof integration>
+	| ReturnType<typeof validate>
 	| ReturnType<typeof prCreate>
 	| ReturnType<typeof archive>
 	| ReturnType<StartWork>
@@ -50,11 +64,241 @@ interface Details {
 	readonly inputs?: readonly Input[]
 }
 export interface ActAction extends Details {
+	readonly description: string
+	readonly icon: string
+	readonly color: string
 	readonly preview: Plan
 	/** Replayable input collection. All mutations belong in the returned plan.run. */
 	readonly prepare: (prompts: ActionPrompts) => Effect.Effect<Plan, Error>
 }
 
+const actionPresentation: Record<
+	string,
+	{
+		readonly description: string
+		readonly icon: string
+		readonly color: string
+	}
+> = {
+	"repo-add": {
+		description: "Clone a remote repository into this workbase.",
+		icon: "󰐕",
+		color: macchiato.green,
+	},
+	"repo-link": {
+		description: "Use an existing local checkout as a repository alias.",
+		icon: "󰌷",
+		color: macchiato.sapphire,
+	},
+	"repo-setup": {
+		description: "Materialize all portable repository declarations.",
+		icon: "󰋊",
+		color: macchiato.blue,
+	},
+	"repo-materialize": {
+		description: "Replace a linked alias with a managed bare clone.",
+		icon: "󰆧",
+		color: macchiato.blue,
+	},
+	"repo-fetch": {
+		description: "Fetch and prune a repository alias.",
+		icon: "󰑐",
+		color: macchiato.sapphire,
+	},
+	"repo-verify": {
+		description: "Check that a repository alias is operational.",
+		icon: "󰄬",
+		color: macchiato.green,
+	},
+	"repo-rename": {
+		description: "Rename an unused repository alias.",
+		icon: "󰑕",
+		color: macchiato.yellow,
+	},
+	"repo-remote": {
+		description: "Update an alias's portable remote declaration.",
+		icon: "󰛳",
+		color: macchiato.sapphire,
+	},
+	"repo-unlink": {
+		description: "Remove only this machine's linked checkout.",
+		icon: "󰌺",
+		color: macchiato.red,
+	},
+	"repo-remove": {
+		description: "Remove an unused alias and its local materialization.",
+		icon: "󰆴",
+		color: macchiato.red,
+	},
+	"task-create": {
+		description: "Create one deliverable execution task.",
+		icon: "󰐕",
+		color: macchiato.green,
+	},
+	"multi-phase-create": {
+		description: "Create a task that will be delivered through phases.",
+		icon: "",
+		color: macchiato.yellow,
+	},
+	"investigation-create": {
+		description: "Create evidence-gathering work before implementation.",
+		icon: "󰍉",
+		color: macchiato.mauve,
+	},
+	"epic-create": {
+		description: "Create an epic to coordinate related tasks.",
+		icon: "",
+		color: macchiato.mauve,
+	},
+	"task-create-in-epic": {
+		description: "Create a new execution task inside this epic.",
+		icon: "󰐕",
+		color: macchiato.green,
+	},
+	review: {
+		description: "Create a task pinned to an existing pull request.",
+		icon: "󰍉",
+		color: macchiato.mauve,
+	},
+	"review-ref": {
+		description: "Create a task pinned to a remote branch or commit.",
+		icon: "󰓹",
+		color: macchiato.mauve,
+	},
+	"current-work": {
+		description: "Show tasks and phases currently being worked.",
+		icon: "",
+		color: macchiato.blue,
+	},
+	"ready-work": {
+		description: "Show execution units that are ready to start.",
+		icon: "󰄱",
+		color: macchiato.green,
+	},
+	validate: {
+		description: "Validate workbase documents and relationships.",
+		icon: "󰄬",
+		color: macchiato.green,
+	},
+	doctor: {
+		description: "Diagnose workbase, repository, and integration health.",
+		icon: "󰒡",
+		color: macchiato.yellow,
+	},
+	"sync-all": {
+		description: "Reconcile all work with repository and provider state.",
+		icon: "󰑓",
+		color: macchiato.sapphire,
+	},
+	"integration-status": {
+		description: "Inspect managed agent integration files.",
+		icon: "󰋼",
+		color: macchiato.blue,
+	},
+	"integration-sync": {
+		description: "Update safe managed agent integration files.",
+		icon: "󰑐",
+		color: macchiato.sapphire,
+	},
+	work: {
+		description: "Prepare this item and start its configured worker.",
+		icon: "",
+		color: macchiato.green,
+	},
+	push: {
+		description: "Validate and publish this execution branch without a PR.",
+		icon: "󰜷",
+		color: macchiato.sapphire,
+	},
+	pr: {
+		description: "Publish this execution branch and record its pull request.",
+		icon: "",
+		color: macchiato.mauve,
+	},
+	"review-refresh": {
+		description: "Fetch and repin this review task to its current source.",
+		icon: "󰑐",
+		color: macchiato.sapphire,
+	},
+	reopen: {
+		description: "Return terminal work to open status.",
+		icon: "󰑓",
+		color: macchiato.sapphire,
+	},
+	drop: {
+		description: "Abandon this item without satisfying dependents.",
+		icon: "󰅖",
+		color: macchiato.red,
+	},
+	archive: {
+		description: "Move terminal work into the archive.",
+		icon: "",
+		color: macchiato.yellow,
+	},
+	split: {
+		description: "Convert or extend this task with another delivery phase.",
+		icon: "",
+		color: macchiato.yellow,
+	},
+	handoff: {
+		description: "Create distinct implementation work from this investigation.",
+		icon: "",
+		color: macchiato.mauve,
+	},
+	complete: {
+		description: "Record a genuine non-PR outcome as complete.",
+		icon: "󰄬",
+		color: macchiato.green,
+	},
+	sync: {
+		description: "Reconcile this item with repository and provider state.",
+		icon: "󰑓",
+		color: macchiato.sapphire,
+	},
+	"pr-ready": {
+		description: "Mark this recorded GitHub pull request ready for review.",
+		icon: "󰄬",
+		color: macchiato.green,
+	},
+	"pr-close": {
+		description: "Close this recorded GitHub pull request.",
+		icon: "",
+		color: macchiato.red,
+	},
+	rename: {
+		description: "Rename this item and update durable references.",
+		icon: "󰑕",
+		color: macchiato.yellow,
+	},
+	"dependency-add": {
+		description: "Require another sibling item to finish first.",
+		icon: "󰌹",
+		color: macchiato.yellow,
+	},
+	"dependency-remove": {
+		description: "Remove a completion dependency from this item.",
+		icon: "󰌺",
+		color: macchiato.red,
+	},
+	"move-to-epic": {
+		description: "Move this task into an existing epic.",
+		icon: "󰉒",
+		color: macchiato.mauve,
+	},
+	"remove-from-epic": {
+		description: "Move this task out of its current epic.",
+		icon: "󰉍",
+		color: macchiato.yellow,
+	},
+}
+
+const present = (details: Details) => {
+	const presentation = actionPresentation[details.id]
+	if (!presentation)
+		throw new Error(`Missing presentation for action '${details.id}'`)
+	return { ...details, ...presentation }
+}
+
 // A typed argument builder is used for both discovery and execution. Prompts are
 // ordinary TypeScript; discovery does not expose or interpret form instructions.
 const action = <A>(
@@ -63,12 +307,12 @@ const action = <A>(
 	read: (p: ActionPrompts) => Effect.Effect<A, Error>,
 	build: (args: A) => Plan,
 ): ActAction => ({
-	...details,
+	...present(details),
 	preview: build(example),
 	prepare: (p) => Effect.map(read(p), build),
 })
 const immediate = (details: Details, plan: Plan): ActAction => ({
-	...details,
+	...present(details),
 	preview: plan,
 	prepare: () => Effect.succeed(plan),
 })
@@ -90,9 +334,15 @@ const taskTarget = (node: ActEntity) =>
 export const actionGroups = [
 	{
 		id: "create",
-		label: "Create a task",
+		label: "Create work",
 		icon: "󰐕",
-		actions: ["task-create", "investigation-create"],
+		actions: [
+			"task-create",
+			"multi-phase-create",
+			"investigation-create",
+			"epic-create",
+			"task-create-in-epic",
+		],
 	},
 	{
 		id: "work",
@@ -120,9 +370,9 @@ export const actionGroups = [
 	},
 	{
 		id: "current-work",
-		label: "See current work",
+		label: "See work status",
 		icon: "",
-		actions: ["current-work"],
+		actions: ["current-work", "ready-work"],
 	},
 	{
 		id: "browse",
@@ -132,9 +382,9 @@ export const actionGroups = [
 	},
 	{
 		id: "pull-request",
-		label: "Update pull-request status",
+		label: "Publish or update a pull request",
 		icon: "",
-		actions: ["sync", "pr", "pr-ready", "pr-close"],
+		actions: ["push", "sync", "pr", "pr-ready", "pr-close"],
 	},
 	{
 		id: "close",
@@ -150,9 +400,44 @@ export const actionGroups = [
 	},
 	{
 		id: "repository",
-		label: "Add a repository",
+		label: "Manage repositories",
 		icon: "",
-		actions: ["repo-add", "repo-link"],
+		actions: [
+			"repo-add",
+			"repo-link",
+			"repo-setup",
+			"repo-materialize",
+			"repo-fetch",
+			"repo-verify",
+			"repo-rename",
+			"repo-remote",
+			"repo-unlink",
+			"repo-remove",
+		],
+	},
+	{
+		id: "health",
+		label: "Check or refresh the workbase",
+		icon: "󰒡",
+		actions: [
+			"validate",
+			"doctor",
+			"sync-all",
+			"integration-status",
+			"integration-sync",
+		],
+	},
+	{
+		id: "organize",
+		label: "Rename or change dependencies",
+		icon: "󰙅",
+		actions: [
+			"rename",
+			"move-to-epic",
+			"remove-from-epic",
+			"dependency-add",
+			"dependency-remove",
+		],
 	},
 ] as const
 
@@ -209,26 +494,38 @@ export const actActions = (
 					}),
 				),
 			),
-			...([false, true] as const).map((investigation) =>
+			...(["standard", "multi-phase", "investigation"] as const).map((kind) =>
 				action(
 					{
-						id: investigation ? "investigation-create" : "task-create",
-						label: investigation
-							? "Create an investigation"
-							: "Create a standard task",
-						blockedReason: needsRepository,
+						id:
+							kind === "standard"
+								? "task-create"
+								: kind === "multi-phase"
+									? "multi-phase-create"
+									: "investigation-create",
+						label:
+							kind === "standard"
+								? "Create a standard task"
+								: kind === "multi-phase"
+									? "Create a multi-phase task"
+									: "Create an investigation",
+						blockedReason: kind === "multi-phase" ? null : needsRepository,
 						inputs: [
 							input("description", "Outcome", { multiline: true }),
 							input("id", "Task ID"),
-							input("repo", "Repository alias"),
-							input("base", "Base branch"),
+							...(kind === "multi-phase"
+								? []
+								: [
+										input("repo", "Repository alias"),
+										input("base", "Base branch"),
+									]),
 						],
 					},
 					{
 						id: "<id>",
 						description: "<description>",
-						repo: "<repo>",
-						base: "<base>",
+						repo: kind === "multi-phase" ? undefined : "<repo>",
+						base: kind === "multi-phase" ? undefined : "<base>",
 					},
 					(p) =>
 						Effect.gen(function* () {
@@ -236,8 +533,12 @@ export const actActions = (
 							return {
 								description,
 								id: yield* p.id("New task ID", description),
-								repo: yield* p.repository(),
-								base: yield* p.text("Base branch", "main"),
+								repo:
+									kind === "multi-phase" ? undefined : yield* p.repository(),
+								base:
+									kind === "multi-phase"
+										? undefined
+										: yield* p.text("Base branch", "main"),
 							}
 						}),
 					(args) => ({
@@ -246,25 +547,81 @@ export const actActions = (
 							"task",
 							"create",
 							args.id,
-							"--repo",
-							args.repo,
-							"--base",
-							args.base,
+							...(args.repo ? ["--repo", args.repo] : []),
+							...(args.base ? ["--base", args.base] : []),
 							"--description",
 							args.description,
-							...(investigation ? ["--purpose", "investigation"] : []),
+							...(kind === "multi-phase" ? ["--multi-phase"] : []),
+							...(kind === "investigation"
+								? ["--purpose", "investigation"]
+								: []),
 						],
 						run: task({
 							...options,
 							subcommand: "create",
 							args: [args.id],
 							...args,
-							purpose: investigation ? "investigation" : undefined,
+							multiPhase: kind === "multi-phase",
+							purpose: kind === "investigation" ? "investigation" : undefined,
 						}),
 						next: { taskId: args.id },
 					}),
 				),
 			),
+			action(
+				{
+					id: "epic-create",
+					label: "Create an epic",
+					blockedReason: needsRepository,
+					inputs: [
+						input("description", "Outcome", { multiline: true }),
+						input("id", "Epic ID"),
+						input("ticketUrl", "Ticket URL"),
+						input("repo", "Repository alias"),
+						input("ref", "Repository ref"),
+					],
+				},
+				{
+					id: "<id>",
+					description: "<description>",
+					ticketUrl: "<ticketUrl>",
+					repo: "<repo>",
+					ref: "<ref>",
+				},
+				(p) =>
+					Effect.gen(function* () {
+						const description = yield* p.text("Outcome")
+						return {
+							description,
+							id: yield* p.id("New epic ID", description),
+							ticketUrl: yield* p.text("Ticket URL"),
+							repo: yield* p.repository(),
+							ref: yield* p.text("Repository ref", "main"),
+						}
+					}),
+				(values) => ({
+					command: [
+						"agency",
+						"epic",
+						"create",
+						values.id,
+						"--ticket-url",
+						values.ticketUrl,
+						"--repo",
+						`${values.repo}:${values.ref}`,
+						"--description",
+						values.description,
+					],
+					run: epic({
+						...options,
+						subcommand: "create",
+						args: [values.id],
+						ticketUrl: values.ticketUrl,
+						repos: [`${values.repo}:${values.ref}`],
+						description: values.description,
+					}),
+				}),
+			),
 			...(["pull-request", "ref"] as const).map((sourceType) =>
 				action(
 					{
@@ -337,6 +694,157 @@ export const actActions = (
 					run: status({ ...options, statuses: ["working"] }),
 				},
 			),
+			immediate(
+				{
+					id: "ready-work",
+					label: "See ready work",
+					blockedReason: null,
+				},
+				{
+					command: ["agency", "status", "--ready"],
+					run: status({ ...options, ready: true }),
+				},
+			),
+			immediate(
+				{
+					id: "repo-setup",
+					label: "Set up declared repositories",
+					blockedReason: null,
+				},
+				{
+					command: ["agency", "repo", "setup", "--apply"],
+					run: repo({ ...options, subcommand: "setup", args: [], apply: true }),
+				},
+			),
+			...(["materialize", "fetch", "verify"] as const).map((operation) =>
+				action(
+					{
+						id: `repo-${operation}`,
+						label:
+							operation === "materialize"
+								? "Materialize a repository"
+								: operation === "fetch"
+									? "Fetch a repository"
+									: "Verify a repository",
+						blockedReason: needsRepository,
+						inputs: [input("repo", "Repository alias")],
+					},
+					"<repo>",
+					(p) => p.repository(),
+					(alias) => ({
+						command: ["agency", "repo", operation, alias],
+						run: repo({ ...options, subcommand: operation, args: [alias] }),
+					}),
+				),
+			),
+			action(
+				{
+					id: "repo-rename",
+					label: "Rename a repository alias",
+					blockedReason: needsRepository,
+					inputs: [
+						input("repo", "Repository alias"),
+						input("id", "New repository alias"),
+					],
+				},
+				{ repo: "<repo>", id: "<id>" },
+				(p) =>
+					Effect.gen(function* () {
+						return {
+							repo: yield* p.repository(),
+							id: yield* p.id("New repository alias", "repository"),
+						}
+					}),
+				({ repo: alias, id }) => ({
+					command: ["agency", "repo", "rename", alias, id],
+					run: repo({
+						...options,
+						subcommand: "rename",
+						args: [alias, id],
+					}),
+				}),
+			),
+			action(
+				{
+					id: "repo-remote",
+					label: "Update a repository remote",
+					blockedReason: needsRepository,
+					inputs: [
+						input("repo", "Repository alias"),
+						input("remote", "Remote URL"),
+					],
+				},
+				{ repo: "<repo>", remote: "<remote>" },
+				(p) =>
+					Effect.gen(function* () {
+						return {
+							repo: yield* p.repository(),
+							remote: yield* p.text("Portable remote URL"),
+						}
+					}),
+				({ repo: alias, remote }) => ({
+					command: ["agency", "repo", "remote", alias, remote],
+					run: repo({
+						...options,
+						subcommand: "remote",
+						args: [alias, remote],
+					}),
+				}),
+			),
+			...(["unlink", "remove"] as const).map((operation) =>
+				action(
+					{
+						id: `repo-${operation}`,
+						label:
+							operation === "unlink"
+								? "Unlink a local repository"
+								: "Remove a repository alias",
+						blockedReason: needsRepository,
+						inputs: [input("repo", "Repository alias")],
+					},
+					"<repo>",
+					(p) => p.repository(),
+					(alias) => ({
+						command: ["agency", "repo", operation, alias],
+						run: repo({ ...options, subcommand: operation, args: [alias] }),
+					}),
+				),
+			),
+			immediate(
+				{ id: "validate", label: "Validate workbase", blockedReason: null },
+				{
+					command: ["agency", "validate"],
+					run: validate(options),
+				},
+			),
+			immediate(
+				{ id: "doctor", label: "Diagnose workbase", blockedReason: null },
+				{ command: ["agency", "doctor"], run: doctor(options) },
+			),
+			immediate(
+				{
+					id: "sync-all",
+					label: "Refresh all Agency state",
+					blockedReason: null,
+				},
+				{ command: ["agency", "sync"], run: sync(options) },
+			),
+			...(["status", "sync"] as const).map((operation) =>
+				immediate(
+					{
+						id: `integration-${operation}`,
+						label:
+							operation === "status"
+								? "Check agent integration"
+								: "Update agent integration",
+						blockedReason: null,
+					},
+					{
+						command: ["agency", "integration", operation],
+						run: integration({ ...options, subcommand: operation }),
+					},
+				),
+			),
 		]
 
 	const target = taskTarget(node)
@@ -393,6 +901,14 @@ export const actActions = (
 		return target.phaseId ? phase(update) : task(update)
 	}
 	const workTarget = node.kind === "epic" ? { epicId: node.key } : target
+	const itemDirectory = join(
+		options.cwd ?? process.cwd(),
+		node.kind === "epic"
+			? `epics/${node.key}`
+			: target.phaseId
+				? `tasks/${target.taskId}/phases/${target.phaseId}`
+				: `tasks/${target.taskId}`,
+	)
 	const canWork =
 		node.readiness.ready ||
 		Boolean(
@@ -424,6 +940,22 @@ export const actActions = (
 				run: Effect.suspend(() => work({ ...options, ...workTarget })),
 			},
 		),
+		immediate(
+			details(
+				"push",
+				"Publish branch without a pull request",
+				noExecution ??
+					(parent && "review" in parent.data
+						? "Review tasks do not publish delivery branches"
+						: node.status !== "working"
+							? "Item must be working before publication"
+							: null),
+			),
+			{
+				command: ["agency", "--cwd", itemDirectory, "push"],
+				run: push({ ...options, cwd: itemDirectory }),
+			},
+		),
 		immediate(
 			details(
 				"pr",
@@ -450,6 +982,31 @@ export const actActions = (
 				run: prCreate({ ...options, ...target }),
 			},
 		),
+		immediate(
+			details(
+				"review-refresh",
+				"Refresh review source",
+				node.kind === "task" && "review" in node.data
+					? null
+					: "Select a review task",
+			),
+			{
+				command: [
+					"agency",
+					"review",
+					"refresh",
+					target.taskId,
+					"--if-revision",
+					node.data.sha256,
+				],
+				run: review({
+					...options,
+					subcommand: "refresh",
+					taskId: target.taskId,
+					ifRevision: node.data.sha256,
+				}),
+			},
+		),
 		...(["reopen", "drop"] as const).map((id) => {
 			const status = id === "reopen" ? "open" : "dropped"
 			return immediate(
@@ -481,6 +1038,61 @@ export const actActions = (
 				run: archive({ ...options, type: node.kind, args }),
 			},
 		),
+		action(
+			{
+				...details(
+					"task-create-in-epic",
+					"Create a task in this epic",
+					node.kind === "epic" ? needsRepository : "Select an epic",
+				),
+				inputs: [
+					input("description", "Outcome", { multiline: true }),
+					input("id", "Task ID"),
+					input("repo", "Repository alias"),
+					input("base", "Base branch"),
+				],
+			},
+			{
+				id: "<id>",
+				description: "<description>",
+				repo: "<repo>",
+				base: "<base>",
+			},
+			(p) =>
+				Effect.gen(function* () {
+					const description = yield* p.text("Outcome")
+					return {
+						description,
+						id: yield* p.id("New task ID", description),
+						repo: yield* p.repository(node.repositories[0]),
+						base: yield* p.text("Base branch", "main"),
+					}
+				}),
+			(values) => ({
+				command: [
+					"agency",
+					"task",
+					"create",
+					values.id,
+					"--epic",
+					node.key,
+					"--repo",
+					values.repo,
+					"--base",
+					values.base,
+					"--description",
+					values.description,
+				],
+				run: task({
+					...options,
+					subcommand: "create",
+					args: [values.id],
+					epic: node.key,
+					...values,
+				}),
+				next: { taskId: values.id },
+			}),
+		),
 		action(
 			{
 				...details(
@@ -688,14 +1300,172 @@ export const actActions = (
 				},
 			),
 		),
+		action(
+			{
+				...details("rename", "Rename item"),
+				inputs: [input("id", "New item ID")],
+			},
+			"<id>",
+			(p) =>
+				p.id(
+					`New ${node.kind} ID`,
+					node.kind === "phase" ? target.phaseId! : node.key,
+					node.kind === "phase" ? `${target.taskId}/` : "",
+				),
+			(id) => {
+				const command = [
+					"agency",
+					node.kind,
+					"rename",
+					...(node.kind === "phase"
+						? [target.taskId, target.phaseId!, id]
+						: [node.key, id]),
+					"--if-revision",
+					node.data.sha256,
+				]
+				const update = {
+					...options,
+					subcommand: "rename",
+					args:
+						node.kind === "phase"
+							? [target.taskId, target.phaseId!, id]
+							: [node.key, id],
+					ifRevision: node.data.sha256,
+				}
+				return {
+					command,
+					run:
+						node.kind === "epic"
+							? epic(update)
+							: node.kind === "phase"
+								? phase(update)
+								: task(update),
+				}
+			},
+		),
+		action(
+			{
+				...details(
+					"move-to-epic",
+					"Move task to an epic",
+					node.kind === "task" ? null : "Select a task",
+				),
+				inputs: [input("epic", "Epic ID")],
+			},
+			"<epic>",
+			(p) => p.text("Destination epic ID"),
+			(epicId) => ({
+				command: [
+					"agency",
+					"task",
+					"move",
+					target.taskId,
+					"--epic",
+					epicId,
+					"--if-revision",
+					node.data.sha256,
+				],
+				run: task({
+					...options,
+					subcommand: "move",
+					args: [target.taskId],
+					epic: epicId,
+					ifRevision: node.data.sha256,
+				}),
+			}),
+		),
+		immediate(
+			details(
+				"remove-from-epic",
+				"Remove task from its epic",
+				node.kind === "task" && node.data.epic
+					? null
+					: "Select a task that belongs to an epic",
+			),
+			{
+				command: [
+					"agency",
+					"task",
+					"move",
+					target.taskId,
+					"--no-epic",
+					"--if-revision",
+					node.data.sha256,
+				],
+				run: task({
+					...options,
+					subcommand: "move",
+					args: [target.taskId],
+					noEpic: true,
+					ifRevision: node.data.sha256,
+				}),
+			},
+		),
+		...(["add", "remove"] as const).map((operation) =>
+			action(
+				{
+					...details(
+						`dependency-${operation}`,
+						operation === "add" ? "Add dependency" : "Remove dependency",
+						node.kind === "phase"
+							? terminal
+								? "Phase is terminal"
+								: null
+							: node.kind === "task" && node.data.epic
+								? terminal
+									? "Task is terminal"
+									: null
+								: "Select a phase or a task in an epic",
+					),
+					inputs: [input("dependency", "Dependency ID")],
+				},
+				"<dependency>",
+				(p) =>
+					p.text(`${operation === "add" ? "Required" : "Current"} sibling ID`),
+				(dependency) => {
+					const command = [
+						"agency",
+						node.kind === "phase" ? "phase" : "task",
+						"dependency",
+						operation,
+						...args,
+						dependency,
+						"--if-revision",
+						node.data.sha256,
+					]
+					const update = {
+						...options,
+						subcommand: "dependency",
+						args: [operation, ...args, dependency],
+						ifRevision: node.data.sha256,
+					}
+					return {
+						command,
+						run: node.kind === "phase" ? phase(update) : task(update),
+					}
+				},
+			),
+		),
 	]
 }
 
 export const actionOutput = (action: ActAction, auto?: boolean) => {
-	const { id, label, blockedReason, preview, inputs = [] } = action
+	const {
+		id,
+		label,
+		description,
+		icon,
+		color,
+		blockedReason,
+		preview,
+		inputs = [],
+	} = action
 	return {
 		id,
 		label,
+		description,
+		icon,
+		color,
 		available: blockedReason === null,
 		blockedReason,
 		...(blockedReason

package/src/commands/act.ts

@@ -169,29 +169,18 @@ const entitySummary = (node: ActEntity) => ({
 	readiness: node.readiness,
 	revision: node.data.sha256,
 })
-const actionIcons: Record<string, string> = {
-	reopen: "󰑓",
-	drop: "󰅖",
-	complete: "󰄬",
-	sync: "󰑓",
-	"pr-ready": "󰄬",
-	"pr-close": "",
-}
 const actionChoices = (actions: readonly ActAction[]): Choice<string>[] =>
-	actions.map(({ id, label }) => {
-		const icon =
-			actionIcons[id] ??
-			actionGroups.find((group) =>
-				group.actions.some((action) => action === id),
-			)!.icon
-		const color =
-			id === "drop" || id === "pr-close" ? macchiato.red : macchiato.overlay1
+	actions.map(({ id, label, description, icon, color }) => {
 		return {
 			key: id,
 			value: id,
-			label: `${icon}  ${label}`,
-			plainLabel: label,
-			segments: [{ text: `${icon}  `, color }, { text: label }],
+			label: `${icon}  ${label} — ${description}`,
+			plainLabel: `${label} — ${description}`,
+			segments: [
+				{ text: `${icon}  `, color },
+				{ text: label },
+				{ text: ` — ${description}`, color: macchiato.overlay0 },
+			],
 		}
 	})
 
@@ -366,7 +355,7 @@ const actStep = (
 						? isPath
 							? pathEntityKey(root, path)
 							: `task:${options.directory}`
-						: undefined
+						: pathEntityKey(root, path)
 		let actionId = options.action
 		if (session && options.directory && isPath && !selectedKey && !actionId)
 			session.activateTab("workbase")
@@ -568,7 +557,7 @@ const actStep = (
 					graph.nodes
 						.filter((node) => node.kind === "repository")
 						.map((node) => node.key),
-					nodes.filter((node) => node.kind !== "epic").map((node) => node.key),
+					nodes.map((node) => node.key),
 					config.chooserCommand,
 				),
 			)