@fledge/workflow 0.5.0 → 0.6.1

package/dist/scripts/brief.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { i as runMain, n as writeFrontmatter, r as defineCommand, t as parseFrontmatter } from "./frontmatter-BUnjSmTA.js";
-import { cwd, env, stdout } from "node:process";
+import { cwd, stdout } from "node:process";
 import fs from "node:fs";
 import path from "node:path";
 Object.freeze({ status: "aborted" });
@@ -3679,90 +3679,98 @@ const tasksFrontmatter = object({ tasks: array(object({
 //#region ../cli/dist/brief.js
 const BRIEFS_DIRECTORY = path.join(".fledge", "briefs");
 /**
-* Returns the project root directory.
-* Uses the `FLEDGE_PROJECT_DIR` environment variable if set, otherwise falls back to `cwd()`.
+* Creates a BriefContext from a project directory path or falls back to `cwd()`.
 *
-* @returns The absolute path to the project root.
+* @param projectDirectory - Optional project root override.
+* @returns A BriefContext with the resolved project root.
 */
-function getProjectRoot() {
-	return env.FLEDGE_PROJECT_DIR || cwd();
+function createBriefContext(projectDirectory) {
+	return { projectRoot: projectDirectory ? path.resolve(projectDirectory) : cwd() };
 }
 /**
-* Returns the absolute path to the briefs directory for the current project.
+* Returns the absolute path to the briefs directory for the given context.
 *
+* @param context - The brief context.
 * @returns The absolute path to `.fledge/briefs/` in the project root.
 */
-function getBriefsDirectory() {
-	return path.join(getProjectRoot(), BRIEFS_DIRECTORY);
+function getBriefsDirectory(context) {
+	return path.join(context.projectRoot, BRIEFS_DIRECTORY);
 }
 /**
 * Returns the absolute path to a specific brief's directory.
 *
+* @param context - The brief context.
 * @param name - The brief name (used as directory name).
 * @returns The absolute path to the brief directory.
 */
-function getBriefDirectory(name) {
-	return path.join(getBriefsDirectory(), name);
+function getBriefDirectory(context, name) {
+	return path.join(getBriefsDirectory(context), name);
 }
 /**
 * Returns the absolute path to a brief's `brief.md` file.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @returns The absolute path to `brief.md`.
 */
-function getBriefFile(name) {
-	return path.join(getBriefDirectory(name), "brief.md");
+function getBriefFile(context, name) {
+	return path.join(getBriefDirectory(context, name), "brief.md");
 }
 /**
 * Returns the absolute path to a brief's `tasks.md` file.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @returns The absolute path to `tasks.md`.
 */
-function getTasksFile(name) {
-	return path.join(getBriefDirectory(name), "tasks.md");
+function getTasksFile(context, name) {
+	return path.join(getBriefDirectory(context, name), "tasks.md");
 }
 /**
 * Checks whether a brief directory exists.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @returns `true` if the brief directory exists.
 */
-function briefExists(name) {
-	return fs.existsSync(getBriefDirectory(name));
+function briefExists(context, name) {
+	return fs.existsSync(getBriefDirectory(context, name));
 }
 /**
 * Reads and validates the frontmatter of a brief's `brief.md` file.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @returns The validated brief frontmatter.
 * @throws If the file does not exist or frontmatter fails validation.
 */
-function readBriefFrontmatter(name) {
-	const content = fs.readFileSync(getBriefFile(name), "utf8");
+function readBriefFrontmatter(context, name) {
+	const content = fs.readFileSync(getBriefFile(context, name), "utf8");
 	return briefFrontmatter.parse(parseFrontmatter(content));
 }
 /**
 * Reads and validates the frontmatter of a brief's `tasks.md` file.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @returns The validated tasks frontmatter.
 * @throws If the file does not exist or frontmatter fails validation.
 */
-function readTasksFrontmatter(name) {
-	const content = fs.readFileSync(getTasksFile(name), "utf8");
+function readTasksFrontmatter(context, name) {
+	const content = fs.readFileSync(getTasksFile(context, name), "utf8");
 	return tasksFrontmatter.parse(parseFrontmatter(content));
 }
 /**
 * Updates the frontmatter of a brief's `brief.md` file while preserving its body content.
 *
+* @param context - The brief context.
 * @param name - The brief name.
 * @param data - The new frontmatter data to write.
 */
-function updateBriefFrontmatter(name, data) {
-	const briefFile = getBriefFile(name);
-	const content = fs.readFileSync(briefFile, "utf8");
-	fs.writeFileSync(briefFile, writeFrontmatter(data, content));
+function updateBriefFrontmatter(context, name, data) {
+	const file = getBriefFile(context, name);
+	const content = fs.readFileSync(file, "utf8");
+	fs.writeFileSync(file, writeFrontmatter(data, content));
 }
 /**
 * Validates that a state transition is allowed and throws a descriptive error if not.
@@ -3789,37 +3797,52 @@ function formatDate() {
 /**
 * Lists all brief directories in the project.
 *
+* @param context - The brief context.
 * @returns An array of brief names (directory names).
 */
-function listBriefs() {
-	const directory = getBriefsDirectory();
+function listBriefs(context) {
+	const directory = getBriefsDirectory(context);
 	if (!fs.existsSync(directory)) return [];
 	return fs.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
 }
 //#endregion
+//#region ../cli/dist/commands/brief/shared.js
+/**
+* Shared argument definition for the `--project-dir` flag used by all brief subcommands.
+*/
+const projectDirectory = {
+	required: false,
+	alias: "project-dir",
+	description: "Project root directory. Overrides cwd() for locating .fledge/briefs/."
+};
+//#endregion
 //#region ../cli/dist/commands/brief/complete.js
 var complete_default = defineCommand({
 	meta: {
 		name: "complete",
 		description: "Transition a brief from active to completed"
 	},
-	args: { name: {
-		type: "positional",
-		required: true,
-		description: "The name of the brief to complete"
-	} },
+	args: {
+		name: {
+			type: "positional",
+			required: true,
+			description: "The name of the brief to complete"
+		},
+		projectDirectory
+	},
 	run(context) {
+		const ctx = createBriefContext(context.args.projectDirectory);
 		const { name } = context.args;
-		if (!briefExists(name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(name)}"`);
-		const brief = readBriefFrontmatter(name);
+		if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
+		const brief = readBriefFrontmatter(ctx, name);
 		validateTransition(brief.status, "completed");
 		if (!brief.summary) throw new Error("Brief must have a summary before completing. Add a \"summary\" field to the brief.md frontmatter.");
-		const incomplete = readTasksFrontmatter(name).tasks.filter((task) => !task.done);
+		const incomplete = readTasksFrontmatter(ctx, name).tasks.filter((task) => !task.done);
 		if (incomplete.length > 0) {
 			const names = incomplete.map((task) => `  - ${task.name}`).join("\n");
 			throw new Error(`Cannot complete brief with ${incomplete.length} incomplete task(s):\n${names}`);
 		}
-		updateBriefFrontmatter(name, {
+		updateBriefFrontmatter(ctx, name, {
 			...brief,
 			status: "completed",
 			updated: formatDate()
@@ -3834,24 +3857,28 @@ var create_default = defineCommand({
 		name: "create",
 		description: "Create a new brief with stub files"
 	},
-	args: { name: {
-		type: "positional",
-		required: true,
-		description: "The name of the brief to create (used as directory name)"
-	} },
+	args: {
+		name: {
+			type: "positional",
+			required: true,
+			description: "The name of the brief to create (used as directory name)"
+		},
+		projectDirectory
+	},
 	run(context) {
+		const ctx = createBriefContext(context.args.projectDirectory);
 		const { name } = context.args;
-		if (briefExists(name)) throw new Error(`Brief "${name}" already exists at "${getBriefDirectory(name)}"`);
-		const directory = getBriefDirectory(name);
+		if (briefExists(ctx, name)) throw new Error(`Brief "${name}" already exists at "${getBriefDirectory(ctx, name)}"`);
+		const directory = getBriefDirectory(ctx, name);
 		fs.mkdirSync(directory, { recursive: true });
 		const date = formatDate();
-		fs.writeFileSync(getBriefFile(name), writeFrontmatter({
+		fs.writeFileSync(getBriefFile(ctx, name), writeFrontmatter({
 			name,
 			status: "draft",
 			created: date,
 			updated: date
 		}));
-		fs.writeFileSync(getTasksFile(name), writeFrontmatter({ tasks: [] }));
+		fs.writeFileSync(getTasksFile(ctx, name), writeFrontmatter({ tasks: [] }));
 		stdout.write(`Created brief "${name}" at "${directory}"\n`);
 	}
 });
@@ -3862,20 +3889,24 @@ var list_default = defineCommand({
 		name: "list",
 		description: "List all briefs with their status and progress"
 	},
-	args: { status: {
-		type: "string",
-		required: false,
-		description: "Filter by brief status (draft, active, completed)"
-	} },
+	args: {
+		status: {
+			type: "string",
+			required: false,
+			description: "Filter by brief status (draft, active, completed)"
+		},
+		projectDirectory
+	},
 	run(context) {
-		const names = listBriefs();
+		const ctx = createBriefContext(context.args.projectDirectory);
+		const names = listBriefs(ctx);
 		if (names.length === 0) {
 			stdout.write("No briefs found\n");
 			return;
 		}
 		let briefs = names.map((name) => {
-			const brief = readBriefFrontmatter(name);
-			const { tasks } = readTasksFrontmatter(name);
+			const brief = readBriefFrontmatter(ctx, name);
+			const { tasks } = readTasksFrontmatter(ctx, name);
 			const done = tasks.filter((task) => task.done).length;
 			return {
 				...brief,
@@ -3925,18 +3956,22 @@ var start_default = defineCommand({
 		name: "start",
 		description: "Transition a brief from draft to active"
 	},
-	args: { name: {
-		type: "positional",
-		required: true,
-		description: "The name of the brief to start"
-	} },
+	args: {
+		name: {
+			type: "positional",
+			required: true,
+			description: "The name of the brief to start"
+		},
+		projectDirectory
+	},
 	run(context) {
+		const ctx = createBriefContext(context.args.projectDirectory);
 		const { name } = context.args;
-		if (!briefExists(name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(name)}"`);
-		const brief = readBriefFrontmatter(name);
+		if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
+		const brief = readBriefFrontmatter(ctx, name);
 		validateTransition(brief.status, "active");
-		if (readTasksFrontmatter(name).tasks.length === 0) throw new Error("Brief must have at least one task before starting");
-		updateBriefFrontmatter(name, {
+		if (readTasksFrontmatter(ctx, name).tasks.length === 0) throw new Error("Brief must have at least one task before starting");
+		updateBriefFrontmatter(ctx, name, {
 			...brief,
 			status: "active",
 			updated: formatDate()
@@ -3989,24 +4024,28 @@ runMain(defineCommand({
 				name: "status",
 				description: "Show the status and task progress of a brief"
 			},
-			args: { name: {
-				type: "positional",
-				required: true,
-				description: "The name of the brief to show status for"
-			} },
+			args: {
+				name: {
+					type: "positional",
+					required: true,
+					description: "The name of the brief to show status for"
+				},
+				projectDirectory
+			},
 			run(context) {
+				const ctx = createBriefContext(context.args.projectDirectory);
 				const { name } = context.args;
-				if (!briefExists(name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(name)}"`);
-				const brief = readBriefFrontmatter(name);
-				const { tasks } = readTasksFrontmatter(name);
+				if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
+				const brief = readBriefFrontmatter(ctx, name);
+				const { tasks } = readTasksFrontmatter(ctx, name);
 				const done = tasks.filter((task) => task.done).length;
 				const lines = [];
 				lines.push(`${name} [${brief.status}] ${done}/${tasks.length} tasks done`);
 				lines.push("");
 				const groups = groupTasks(tasks);
-				for (const [group, groupTasks] of groups) {
+				for (const [group, groupedTasks] of groups) {
 					if (group) lines.push(group);
-					for (const task of groupTasks) lines.push(formatTask(task));
+					for (const task of groupedTasks) lines.push(formatTask(task));
 				}
 				stdout.write(`${lines.join("\n")}\n`);
 			}
@@ -4016,19 +4055,23 @@ runMain(defineCommand({
 				name: "validate",
 				description: "Validate brief and tasks files against their schemas"
 			},
-			args: { name: {
-				type: "positional",
-				required: true,
-				description: "The name of the brief to validate"
-			} },
+			args: {
+				name: {
+					type: "positional",
+					required: true,
+					description: "The name of the brief to validate"
+				},
+				projectDirectory
+			},
 			run(context) {
+				const ctx = createBriefContext(context.args.projectDirectory);
 				const { name } = context.args;
-				if (!briefExists(name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(name)}"`);
+				if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
 				const errors = [];
-				const briefContent = fs.readFileSync(getBriefFile(name), "utf8");
+				const briefContent = fs.readFileSync(getBriefFile(ctx, name), "utf8");
 				const briefResult = briefFrontmatter.safeParse(parseFrontmatter(briefContent));
 				if (!briefResult.success) for (const issue of briefResult.error.issues) errors.push(`brief.md: ${issue.path.join(".")}: ${issue.message}`);
-				const tasksContent = fs.readFileSync(getTasksFile(name), "utf8");
+				const tasksContent = fs.readFileSync(getTasksFile(ctx, name), "utf8");
 				const tasksResult = tasksFrontmatter.safeParse(parseFrontmatter(tasksContent));
 				if (!tasksResult.success) for (const issue of tasksResult.error.issues) errors.push(`tasks.md: ${issue.path.join(".")}: ${issue.message}`);
 				if (errors.length > 0) throw new Error(`Validation failed for "${name}":\n${errors.map((error) => `  - ${error}`).join("\n")}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fledge/workflow",
   "type": "module",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "author": "René Schapka",
   "license": "MIT",
   "files": [
@@ -15,7 +15,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@fledge/cli": "^0.8.0"
+    "@fledge/cli": "^0.9.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "7.7.3",

package/skills/brief/SKILL.md

@@ -5,28 +5,19 @@ description: >-
   Invoked directly via /fledge-brief, not auto-triggered.
 metadata:
   type: workflow
+allowed-tools: Bash(scripts/brief.js *), Bash(node *)
 ---
 
-## Setup
-
-Before running any script, set the `FLEDGE_PROJECT_DIR` environment variable to the project root so scripts know where to find and create briefs:
-
-```bash
-export FLEDGE_PROJECT_DIR="$(pwd)"
-```
-
-Set this once at the start of the conversation. All scripts below assume it is set.
-
 ## Available scripts
 
-Self-contained executable scripts bundled with this skill:
+**Important:** All scripts have a shebang and are executable. Run them directly (e.g. `scripts/brief.js list`), never prefix with `node`. Always pass `--project-dir` pointing to the project root.
 
-- **`scripts/brief.js create <name>`** -- Create a new brief with stub files
-- **`scripts/brief.js start <name>`** -- Transition a brief from draft to active
-- **`scripts/brief.js complete <name>`** -- Transition a brief from active to completed
-- **`scripts/brief.js status <name>`** -- Show status and task progress
-- **`scripts/brief.js list [--status <status>]`** -- List all briefs with progress and summary
-- **`scripts/brief.js validate <name>`** -- Validate brief files against schemas
+- **`scripts/brief.js create <name> --project-dir <path>`** -- Create a new brief with stub files
+- **`scripts/brief.js start <name> --project-dir <path>`** -- Transition a brief from draft to active
+- **`scripts/brief.js complete <name> --project-dir <path>`** -- Transition a brief from active to completed
+- **`scripts/brief.js status <name> --project-dir <path>`** -- Show status and task progress
+- **`scripts/brief.js list [--status <status>] --project-dir <path>`** -- List all briefs with progress and summary
+- **`scripts/brief.js validate <name> --project-dir <path>`** -- Validate brief files against schemas
 - **`scripts/brief.js schema`** -- Output JSON Schema for brief and tasks frontmatter
 
 ## Step 0: Determine intent
@@ -37,7 +28,7 @@ Ask what the user wants to do, or infer from context. Present these options:
 2. **Continue a brief** -- pick up an existing brief. Proceed to Step 4.
 3. **Complete a brief** -- wrap up a finished feature. Proceed to Step 5.
 
-If unclear, run `scripts/brief.js list` to show current briefs and ask.
+If unclear, run `scripts/brief.js list --project-dir <path>` to show current briefs and ask.
 
 ---
 
@@ -45,7 +36,7 @@ If unclear, run `scripts/brief.js list` to show current briefs and ask.
 
 Before writing anything, build an understanding of what exists.
 
-1. Run `scripts/brief.js list --status completed` to read summaries of completed features. Note anything relevant to the new feature.
+1. Run `scripts/brief.js list --status completed --project-dir <path>` to read summaries of completed features. Note anything relevant to the new feature.
 2. Ask the user what they want to build. Keep it conversational, not a form. Aim to understand:
    - What is the user-facing change?
    - Why does it matter?
@@ -60,7 +51,7 @@ Proceed to Step 2.
 
 ## Step 2: Draft the brief
 
-Run `scripts/brief.js create <name>` to create the brief directory.
+Run `scripts/brief.js create <name> --project-dir <path>` to create the brief directory.
 
 Write the brief content into `brief.md`. The frontmatter is managed by the scripts. The markdown body should capture:
 
@@ -96,7 +87,7 @@ tasks:
 
 Order tasks by dependency: tasks that others depend on come first within their group.
 
-After writing tasks, run `scripts/brief.js validate <name>` to confirm the brief is valid, then run `scripts/brief.js start <name>` to transition to active.
+After writing tasks, run `scripts/brief.js validate <name> --project-dir <path>` to confirm the brief is valid, then run `scripts/brief.js start <name> --project-dir <path>` to transition to active.
 
 Present the complete brief and task list to the user for review before starting.
 
@@ -104,22 +95,22 @@ Present the complete brief and task list to the user for review before starting.
 
 ## Step 4: Continue a brief
 
-Run `scripts/brief.js list` to show all briefs. If the user does not specify which brief, ask them to pick one.
+Run `scripts/brief.js list --project-dir <path>` to show all briefs. If the user does not specify which brief, ask them to pick one.
 
-Run `scripts/brief.js status <name>` to show progress. Read the brief and tasks files to understand the full context.
+Run `scripts/brief.js status <name> --project-dir <path>` to show progress. Read the brief and tasks files to understand the full context.
 
 From here, the user may want to:
 - **Discuss a task** -- talk through approach before implementing
 - **Update tasks** -- mark tasks as done, add new tasks, reorder
 - **Revise the brief** -- update scope or design decisions based on what was learned during implementation
 
-When updating task status, modify the `tasks.md` frontmatter directly, then run `scripts/brief.js status <name>` to confirm the update.
+When updating task status, modify the `tasks.md` frontmatter directly, then run `scripts/brief.js status <name> --project-dir <path>` to confirm the update.
 
 ---
 
 ## Step 5: Complete a brief
 
-Run `scripts/brief.js status <name>` to verify all tasks are done.
+Run `scripts/brief.js status <name> --project-dir <path>` to verify all tasks are done.
 
 If there are incomplete tasks, ask the user whether to:
 1. Mark remaining tasks as done (if they were completed outside this conversation)
@@ -130,4 +121,4 @@ Write a summary into the `brief.md` frontmatter `summary` field. The summary sho
 - What was built
 - Key decisions or patterns established that future features should know about
 
-Run `scripts/brief.js complete <name>` to transition to completed. The script validates that all tasks are done and the summary is present.
+Run `scripts/brief.js complete <name> --project-dir <path>` to transition to completed. The script validates that all tasks are done and the summary is present.