@fledge/workflow 0.6.3 → 0.7.1

package/dist/scripts/brief.js

@@ -554,7 +554,6 @@ const string$1 = (params) => {
 	const regex = params ? `[\\s\\S]{${params?.minimum ?? 0},${params?.maximum ?? ""}}` : `[\\s\\S]*`;
 	return new RegExp(`^${regex}$`);
 };
-const boolean$1 = /^(?:true|false)$/i;
 const lowercase = /^[^A-Z]*$/;
 const uppercase = /^[^a-z]*$/;
 //#endregion
@@ -1166,24 +1165,6 @@ const $ZodJWT = /* @__PURE__ */ $constructor("$ZodJWT", (inst, def) => {
 		});
 	};
 });
-const $ZodBoolean = /* @__PURE__ */ $constructor("$ZodBoolean", (inst, def) => {
-	$ZodType.init(inst, def);
-	inst._zod.pattern = boolean$1;
-	inst._zod.parse = (payload, _ctx) => {
-		if (def.coerce) try {
-			payload.value = Boolean(payload.value);
-		} catch (_) {}
-		const input = payload.value;
-		if (typeof input === "boolean") return payload;
-		payload.issues.push({
-			expected: "boolean",
-			code: "invalid_type",
-			input,
-			inst
-		});
-		return payload;
-	};
-});
 const $ZodUnknown = /* @__PURE__ */ $constructor("$ZodUnknown", (inst, def) => {
 	$ZodType.init(inst, def);
 	inst._zod.parse = (payload) => payload;
@@ -2146,13 +2127,6 @@ function _isoDuration(Class, params) {
 	});
 }
 /* @__NO_SIDE_EFFECTS__ */
-function _boolean(Class, params) {
-	return new Class({
-		type: "boolean",
-		...normalizeParams(params)
-	});
-}
-/* @__NO_SIDE_EFFECTS__ */
 function _unknown(Class) {
 	return new Class({ type: "unknown" });
 }
@@ -3336,14 +3310,6 @@ const ZodJWT = /* @__PURE__ */ $constructor("ZodJWT", (inst, def) => {
 	$ZodJWT.init(inst, def);
 	ZodStringFormat.init(inst, def);
 });
-const ZodBoolean = /* @__PURE__ */ $constructor("ZodBoolean", (inst, def) => {
-	$ZodBoolean.init(inst, def);
-	ZodType.init(inst, def);
-	inst._zod.processJSONSchema = (ctx, json, params) => booleanProcessor(inst, ctx, json, params);
-});
-function boolean(params) {
-	return /* @__PURE__ */ _boolean(ZodBoolean, params);
-}
 const ZodUnknown = /* @__PURE__ */ $constructor("ZodUnknown", (inst, def) => {
 	$ZodUnknown.init(inst, def);
 	ZodType.init(inst, def);
@@ -3650,8 +3616,10 @@ function superRefine(fn) {
 //#region ../cli/dist/schemas/brief.js
 const briefStatus = _enum([
 	"draft",
+	"ready",
 	"active",
-	"completed"
+	"completed",
+	"cancelled"
 ]);
 const briefFrontmatter = object({
 	name: string().min(1),
@@ -3663,20 +3631,42 @@ const briefFrontmatter = object({
 /**
 * Valid state transitions for a brief.
 * Each key maps to the set of states it can transition to.
+*
+* draft → ready: brief skill marks the brief as designed and enriched
+* ready → active: build skill begins building
+* ready → draft: brief needs rework
+* active → completed: build skill finishes all tasks
+* draft/ready/active → cancelled: feature is dropped
 */
 const briefTransitions = {
-	draft: ["active"],
-	active: ["completed", "draft"],
-	completed: []
+	draft: ["ready", "cancelled"],
+	ready: [
+		"active",
+		"draft",
+		"cancelled"
+	],
+	active: ["completed", "cancelled"],
+	completed: [],
+	cancelled: []
 };
+//#endregion
+//#region ../cli/dist/schemas/tasks.js
+const taskStatus = _enum([
+	"pending",
+	"active",
+	"completed",
+	"skipped"
+]);
 const tasksFrontmatter = object({ tasks: array(object({
 	name: string().min(1),
 	group: string().min(1).optional(),
-	done: boolean().default(false)
+	status: taskStatus.default("pending")
 })) });
 //#endregion
 //#region ../cli/dist/brief.js
-const BRIEFS_DIRECTORY = path.join(".fledge", "briefs");
+const FLEDGE_DIRECTORY = ".fledge";
+const BRIEFS_DIRECTORY = path.join(FLEDGE_DIRECTORY, "briefs");
+path.join(FLEDGE_DIRECTORY, "project.md");
 /**
 * Creates a BriefContext from a project directory path or falls back to `cwd()`.
 *
@@ -3726,6 +3716,16 @@ function getTasksFile(context, name) {
 	return path.join(getBriefDirectory(context, name), "tasks.md");
 }
 /**
+* Returns the absolute path to a brief's `spec.md` file.
+*
+* @param context - The brief context.
+* @param name - The brief name.
+* @returns The absolute path to `spec.md`.
+*/
+function getSpecFile(context, name) {
+	return path.join(getBriefDirectory(context, name), "spec.md");
+}
+/**
 * Checks whether a brief directory exists.
 *
 * @param context - The brief context.
@@ -3815,6 +3815,35 @@ const projectDirectory = {
 	description: "Project root directory. Overrides cwd() for locating .fledge/briefs/."
 };
 //#endregion
+//#region ../cli/dist/commands/brief/cancel.js
+var cancel_default = defineCommand({
+	meta: {
+		name: "cancel",
+		description: "Cancel a brief"
+	},
+	args: {
+		name: {
+			type: "positional",
+			required: true,
+			description: "The name of the brief to cancel"
+		},
+		projectDirectory
+	},
+	run(context) {
+		const ctx = createBriefContext(context.args.projectDirectory);
+		const { name } = context.args;
+		if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
+		const brief = readBriefFrontmatter(ctx, name);
+		validateTransition(brief.status, "cancelled");
+		updateBriefFrontmatter(ctx, name, {
+			...brief,
+			status: "cancelled",
+			updated: formatDate()
+		});
+		stdout.write(`Brief "${name}" has been cancelled\n`);
+	}
+});
+//#endregion
 //#region ../cli/dist/commands/brief/complete.js
 var complete_default = defineCommand({
 	meta: {
@@ -3836,10 +3865,10 @@ var complete_default = defineCommand({
 		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(ctx, name).tasks.filter((task) => !task.done);
+		const incomplete = readTasksFrontmatter(ctx, name).tasks.filter((task) => task.status !== "completed" && task.status !== "skipped");
 		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}`);
+			const names = incomplete.map((task) => `  - ${task.name} [${task.status}]`).join("\n");
+			throw new Error(`Cannot complete brief with ${incomplete.length} unfinished task(s):\n${names}`);
 		}
 		updateBriefFrontmatter(ctx, name, {
 			...brief,
@@ -3878,6 +3907,7 @@ var create_default = defineCommand({
 			updated: date
 		}));
 		fs.writeFileSync(getTasksFile(ctx, name), writeFrontmatter({ tasks: [] }));
+		fs.writeFileSync(getSpecFile(ctx, name), "");
 		stdout.write(`Created brief "${name}" at "${directory}"\n`);
 	}
 });
@@ -3892,7 +3922,7 @@ var list_default = defineCommand({
 		status: {
 			type: "string",
 			required: false,
-			description: "Filter by brief status (draft, active, completed)"
+			description: "Filter by brief status (draft, ready, active, completed, cancelled)"
 		},
 		projectDirectory
 	},
@@ -3906,7 +3936,7 @@ var list_default = defineCommand({
 		let briefs = names.map((name) => {
 			const brief = readBriefFrontmatter(ctx, name);
 			const { tasks } = readTasksFrontmatter(ctx, name);
-			const done = tasks.filter((task) => task.done).length;
+			const done = tasks.filter((task) => task.status === "completed" || task.status === "skipped").length;
 			return {
 				...brief,
 				tasksDone: done,
@@ -3934,6 +3964,35 @@ var list_default = defineCommand({
 	}
 });
 //#endregion
+//#region ../cli/dist/commands/brief/ready.js
+var ready_default = defineCommand({
+	meta: {
+		name: "ready",
+		description: "Transition a brief from draft to ready"
+	},
+	args: {
+		name: {
+			type: "positional",
+			required: true,
+			description: "The name of the brief to mark as ready"
+		},
+		projectDirectory
+	},
+	run(context) {
+		const ctx = createBriefContext(context.args.projectDirectory);
+		const { name } = context.args;
+		if (!briefExists(ctx, name)) throw new Error(`Brief "${name}" does not exist at "${getBriefDirectory(ctx, name)}"`);
+		const brief = readBriefFrontmatter(ctx, name);
+		validateTransition(brief.status, "ready");
+		updateBriefFrontmatter(ctx, name, {
+			...brief,
+			status: "ready",
+			updated: formatDate()
+		});
+		stdout.write(`Brief "${name}" is ready for implementation\n`);
+	}
+});
+//#endregion
 //#region ../cli/dist/commands/brief/schema.js
 var schema_default = defineCommand({
 	meta: {
@@ -3953,7 +4012,7 @@ var schema_default = defineCommand({
 var start_default = defineCommand({
 	meta: {
 		name: "start",
-		description: "Transition a brief from draft to active"
+		description: "Transition a brief from ready to active"
 	},
 	args: {
 		name: {
@@ -3969,7 +4028,6 @@ var start_default = defineCommand({
 		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(ctx, name).tasks.length === 0) throw new Error("Brief must have at least one task before starting");
 		updateBriefFrontmatter(ctx, name, {
 			...brief,
 			status: "active",
@@ -3997,13 +4055,18 @@ function groupTasks(tasks) {
 	return groups;
 }
 /**
-* Formats a task as a line with a checkbox indicator.
+* Maps a task status to a display indicator.
 *
 * @param task - The task to format.
-* @returns The formatted task string.
+* @returns The formatted task string with status indicator.
 */
 function formatTask(task) {
-	return `  ${task.done ? "[x]" : "[ ]"} ${task.name}`;
+	return `  ${{
+		pending: "[ ]",
+		active: "[~]",
+		completed: "[x]",
+		skipped: "[-]"
+	}[task.status] ?? "[ ]"} ${task.name}`;
 }
 //#endregion
 //#region ../cli/dist/run-brief.js
@@ -4013,9 +4076,11 @@ runMain(defineCommand({
 		description: "Manage feature briefs"
 	},
 	subCommands: {
+		cancel: cancel_default,
 		complete: complete_default,
 		create: create_default,
 		list: list_default,
+		ready: ready_default,
 		schema: schema_default,
 		start: start_default,
 		status: defineCommand({
@@ -4037,7 +4102,7 @@ runMain(defineCommand({
 				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 done = tasks.filter((task) => task.status === "completed" || task.status === "skipped").length;
 				const lines = [];
 				lines.push(`${name} [${brief.status}] ${done}/${tasks.length} tasks done`);
 				lines.push("");

package/package.json

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

package/skills/brief/SKILL.md

@@ -1,20 +1,43 @@
 ---
 name: fledge-brief
 description: >-
-  Guide feature brief creation and lifecycle. Plan new features, create or update feature briefs, break down work into tasks, or complete a feature.
+  Guide feature brief creation and lifecycle. Plan new features, create or update feature briefs, enrich with project knowledge, or complete a feature.
   Invoked directly via /fledge-brief, not auto-triggered.
 metadata:
   type: workflow
-allowed-tools: Bash(node *scripts/brief.js *)
+allowed-tools: Bash(node *scripts/brief.js*)
 ---
 
+## Lifecycle overview
+
+The brief skill owns two workflow phases: **Brief** (capture what to build) and **Enrich** (connect to project knowledge). See [docs/workflow.md](../../docs/workflow.md) for the full workflow.
+
+```
+Brief  →  Enrich  →  [Build]  →  [Verify]  →  [Complete]
+└── this skill ──┘    └── build skill (future) ──────────┘
+```
+
+**States this skill manages:** `draft → ready`
+**States managed by the build skill:** `ready → active → completed`
+
+A brief directory contains three files:
+
+```
+.fledge/briefs/<name>/
+  brief.md      what, why, scope, design decisions (product-level)
+  spec.md       data models, APIs, external services (technical context)
+  tasks.md      tasks (empty until build phase)
+```
+
 ## Available scripts
 
 **Important:** Run all scripts with `node` (e.g. `node scripts/brief.js list`). Always pass `--project-dir` pointing to the project root.
 
 - **`node scripts/brief.js create <name> --project-dir <path>`** -- Create a new brief with stub files
-- **`node scripts/brief.js start <name> --project-dir <path>`** -- Transition a brief from draft to active
+- **`node scripts/brief.js ready <name> --project-dir <path>`** -- Transition a brief from draft to ready
+- **`node scripts/brief.js start <name> --project-dir <path>`** -- Transition a brief from ready to active
 - **`node scripts/brief.js complete <name> --project-dir <path>`** -- Transition a brief from active to completed
+- **`node scripts/brief.js cancel <name> --project-dir <path>`** -- Cancel a brief
 - **`node scripts/brief.js status <name> --project-dir <path>`** -- Show status and task progress
 - **`node scripts/brief.js list [--status <status>] --project-dir <path>`** -- List all briefs with progress and summary
 - **`node scripts/brief.js validate <name> --project-dir <path>`** -- Validate brief files against schemas
@@ -25,8 +48,8 @@ allowed-tools: Bash(node *scripts/brief.js *)
 Ask what the user wants to do, or infer from context. Present these options:
 
 1. **New brief** -- plan a new feature from scratch. Proceed to Step 1.
-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.
+2. **Continue a brief** -- pick up an existing brief. Proceed to Step 5.
+3. **Complete a brief** -- wrap up a finished feature. Proceed to Step 6.
 
 If unclear, run `node scripts/brief.js list --project-dir <path>` to show current briefs and ask.
 
@@ -60,65 +83,70 @@ Write the brief content into `brief.md`. The frontmatter is managed by the scrip
 - **Scope**: what is included and what is explicitly excluded
 - **Design decisions**: key choices made during this conversation, with reasoning
 
-Keep it concise. The brief is a reference for implementation, not a specification document. If something is obvious from the code, do not repeat it here.
+Keep it concise. The brief is a reference for building, not a specification document. If something is obvious from the code, do not repeat it here.
 
 Proceed to Step 3.
 
 ---
 
-## Step 3: Break down into tasks
+## Step 3: Enrich with project knowledge
 
-Define the implementation tasks in `tasks.md`. Each task should be:
+Connect the brief to the technical reality of the project. Start by reading `.fledge/project.md` to understand the project landscape. If this file does not exist, suggest running `fledge init` first.
 
-- **Small enough** to be a single focused unit of work
-- **Specific enough** that someone (or an agent) can start without further clarification
-- **Grouped** by concern when the feature spans multiple areas (e.g. backend, frontend, data)
+Walk through each section of `project.md` with the brief in mind:
 
-Write the tasks into the `tasks.md` frontmatter:
+1. **Domain**: which concepts from the glossary does this feature involve? Are there new domain terms that need defining?
+2. **Data models**: which existing models does the feature interact with? Are new models or fields needed?
+3. **APIs**: which existing endpoints are relevant? Are new endpoints needed? Do they follow the documented conventions?
+4. **External services**: does this feature involve any third-party integrations?
+5. **Conventions**: are there project-specific patterns the build should follow?
+6. **Stack**: which technology skills are available to guide the build?
+
+Write the relevant findings into `spec.md`. The spec grounds the product-level brief in the project's actual structure. It does **not** include tasks or technology-specific guidance (those come from the build skill and technology skills).
+
+**Gap detection**: if you discover aspects of the project that are not reflected in `project.md` (an undocumented endpoint, a model that is missing, a domain concept that should be in the glossary), note these gaps and suggest updates to `project.md`. Keeping project knowledge current is part of enrichment.
+
+Proceed to Step 4.
 
-```yaml
----
-tasks:
-  - name: <clear, actionable task name>
-    group: <area>
-    done: false
 ---
-```
 
-Order tasks by dependency: tasks that others depend on come first within their group.
+## Step 4: Mark as ready
+
+Run `node scripts/brief.js validate <name> --project-dir <path>` to confirm the brief is valid.
 
-After writing tasks, run `node scripts/brief.js validate <name> --project-dir <path>` to confirm the brief is valid, then run `node scripts/brief.js start <name> --project-dir <path>` to transition to active.
+Present the complete brief (`brief.md`) and spec (`spec.md`) to the user for review.
 
-Present the complete brief and task list to the user for review before starting.
+Once approved, run `node scripts/brief.js ready <name> --project-dir <path>` to transition to ready. The brief is now ready for the build skill to pick up.
 
 ---
 
-## Step 4: Continue a brief
+## Step 5: Continue a brief
 
 Run `node 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 `node scripts/brief.js status <name> --project-dir <path>` to show progress. Read the brief and tasks files to understand the full context.
+Run `node scripts/brief.js status <name> --project-dir <path>` to show progress. Read the brief, spec, 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
+- **Discuss the brief** -- talk through scope or design decisions
+- **Update the spec** -- add or revise technical context
+- **Revise the brief** -- update scope or design decisions based on what was learned
+- **Send back to draft** -- if a ready brief needs significant rework, update the status back to draft
 
-When updating task status, modify the `tasks.md` frontmatter directly, then run `node scripts/brief.js status <name> --project-dir <path>` to confirm the update.
+When updating files, run `node scripts/brief.js validate <name> --project-dir <path>` afterward to confirm validity.
 
 ---
 
-## Step 5: Complete a brief
+## Step 6: Complete a brief
 
 Run `node 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)
-2. Remove tasks that are no longer needed
+1. Mark remaining tasks as completed (if they were completed outside this conversation)
+2. Mark tasks as skipped (if they are no longer needed)
 3. Continue working on them first
 
 Write a summary into the `brief.md` frontmatter `summary` field. The summary should be one to two sentences capturing:
 - What was built
 - Key decisions or patterns established that future features should know about
 
-Run `node 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.
+Run `node scripts/brief.js complete <name> --project-dir <path>` to transition to completed. The script validates that all tasks are done or skipped and the summary is present.