@clipboard-health/groundcrew 4.28.0 → 4.30.0

package/README.md

@@ -150,35 +150,9 @@ There is no `linear` config block. Groundcrew reads `GROUNDCREW_LINEAR_API_KEY`
 - [Credentials](./docs/credentials.md): Linear API keys, 1Password, build secrets, and `preLaunch`.
 - [Prepare worktree hooks](./docs/setup-hooks.md): `.groundcrew/config.json` `hooks.prepareWorktree` for per-repo dependency setup.
 - [Task sources](./docs/task-sources.md): custom shell/Jira/local-plan adapters.
+- [Development](./docs/development.md): local source workflow and README/demo asset regeneration.
 - [Troubleshooting](./docs/troubleshooting.md): common operational pitfalls and fixes.
 
-## Development
-
-Clone the repo and run the CLI from TypeScript source:
-
-```bash
-cd ~/dev/c/groundcrew
-node --run crew -- doctor
-
-# With 1Password for GROUNDCREW_LINEAR_API_KEY:
-node --run crew:op -- run --watch
-```
-
-Both forms discover config through cosmiconfig. Source edits in `src/**` are picked up on the next invocation. Requires Node >= 24.
-
-Regenerate the README demo with VHS:
-
-```bash
-./static/render-demo.sh
-```
-
-Regenerate the Slack bot avatar (also used as the emoji upload; Slack scales it down) after editing the mark:
-
-```bash
-sed 's/width="120" height="120"/width="512" height="512"/' static/groundcrew-mark.svg > /tmp/mark512.svg
-sips -s format png /tmp/mark512.svg --out static/groundcrew-avatar.png
-```
-
 ## License
 
 [MIT](./LICENSE)

package/crew.config.example.ts

@@ -120,6 +120,9 @@ export default {
   //   // `${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/initial-prompt.md`.
   //   // If you uncomment this, also uncomment the readFileSync import above.
   //   initial: readFileSync(new URL("./initial-prompt.md", import.meta.url), "utf8"),
+  //   // Or, instead of `initial`, point at a file (also works in crew.config.json).
+  //   // Resolved relative to this config's directory; `~` and absolute paths work.
+  //   // promptFile: "initial-prompt.md",
   // },
   //
   // // Terminal session manager. "auto" picks cmux when on PATH, else tmux.

package/dist/lib/adapters/shell/factory.d.ts

@@ -1,7 +1,7 @@
 /**
  * Shell-adapter `TaskSource` factory. Wires `invokeShellCommand` to the
- * four TaskSource operations and applies the ShellIssue Zod schema for
- * runtime validation of script stdout.
+ * TaskSource operations and applies the ShellIssue Zod schema for runtime
+ * validation of script stdout.
  *
  * Fallback behavior for omitted commands:
  *  - `verify` absent → no-op (always succeeds).
@@ -13,6 +13,10 @@
  *  - `markInProgress` absent → silent no-op.
  *  - `markInReview` absent → reports unsupported.
  *  - `markDone` absent → reports unsupported.
+ *  - `createTask` absent → method omitted entirely (source reports it cannot
+ *    create tasks; the optional method is attached only when configured).
+ *  - `validate` absent → method omitted entirely (same capability-detection
+ *    contract as createTask).
  *  - `fetch` is required by the Zod schema.
  */
 import type { AdapterContext } from "../../adapterDefinition.ts";

package/dist/lib/adapters/shell/factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAGL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAEhB,MAAM,aAAa,CAAC;AAkErB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,UAAU,CAyHZ"}
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAIL,KAAK,KAAK,IAAI,cAAc,EAG5B,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,UAAU,EAGhB,MAAM,aAAa,CAAC;AAyErB,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAuB3F;AA8BD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,cAAc,GACvB,UAAU,CA6LZ"}

package/dist/lib/adapters/shell/factory.js

@@ -1,7 +1,7 @@
 /**
  * Shell-adapter `TaskSource` factory. Wires `invokeShellCommand` to the
- * four TaskSource operations and applies the ShellIssue Zod schema for
- * runtime validation of script stdout.
+ * TaskSource operations and applies the ShellIssue Zod schema for runtime
+ * validation of script stdout.
  *
  * Fallback behavior for omitted commands:
  *  - `verify` absent → no-op (always succeeds).
@@ -13,12 +13,16 @@
  *  - `markInProgress` absent → silent no-op.
  *  - `markInReview` absent → reports unsupported.
  *  - `markDone` absent → reports unsupported.
+ *  - `createTask` absent → method omitted entirely (source reports it cannot
+ *    create tasks; the optional method is attached only when configured).
+ *  - `validate` absent → method omitted entirely (same capability-detection
+ *    contract as createTask).
  *  - `fetch` is required by the Zod schema.
  */
 import { toCanonicalId, } from "../../taskSource.js";
-import { writeError } from "../../util.js";
+import { errorMessage, writeError } from "../../util.js";
 import { invokeShellCommand } from "./invoke.js";
-import { shellFetchOutputSchema, shellIssueSchema, } from "./schema.js";
+import { shellFetchOutputSchema, shellIssueSchema, shellValidateOutputSchema, } from "./schema.js";
 const DEFAULT_TIMEOUTS = {
     verify: 10_000,
     listTasks: 30_000,
@@ -26,15 +30,20 @@ const DEFAULT_TIMEOUTS = {
     markInProgress: 10_000,
     markInReview: 10_000,
     markDone: 10_000,
+    createTask: 30_000,
+    validate: 30_000,
 };
 function mergeTimeouts(overrides) {
+    const o = overrides ?? {};
     return {
-        verify: overrides?.verify ?? DEFAULT_TIMEOUTS.verify,
-        listTasks: overrides?.listTasks ?? overrides?.fetch ?? DEFAULT_TIMEOUTS.listTasks,
-        getTask: overrides?.getTask ?? overrides?.resolveOne ?? DEFAULT_TIMEOUTS.getTask,
-        markInProgress: overrides?.markInProgress ?? DEFAULT_TIMEOUTS.markInProgress,
-        markInReview: overrides?.markInReview ?? DEFAULT_TIMEOUTS.markInReview,
-        markDone: overrides?.markDone ?? DEFAULT_TIMEOUTS.markDone,
+        verify: o.verify ?? DEFAULT_TIMEOUTS.verify,
+        listTasks: o.listTasks ?? o.fetch ?? DEFAULT_TIMEOUTS.listTasks,
+        getTask: o.getTask ?? o.resolveOne ?? DEFAULT_TIMEOUTS.getTask,
+        markInProgress: o.markInProgress ?? DEFAULT_TIMEOUTS.markInProgress,
+        markInReview: o.markInReview ?? DEFAULT_TIMEOUTS.markInReview,
+        markDone: o.markDone ?? DEFAULT_TIMEOUTS.markDone,
+        createTask: o.createTask ?? DEFAULT_TIMEOUTS.createTask,
+        validate: o.validate ?? DEFAULT_TIMEOUTS.validate,
     };
 }
 function warnDuplicate(sourceName, preferred, legacy) {
@@ -85,6 +94,33 @@ export function toCanonicalIssue(shellIssue, sourceName) {
         sourceRef: shellIssue.sourceRef,
     };
 }
+/**
+ * Flatten a CreateTaskInput into the `${...}` substitution map the createTask
+ * script receives. Every key is always present — absent optionals become an
+ * empty string — so no placeholder is ever left literally in the command.
+ * List fields are comma-joined into a single value.
+ */
+function createTaskSubstitutions(input) {
+    return {
+        title: input.title,
+        agent: input.agent,
+        // Exposed under both `repo` (short form) and `repository` (matches the
+        // CreateTaskInput field name) so either placeholder resolves.
+        repo: input.repository ?? "",
+        repository: input.repository ?? "",
+        team: input.team ?? "",
+        id: input.id ?? "",
+        priority: input.priority ?? "",
+        due: input.due ?? "",
+        recurrence: input.recurrence ?? "",
+        promptFile: input.promptFile ?? "",
+        description: input.description ?? "",
+        edit: input.edit ? "true" : "",
+        projects: input.projects.join(","),
+        contexts: input.contexts.join(","),
+        dependencies: input.dependencies.join(","),
+    };
+}
 export function createShellTaskSource(config, _context) {
     const sourceName = config.name;
     const timeouts = mergeTimeouts(config.timeouts);
@@ -149,7 +185,7 @@ export function createShellTaskSource(config, _context) {
             sourceName,
         });
     }
-    return {
+    const source = {
         name: sourceName,
         async verify() {
             const verifyCommand = config.commands.verify;
@@ -198,4 +234,66 @@ export function createShellTaskSource(config, _context) {
             return { outcome: "applied" };
         },
     };
+    // createTask / validate are attached only when their command is configured.
+    // Capability detection keys off `source.createTask === undefined` /
+    // `source.validate === undefined`, so a slot left unset must leave the
+    // method genuinely absent rather than present-but-failing.
+    const createTaskCommand = config.commands.createTask;
+    if (createTaskCommand !== undefined) {
+        source.createTask = async (input) => {
+            const { stdout, exitCode } = await invokeShellCommand({
+                command: createTaskCommand,
+                timeoutMs: timeouts.createTask,
+                cwd: config.cwd,
+                env: config.env,
+                substitutions: createTaskSubstitutions(input),
+                sourceName,
+            });
+            // invokeShellCommand resolves (does not throw) on exit 3 — its "not
+            // found" sentinel for lookups. Creation has no not-found concept, so any
+            // nonzero exit is a failure: surface it rather than parse partial output.
+            if (exitCode === 3) {
+                throw new Error(`shell source "${sourceName}" createTask command exited 3 (not-found); task creation cannot signal not-found`);
+            }
+            const trimmed = stdout.trim();
+            if (trimmed.length === 0) {
+                throw new Error(`shell source "${sourceName}" createTask command produced no output (expected one ShellIssue JSON)`);
+            }
+            const parsed = shellIssueSchema.parse(JSON.parse(trimmed));
+            return toCanonicalIssue(parsed, sourceName);
+        };
+    }
+    const validateCommand = config.commands.validate;
+    if (validateCommand !== undefined) {
+        source.validate = async () => {
+            try {
+                const { stdout, exitCode } = await invokeShellCommand({
+                    command: validateCommand,
+                    timeoutMs: timeouts.validate,
+                    cwd: config.cwd,
+                    env: config.env,
+                    sourceName,
+                });
+                // exit 3 is invoke's lookup "not found" sentinel; for validation it is
+                // not a meaningful success, so surface it as a failure (and validate
+                // never throws — return the failure as an error string).
+                if (exitCode === 3) {
+                    return [
+                        `shell source "${sourceName}" validate command exited 3 (not-found); treating as a validation failure`,
+                    ];
+                }
+                const trimmed = stdout.trim();
+                if (trimmed.length === 0) {
+                    return [];
+                }
+                return shellValidateOutputSchema.parse(JSON.parse(trimmed));
+            }
+            catch (error) {
+                // Contract: validate() never throws — fold a nonzero exit, timeout,
+                // malformed JSON, or wrong-shape payload into a single error string.
+                return [`shell source "${sourceName}" validate command failed: ${errorMessage(error)}`];
+            }
+        };
+    }
+    return source;
 }

package/dist/lib/adapters/shell/schema.d.ts

@@ -80,6 +80,12 @@ export declare const shellFetchOutputSchema: z.ZodArray<z.ZodObject<{
     url: z.ZodOptional<z.ZodURL>;
     sourceRef: z.ZodUnknown;
 }, z.core.$strip>>;
+/**
+ * Shape a `commands.validate` script must emit on stdout: a JSON array of
+ * human-readable error strings. An empty array (or empty stdout, handled by
+ * the factory) means "no problems found".
+ */
+export declare const shellValidateOutputSchema: z.ZodArray<z.ZodString>;
 export declare const shellAdapterConfigSchema: z.ZodObject<{
     kind: z.ZodLiteral<"shell">;
     name: z.ZodString;
@@ -92,6 +98,8 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         markInProgress: z.ZodOptional<z.ZodString>;
         markInReview: z.ZodOptional<z.ZodString>;
         markDone: z.ZodOptional<z.ZodString>;
+        createTask: z.ZodOptional<z.ZodString>;
+        validate: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     cwd: z.ZodOptional<z.ZodString>;
     timeouts: z.ZodOptional<z.ZodObject<{
@@ -103,6 +111,8 @@ export declare const shellAdapterConfigSchema: z.ZodObject<{
         markInProgress: z.ZodOptional<z.ZodNumber>;
         markInReview: z.ZodOptional<z.ZodNumber>;
         markDone: z.ZodOptional<z.ZodNumber>;
+        createTask: z.ZodOptional<z.ZodNumber>;
+        validate: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;

package/dist/lib/adapters/shell/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;iBAiDnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/lib/adapters/shell/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAYxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAiB3B,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA4B,CAAC;AAEhE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,yBAAsB,CAAC;AAE7D,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkEnC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC"}

package/dist/lib/adapters/shell/schema.js

@@ -36,6 +36,12 @@ export const shellIssueSchema = z.object({
     sourceRef: z.unknown(),
 });
 export const shellFetchOutputSchema = z.array(shellIssueSchema);
+/**
+ * Shape a `commands.validate` script must emit on stdout: a JSON array of
+ * human-readable error strings. An empty array (or empty stdout, handled by
+ * the factory) means "no problems found".
+ */
+export const shellValidateOutputSchema = z.array(z.string());
 export const shellAdapterConfigSchema = z.object({
     kind: z.literal("shell"),
     name: z
@@ -55,6 +61,19 @@ export const shellAdapterConfigSchema = z.object({
         markInProgress: z.string().optional(),
         markInReview: z.string().optional(),
         markDone: z.string().optional(),
+        /**
+         * Create a task from a `CreateTaskInput`. Receives the input fields as
+         * shell-quoted `${...}` placeholders (see factory) and must print one
+         * ShellIssue JSON on stdout. Omitting it leaves the source unable to
+         * create tasks.
+         */
+        createTask: z.string().optional(),
+        /**
+         * Validate task content. Must print a JSON array of error strings on
+         * stdout (empty array / empty stdout = no problems). Omitting it leaves
+         * the source unable to validate.
+         */
+        validate: z.string().optional(),
     })
         .superRefine((commands, ctx) => {
         if (commands.listTasks === undefined && commands.fetch === undefined) {
@@ -82,6 +101,10 @@ export const shellAdapterConfigSchema = z.object({
         markInProgress: z.number().int().positive().optional(),
         markInReview: z.number().int().positive().optional(),
         markDone: z.number().int().positive().optional(),
+        /** Timeout for the createTask command. */
+        createTask: z.number().int().positive().optional(),
+        /** Timeout for the validate command. */
+        validate: z.number().int().positive().optional(),
     })
         .optional(),
     env: z.record(z.string(), z.string()).optional(),

package/dist/lib/config.d.ts

@@ -193,7 +193,14 @@ export interface Config {
         definitions?: Record<string, UserAgentDefinition>;
     };
     prompts?: {
+        /** Inline initial prompt. Mutually exclusive with `promptFile`. */
         initial?: string;
+        /**
+         * Path to a UTF-8 file whose contents become the initial prompt. Resolved
+         * relative to the config file's directory; `~` is expanded; absolute paths
+         * are used as-is. Mutually exclusive with `initial`.
+         */
+        promptFile?: string;
     };
     /**
      * Terminal session manager that hosts agent processes. Defaults to

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAO1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,mBAAmB,GAAG,kBAAkB,GAAG,oBAAoB,CAAC;AAE3F,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAQ,CAAC;AAE/B;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvE,eAAO,MAAM,uBAAuB,EAAE,SAAS,oBAAoB,EAKzD,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAE/D;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,MAAM,CAAC;AAEtD,eAAO,MAAM,qBAAqB,EAAE,SAAS,kBAAkB,EAMrD,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE;QACN,QAAQ,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACjD,CAAC;IACF;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,KAAK,SAAS,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAC/D,KAAK,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,GAAG;IAC1E,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AACF,KAAK,mBAAmB,GAAG,0BAA0B,CAAC;AAEtD;;;;;;;;;GASG;AACH;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,MAAM;IACrB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB;;;;WAIG;QACH,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB;;;WAGG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,iBAAiB,EAAE,CAAC,MAAM,GAAG,eAAe,CAAC,EAAE,CAAC;KACjD,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,YAAY,CAAC;KACtB,CAAC;IACF,YAAY,CAAC,EAAE;QACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,wBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,sBAAsB,CAAC,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;;;;;WAKG;QACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;KACnD,CAAC;IACF,OAAO,CAAC,EAAE;QACR,mEAAmE;QACnE,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB;;;;WAIG;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF;;;;OAIG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,kBAAkB,CAAC;KAC7B,CAAC;IACF,OAAO,CAAC,EAAE;QACR;;;;;WAKG;QACH,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;OAKG;IACH,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,GAAG,EAAE;QACH,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,SAAS,EAAE;QACT,UAAU,EAAE,MAAM,CAAC;QACnB,4DAA4D;QAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,gFAAgF;QAChF,iBAAiB,EAAE,MAAM,EAAE,CAAC;QAC5B,8EAA8E;QAC9E,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACzC,CAAC;IACF,QAAQ,EAAE;QACR,KAAK,EAAE,YAAY,CAAC;KACrB,CAAC;IACF,YAAY,EAAE;QACZ,iBAAiB,EAAE,MAAM,CAAC;QAC1B,wBAAwB,EAAE,MAAM,CAAC;QACjC,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,MAAM,EAAE;QACN,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;KAC9C,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF;;;OAGG;IACH,aAAa,EAAE,oBAAoB,CAAC;IACpC;;;;OAIG;IACH,KAAK,EAAE;QACL,MAAM,EAAE,kBAAkB,CAAC;KAC5B,CAAC;IACF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAE9D;AAED,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC;IACjC,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;CAChC;AA8MD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,eAAe,EAAE,cAAc,CAAC,GAAG,OAAO,CAE1F;AA6FD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,CAAC,EACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAKT;AAkjBD,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CA2B5E;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAGpE"}

package/dist/lib/config.js

@@ -1,5 +1,5 @@
 import { __rewriteRelativeImportExtension } from "tslib";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { cosmiconfig } from "cosmiconfig";
@@ -518,7 +518,32 @@ function normalizeWorkspace(workspace) {
         ...(Object.keys(repositoryDirs).length === 0 ? {} : { repositoryDirs }),
     };
 }
-function applyDefaults(user) {
+/**
+ * Resolve the initial prompt from the user's `prompts` block. `promptFile` and
+ * `initial` are mutually exclusive; when neither is set the built-in default is
+ * used. A `promptFile` is resolved relative to the config file's directory
+ * (matching the `.ts` `import.meta.url` behavior), with `~` expanded and
+ * absolute paths used as-is, then read at load time.
+ */
+function resolveInitialPrompt(prompts, configDir) {
+    const { initial, promptFile } = prompts ?? {};
+    if (initial !== undefined && promptFile !== undefined) {
+        fail("prompts: set either `initial` or `promptFile`, not both");
+    }
+    if (promptFile !== undefined) {
+        requireString(promptFile, "prompts.promptFile");
+        const expanded = expandHome(promptFile);
+        const resolved = path.isAbsolute(expanded) ? expanded : path.resolve(configDir, expanded);
+        try {
+            return readFileSync(resolved, "utf8");
+        }
+        catch (error) {
+            fail(`prompts.promptFile could not be read at ${resolved}: ${String(error)}`);
+        }
+    }
+    return initial ?? DEFAULT_PROMPT_INITIAL;
+}
+function applyDefaults(user, configDir) {
     // Guard the top-level shape before reading nested fields, so a
     // malformed runtime config produces a `groundcrew config: ...` error
     // instead of a raw `TypeError: Cannot read properties of undefined`.
@@ -559,7 +584,7 @@ function applyDefaults(user) {
             definitions: mergeDefinitions(user.agents?.definitions),
         },
         prompts: {
-            initial: user.prompts?.initial ?? DEFAULT_PROMPT_INITIAL,
+            initial: resolveInitialPrompt(user.prompts, configDir),
         },
         workspaceKind: normalizeWorkspaceKind(user.workspaceKind, "workspaceKind") ?? "auto",
         local: {
@@ -571,7 +596,6 @@ function applyDefaults(user) {
     };
 }
 function validatePromptPlaceholders(template) {
-    /* v8 ignore next @preserve -- a no-placeholder prompt is unusual but tests with placeholders consistently match at least once */
     const placeholders = template.match(PROMPT_PLACEHOLDER_RE) ?? [];
     const unknown = placeholders.find((placeholder) => !ALLOWED_PROMPT_PLACEHOLDERS.has(placeholder));
     if (unknown !== undefined) {
@@ -741,7 +765,7 @@ export async function loadConfigWithSource() {
     }
     debug(`Loaded config from ${filepath}`);
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- runtime fields are validated by applyDefaults/validate
-    const resolved = applyDefaults(userConfig);
+    const resolved = applyDefaults(userConfig, path.dirname(filepath));
     validate(resolved);
     setLogFile(resolved.logging.file);
     cached = Object.freeze({

package/dist/lib/sourceCapabilities.js

@@ -29,11 +29,11 @@ function shellCapabilities(raw) {
         verify: commands.verify !== undefined,
         listTasks: true,
         getTask: true,
-        createTask: false,
+        createTask: commands.createTask !== undefined,
         markInProgress: commands.markInProgress !== undefined,
         markInReview: commands.markInReview !== undefined,
         markDone: commands.markDone !== undefined,
-        validate: false,
+        validate: commands.validate !== undefined,
     };
 }
 const TODO_TXT_CAPABILITIES = {

package/docs/configuration.md

@@ -157,6 +157,22 @@ export default {
 
 This keeps package defaults portable while letting your private config reference team-specific statuses, tools, plugins, or review loops.
 
+### Loading the prompt from a file (`prompts.promptFile`)
+
+`readFileSync` works for `.ts` configs but not for `crew.config.json`, which has no way to reference an external file. Set `prompts.promptFile` instead and groundcrew reads the file's contents into the initial prompt at load time:
+
+```json
+{
+  "prompts": {
+    "promptFile": "prompt-initial.md"
+  }
+}
+```
+
+- The path is resolved **relative to the config file's directory** (matching the `.ts` `import.meta.url` behavior); a leading `~` is expanded and absolute paths are used as-is.
+- `prompts.initial` and `prompts.promptFile` are **mutually exclusive** — setting both is a hard error. Set neither to keep the built-in default.
+- Placeholder validation runs on the loaded file contents, so an unknown `{{placeholder}}` in the file fails the same way it would inline.
+
 ## Default Hooks
 
 Repo-local `.groundcrew/config.json` is the preferred place for
@@ -199,7 +215,8 @@ and hook contract.
 | `models.definitions.<name>.sandbox`      | optional             | Docker Sandboxes binding for the model. Required at launch when `local.runner` resolves to `sdx`. Field: `agent` (required sbx agent name). Groundcrew assumes the `groundcrew-<agent>` sandbox already exists.                                                                                                                                                                                                                                                                                                             |
 | `models.definitions.<name>.preLaunch`    | optional             | Host-only shell snippet run before the agent exec and outside Safehouse/sdx. Exports survive into the launch shell; under the default `safehouse` runner they are only forwarded to the agent when listed via `preLaunchEnv` or when `cmd` includes its own `safehouse --env-pass=NAMES`. `{{worktree}}` is substituted. A non-zero exit aborts launch. Not supported when `local.runner` resolves to `sdx` in v1.                                                                                                          |
 | `models.definitions.<name>.preLaunchEnv` | optional             | Companion to `preLaunch`: list of env var names to append to groundcrew's `safehouse-clearance` `--env-pass=` flag, so `preLaunch` exports reach the agent without overriding `cmd` and losing the project's egress allowlist. Each entry must match `[A-Za-z_][A-Za-z0-9_]*`. Under `runner: "none"` exports already inherit and `preLaunchEnv` is a no-op. An empty array is a uniform no-op in every runner; a non-empty list is rejected when `cmd` already starts with `safehouse` or when `runner` resolves to `sdx`. |
-| `prompts.initial`                        | unattended template  | First message sent to the agent: the execution wrapper around each task. The task description is the task-specific prompt. Placeholders: `{{task}}`, `{{worktree}}`, `{{title}}`, `{{description}}`. Override only to change the execution contract for every task, such as team-wide review rules or tool conventions.                                                                                                                                                                                                     |
+| `prompts.initial`                        | unattended template  | First message sent to the agent: the execution wrapper around each task. The task description is the task-specific prompt. Placeholders: `{{task}}`, `{{worktree}}`, `{{title}}`, `{{description}}`. Override only to change the execution contract for every task, such as team-wide review rules or tool conventions. Mutually exclusive with `prompts.promptFile`.                                                                                                                                                       |
+| `prompts.promptFile`                     | optional             | Path to a UTF-8 file whose contents become `prompts.initial`, read at load time. Resolved relative to the config file's directory; `~` is expanded and absolute paths are used as-is. The JSON-friendly alternative to inlining a large prompt or `readFileSync`. Mutually exclusive with `prompts.initial`.                                                                                                                                                                                                                |
 | `workspaceKind`                          | `"auto"`             | Terminal session manager. `"auto"` picks `cmux` when on PATH, else `tmux`. Set to `"cmux"`, `"tmux"`, or `"zellij"` to fail loudly when the chosen backend is missing.                                                                                                                                                                                                                                                                                                                                                      |
 | `local.runner`                           | `"auto"`             | Local isolation backend. `"auto"` uses `safehouse` on macOS and `sdx` on Linux/WSL. Explicit: `"safehouse"`, `"sdx"`, `"none"`. `"none"` is never picked implicitly.                                                                                                                                                                                                                                                                                                                                                        |
 | `logging.file`                           | XDG state path       | Append-mode log file. `log()` / `logEvent()` tee here in addition to stdout. Defaults to `${XDG_STATE_HOME:-$HOME/.local/state}/groundcrew/groundcrew.log`.                                                                                                                                                                                                                                                                                                                                                                 |

package/docs/development.md

@@ -0,0 +1,26 @@
+# Development
+
+Clone the repo and run the CLI from TypeScript source:
+
+```bash
+cd ~/dev/c/groundcrew
+node --run crew -- doctor
+
+# With 1Password for GROUNDCREW_LINEAR_API_KEY:
+node --run crew:op -- run --watch
+```
+
+Both forms discover config through cosmiconfig. Source edits in `src/**` are picked up on the next invocation. Requires Node >= 24.
+
+Regenerate the README demo with VHS:
+
+```bash
+./static/render-demo.sh
+```
+
+Regenerate the Slack bot avatar (also used as the emoji upload; Slack scales it down) after editing the mark:
+
+```bash
+sed 's/width="120" height="120"/width="512" height="512"/' static/groundcrew-mark.svg > /tmp/mark512.svg
+sips -s format png /tmp/mark512.svg --out static/groundcrew-avatar.png
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.28.0",
+  "version": "4.30.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -46,24 +46,24 @@
     "access": "public"
   },
   "scripts": {
-    "architecture:check": "depcruise src bin crew.config.example.ts vitest.config.ts",
+    "architecture:check": "depcruise --config config/dependencyCruiser.cjs src bin crew.config.example.ts vitest.config.ts",
     "build": "tsgo --build --force tsconfig.lib.json",
     "build:dev": "tsgo --build tsconfig.lib.json",
-    "cpd": "jscpd .",
+    "cpd": "jscpd --config config/jscpd.json .",
     "crew": "node --run build:dev && node ./bin/run.js",
     "crew:op": "node --run build:dev && op run --env-file \"${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/op.env\" -- node ./bin/run.js",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "hook:pre-commit": "lint-staged",
+    "format": "oxfmt --config config/oxfmt.json",
+    "format:check": "oxfmt --config config/oxfmt.json --check",
+    "hook:pre-commit": "lint-staged --config config/lintStaged.config.js",
     "hook:pre-push": "node --run verify",
-    "knip": "knip",
-    "lint": "oxlint --deny-warnings",
-    "markdown:lint": "markdownlint-cli2",
+    "knip": "knip --config config/knip.json",
+    "lint": "oxlint --config config/oxlint.config.ts --deny-warnings",
+    "markdown:lint": "markdownlint-cli2 --config config/markdownlint-cli2.jsonc",
     "prepack": "node --run build",
     "prepare": "husky",
-    "spell:check": "cspell --no-summary --no-progress --no-must-find-files",
+    "spell:check": "cspell --config config/cspell.json --no-summary --no-progress --no-must-find-files",
     "sync-ai-rules": "node ./node_modules/@clipboard-health/ai-rules/scripts/sync.js common",
-    "syncpack:lint": "syncpack lint",
+    "syncpack:lint": "syncpack lint --config config/syncpack.config.ts",
     "test": "vitest run --coverage",
     "verify": "node scripts/verifyAll.mts"
   },