@markjaquith/agency 2.7.2 → 2.8.0

package/README.md

@@ -71,11 +71,12 @@ workbase/
             backend/
 ```
 
-Agency creates `AGENTS.md` and `.opencode/opencode.jsonc` during initialization
-and ensures they exist whenever the workbase is discovered. The OpenCode config
-grants external-directory access to task and epic references. Checksums in the
-generated files let newer Agency versions refresh unmodified content while
-preserving custom or edited files.
+Agency keeps discovery and other observational commands read-only. Run
+`agency integration status` to inspect `AGENTS.md` and
+`.opencode/opencode.jsonc`, then `agency integration sync` to create missing
+files or refresh checksum-safe managed files. The OpenCode config grants
+external-directory access to task and epic references. Customized files are
+reported but never overwritten.
 
 Repository metadata comes directly from Git under `repos/{alias}`. Workbase
 configuration may provide a custom writable-worktree creation command.
@@ -242,6 +243,8 @@ agency pr create refresh-copy
 agency init [path] [--json]
 agency workbase add <path> [--json]
 agency workbase list [--json]
+agency integration status [--json]
+agency integration sync [--json]
 agency repo add <alias> <remote> [--json]
 agency repo link <alias> <path> [--json]
 agency repo list [--json]
@@ -253,7 +256,8 @@ Registered workbases are stored in
 repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
-repository mutations, entity creation/list/show, status, validation, and PR creation.
+integration inspection/sync, repository mutations, entity creation/list/show,
+status, validation, and PR creation.
 
 ### Epics
 
@@ -270,7 +274,7 @@ back-reference.
 ### Tasks
 
 Create a task interactively. Text prompts identify optional values, and known
-choices use fzf:
+choices use fzf. This command requires a TTY and fails with `--no-input`:
 
 ```text
 agency task new [id]
@@ -285,6 +289,8 @@ agency task create <id> --repo <alias>
 ```
 
 The branch defaults to `task/<id>` and the base defaults to `main`.
+`task create` is always noninteractive and requires `--repo` for a single-phase
+task. Use it instead of `task new` in scripts and agent workflows.
 
 Create a multi-phase task container:
 
@@ -293,6 +299,13 @@ agency task create <id> --multi-phase
   [--ticket-url <url>] [--description <text>] [--epic <id>] [--json]
 ```
 
+### Noninteractive Use
+
+Agency never prompts when `--no-input` is set or stdin/stderr are not TTYs.
+Commands with explicit inputs continue normally. `task new` fails immediately;
+`work` requires an explicit directory, task ID, or `--epic` and must run from a
+workbase; `validate` requires an explicit path or must run from a workbase.
+
 Inspect tasks:
 
 ```text

package/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
-import { parseArgs } from "util"
 import { Effect, Either, Layer } from "effect"
+import { parseCli } from "./src/cli-parser"
 import { init, help as initHelp } from "./src/commands/init"
 import { task, help as taskHelp } from "./src/commands/task"
 import { pr, help as prHelp } from "./src/commands/pr"
@@ -13,6 +13,10 @@ import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
 import { archive, help as archiveHelp } from "./src/commands/archive"
 import { workbase, help as workbaseHelp } from "./src/commands/workbase"
+import {
+	integration,
+	help as integrationHelp,
+} from "./src/commands/integration"
 import type { Command } from "./src/types"
 import { FileSystemService } from "./src/services/FileSystemService"
 import { WorkbaseService } from "./src/services/WorkbaseService"
@@ -23,6 +27,7 @@ import { PhaseService } from "./src/services/PhaseService"
 import { WorktreeService } from "./src/services/WorktreeService"
 import { PullRequestService } from "./src/services/PullRequestService"
 import { ArchiveService } from "./src/services/ArchiveService"
+import { IntegrationService } from "./src/services/IntegrationService"
 
 // Create CLI layer with all services
 const CliLayer = Layer.mergeAll(
@@ -35,6 +40,7 @@ const CliLayer = Layer.mergeAll(
 	WorktreeService.Default,
 	PullRequestService.Default,
 	ArchiveService.Default,
+	IntegrationService.Default,
 )
 
 /**
@@ -191,6 +197,22 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	integration: {
+		run: async (args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(integrationHelp)
+				return
+			}
+			await runCommand(
+				integration({
+					subcommand: args[0],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 	repo: {
 		run: async (args: string[], options: Record<string, any>) => {
 			if (options.help) {
@@ -229,6 +251,7 @@ const commands: Record<string, Command> = {
 					json: options.json,
 					silent: options.silent,
 					verbose: options.verbose,
+					inputAllowed: options.inputAllowed,
 				}),
 			)
 		},
@@ -239,12 +262,6 @@ const commands: Record<string, Command> = {
 				console.log(workHelp)
 				return
 			}
-			if (args.length > 1) {
-				throw new Error(
-					"Usage: agency work [<directory-or-task-id> | --epic <epic-id>]",
-				)
-			}
-
 			await runCommand(
 				work({
 					directory: args[0],
@@ -253,6 +270,7 @@ const commands: Record<string, Command> = {
 					verbose: options.verbose,
 					opencode: options.opencode,
 					claude: options.claude,
+					inputAllowed: options.inputAllowed,
 				}),
 			)
 		},
@@ -284,6 +302,7 @@ const commands: Record<string, Command> = {
 					silent: options.silent,
 					verbose: options.verbose,
 					json: options.json,
+					inputAllowed: options.inputAllowed,
 				}),
 			)
 		},
@@ -299,6 +318,7 @@ Usage: agency <command> [options]
 Commands:
   init [path]            Initialize an Agency workbase
   workbase <subcommand>  Manage registered workbases
+  integration <command> Inspect or sync managed integration files
   epic <subcommand>      Manage epics
   phase <subcommand>     Manage task phases
   archive <type>         Archive a work item
@@ -314,6 +334,7 @@ Global Options:
   -V, --version          Show version number
   -s, --silent           Suppress output messages
   -v, --verbose          Show verbose output including detailed debugging info
+  --no-input             Never open an interactive prompt or selector
 
 Examples:
   agency init                         # Initialize the current directory
@@ -327,29 +348,7 @@ For more information about a command, run:
 
 try {
 	const args = process.argv.slice(2)
-	const { values, positionals } = parseArgs({
-		args,
-		options: {
-			help: {
-				type: "boolean",
-				short: "h",
-			},
-			version: {
-				type: "boolean",
-				short: "V",
-			},
-			silent: {
-				type: "boolean",
-				short: "s",
-			},
-			verbose: {
-				type: "boolean",
-				short: "v",
-			},
-		},
-		strict: false,
-		allowPositionals: true,
-	})
+	const { commandName, args: commandArgs, values } = parseCli(args)
 
 	// Handle global flags
 	if (values.version) {
@@ -358,80 +357,16 @@ try {
 	}
 
 	// Get command
-	const commandName = positionals[0]
-
 	// Show help if no command
 	if (!commandName) {
 		showMainHelp()
 		process.exit(values.help ? 0 : 1)
 	}
 
-	// Check if command exists
-	const command = commands[commandName]
-	if (!command) {
-		console.error(`Error: Unknown command '${commandName}'`)
-		console.error("\nRun 'agency --help' for usage information.")
-		process.exit(1)
-	}
-
-	const commandIndex = args.indexOf(commandName)
-	const commandArgs = [
-		...args.slice(0, commandIndex),
-		...args.slice(commandIndex + 1),
-	]
-	const { values: cmdValues, positionals: cmdPositionals } = parseArgs({
-		args: commandArgs,
-		options: {
-			help: {
-				type: "boolean",
-				short: "h",
-			},
-			silent: {
-				type: "boolean",
-				short: "s",
-			},
-			verbose: {
-				type: "boolean",
-				short: "v",
-			},
-			branch: {
-				type: "string",
-			},
-			json: {
-				type: "boolean",
-			},
-			"ticket-url": {
-				type: "string",
-			},
-			description: {
-				type: "string",
-			},
-			repo: {
-				type: "string",
-				multiple: true,
-			},
-			reference: {
-				type: "string",
-				multiple: true,
-			},
-			epic: { type: "string" },
-			base: { type: "string" },
-			"multi-phase": { type: "boolean" },
-			"depends-on": { type: "string", multiple: true },
-			"first-phase": { type: "string" },
-			draft: { type: "boolean" },
-			opencode: {
-				type: "boolean",
-			},
-			claude: {
-				type: "boolean",
-			},
-		},
-		strict: false,
-		allowPositionals: true,
-	})
-
-	await command.run(cmdPositionals, cmdValues)
+	const command = commands[commandName]!
+	const inputAllowed =
+		!values["no-input"] && Boolean(process.stdin.isTTY && process.stderr.isTTY)
+	await command.run(commandArgs, { ...values, inputAllowed })
 } catch (error) {
 	if (error instanceof Error) {
 		let message = error.message

package/package.json

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

package/skills/agency/SKILL.md

@@ -39,6 +39,7 @@ From anywhere beneath a workbase, run:
 ```bash
 agency status --json
 agency validate --json
+agency integration status --json
 agency repo list --json
 agency epic list --json
 agency task list --json
@@ -56,6 +57,7 @@ If no workbase is found, do not initialize one without user intent. When asked:
 
 ```bash
 agency init [path]
+agency integration sync
 ```
 
 Register known workbases so `agency work` can select one when run elsewhere:
@@ -108,7 +110,9 @@ Epic task ordering and dependencies live in `EPIC.md`. Creating a task with
 ## Create Single-Phase Tasks
 
 For guided creation, run `agency task new`. It prompts for text input, uses fzf
-for known choices, and allows optional inputs to be skipped.
+for known choices, and allows optional inputs to be skipped. It requires a TTY
+and fails when `--no-input` is set. `task create` never prompts and is the command
+to use from agents and scripts.
 
 ```bash
 agency task create <id> \
@@ -241,6 +245,7 @@ validation errors before materializing worktrees or creating PRs. Validation
 checks schemas, aliases, backlinks, phase directories, duplicate references,
 duplicate writable branch ownership, unknown dependencies, and dependency cycles.
 Outside a workbase, omitting path opens the registered-workbase picker.
+With `--no-input` or without a TTY, pass a path or run from a workbase instead.
 
 ## Worktrees And Agent Launch
 
@@ -256,6 +261,8 @@ replaces the current process with the selected agent. With no directory it opens
 an `fzf` picker containing the workbase hierarchy. Pass `.`, or another
 directory, to infer the nearest epic, task, or phase.
 Outside a workbase, it first opens a picker containing registered workbases.
+With `--no-input` or without a TTY, run from a workbase and provide an explicit
+directory, task ID, or `--epic` so no picker is needed.
 
 Epic and multi-phase task targets are orchestration sessions launched beside
 their documents. Single-phase tasks and phases are execution sessions launched

package/src/cli-parser.test.ts

@@ -0,0 +1,205 @@
+import { describe, expect, test } from "bun:test"
+import { parseCli } from "./cli-parser"
+
+const expectUsageError = (args: string[], usage: string) => {
+	expect(() => parseCli(args)).toThrow(`Usage: ${usage}`)
+}
+
+describe("strict CLI parsing", () => {
+	test("rejects misspelled and command-inapplicable options", () => {
+		expectUsageError(["task", "list", "--josn"], "agency task")
+		expectUsageError(
+			["task", "list", "--repo", "agency"],
+			"agency task list [--json]",
+		)
+		expectUsageError(["status", "--draft"], "agency status [--json]")
+	})
+
+	test("rejects duplicate scalar, boolean, and single-value multiple options", () => {
+		for (const args of [
+			["status", "--json", "--json"],
+			["task", "create", "example", "--repo", "one", "--repo", "two"],
+			[
+				"task",
+				"create",
+				"example",
+				"--repo",
+				"one",
+				"--base",
+				"a",
+				"--base",
+				"b",
+			],
+			["status", "-s", "--silent"],
+		]) {
+			expect(() => parseCli(args)).toThrow("may only be specified once")
+		}
+	})
+
+	test("preserves explicitly repeatable options", () => {
+		expect(
+			parseCli([
+				"epic",
+				"create",
+				"delivery",
+				"--ticket-url",
+				"https://example.com",
+				"--repo",
+				"one:main",
+				"--repo",
+				"two:main",
+			]).values.repo,
+		).toEqual(["one:main", "two:main"])
+		expect(
+			parseCli([
+				"phase",
+				"create",
+				"task",
+				"phase",
+				"--repo",
+				"one",
+				"--branch",
+				"feature",
+				"--base",
+				"main",
+				"--reference",
+				"two:main",
+				"--reference",
+				"three:main",
+				"--depends-on",
+				"first",
+				"--depends-on",
+				"second",
+			]).values,
+		).toMatchObject({
+			reference: ["two:main", "three:main"],
+			"depends-on": ["first", "second"],
+		})
+	})
+
+	test("enforces exact maximum positional arity for every leaf command", () => {
+		for (const [args, usage] of [
+			[["init", "one", "two"], "agency init"],
+			[["workbase", "add", "one", "two"], "agency workbase add"],
+			[["workbase", "list", "extra"], "agency workbase list"],
+			[["integration", "status", "extra"], "agency integration status"],
+			[["integration", "sync", "extra"], "agency integration sync"],
+			[["repo", "add", "a", "b", "extra"], "agency repo add"],
+			[["repo", "link", "a", "b", "extra"], "agency repo link"],
+			[["repo", "list", "extra"], "agency repo list"],
+			[
+				[
+					"epic",
+					"create",
+					"one",
+					"two",
+					"--ticket-url",
+					"url",
+					"--repo",
+					"repo:main",
+				],
+				"agency epic create",
+			],
+			[["epic", "list", "extra"], "agency epic list"],
+			[["epic", "show", "one", "two"], "agency epic show"],
+			[["task", "new", "one", "two"], "agency task new"],
+			[
+				["task", "create", "one", "two", "--repo", "repo"],
+				"agency task create",
+			],
+			[["task", "list", "extra"], "agency task list"],
+			[["task", "show", "one", "two"], "agency task show"],
+			[["task", "status", "one", "open", "extra"], "agency task status"],
+			[
+				[
+					"phase",
+					"create",
+					"task",
+					"phase",
+					"extra",
+					"--repo",
+					"repo",
+					"--branch",
+					"branch",
+					"--base",
+					"main",
+				],
+				"agency phase create",
+			],
+			[["phase", "list", "one", "two"], "agency phase list"],
+			[["phase", "show", "one", "two", "three"], "agency phase show"],
+			[
+				["phase", "status", "one", "two", "open", "extra"],
+				"agency phase status",
+			],
+			[["archive", "epic", "one", "two"], "agency archive epic"],
+			[["archive", "task", "one", "two"], "agency archive task"],
+			[["archive", "phase", "one", "two", "three"], "agency archive phase"],
+			[["work", "one", "two"], "agency work"],
+			[["pr", "create", "one", "two", "three"], "agency pr create"],
+			[["status", "extra"], "agency status"],
+			[["validate", "one", "two"], "agency validate"],
+		] as const) {
+			expectUsageError([...args], usage)
+		}
+	})
+
+	test("reports unknown subcommands with parent usage", () => {
+		expect(() => parseCli(["task", "crate"])).toThrow(
+			"Unknown subcommand 'crate'",
+		)
+		expectUsageError(
+			["task", "crate"],
+			"agency task <new|create|list|show|status>",
+		)
+	})
+
+	test("rejects required-option omissions and explicit conflicts", () => {
+		expect(() => parseCli(["task", "create", "example"])).toThrow(
+			"--repo' is required",
+		)
+		for (const option of ["repo", "reference", "branch", "base"] as const) {
+			const value = option === "reference" ? "other:main" : "value"
+			expect(() =>
+				parseCli([
+					"task",
+					"create",
+					"example",
+					"--multi-phase",
+					`--${option}`,
+					value,
+				]),
+			).toThrow("cannot be combined")
+		}
+		expect(() =>
+			parseCli(["task", "new", "example", "--multi-phase", "--repo", "repo"]),
+		).toThrow("cannot be combined")
+		expect(() => parseCli(["work", "--opencode", "--claude"])).toThrow(
+			"cannot be combined",
+		)
+		expect(() => parseCli(["work", "task", "--epic", "epic"])).toThrow(
+			"cannot be combined",
+		)
+		expect(() => parseCli(["status", "--silent", "--verbose"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
+	test("accepts the global interaction control on every command", () => {
+		expect(parseCli(["--no-input", "task", "new"]).values["no-input"]).toBe(
+			true,
+		)
+		expect(parseCli(["work", "--no-input"]).values["no-input"]).toBe(true)
+		expect(parseCli(["validate", "--no-input"]).values["no-input"]).toBe(true)
+		expect(parseCli(["status", "--no-input"]).values["no-input"]).toBe(true)
+		expect(
+			parseCli(["task", "create", "example", "--repo", "repo", "--no-input"])
+				.values["no-input"],
+		).toBe(true)
+	})
+
+	test("accepts grouped global short options before a command", () => {
+		const parsed = parseCli(["-sh", "task"])
+		expect(parsed.values).toMatchObject({ silent: true, help: true })
+	})
+})