@fledge/workflow 0.3.0 → 0.5.0

package/dist/scripts/skills.js

@@ -0,0 +1,264 @@
+#!/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 fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+//#region ../cli/dist/skills.js
+const SCOPED_PACKAGE_PATTERN = /^@([\w-]+)\/(.+)/;
+/**
+* Relative path from a project (or home directory for global installs) to the
+* skills directory. Claude Code currently only loads skills from `.claude/skills`.
+* Once `.agents/skills` is supported we can switch here:
+* https://github.com/anthropics/claude-code/issues/31005
+*/
+const SKILLS_DIRECTORY = path.join(".claude", "skills");
+/**
+* Reads the package name from a package.json file in the given directory.
+*
+* @param packageDirectory - The directory containing the package.json.
+* @returns The package name.
+* @throws If the package.json does not contain a string name.
+*/
+function getPackageName(packageDirectory) {
+	const packageFile = path.join(packageDirectory, "package.json");
+	const { name } = JSON.parse(fs.readFileSync(packageFile, "utf8"));
+	if (typeof name !== "string") throw new TypeError("Package name must be of type string");
+	return name;
+}
+/**
+* Derives the skill prefix from a package name by replacing the scoped package
+* separator with a hyphen (e.g. `@fledge/vue` becomes `fledge-vue`).
+*
+* @param packageName - The npm package name.
+* @returns The skill prefix used as directory name.
+*/
+function getSkillPrefix(packageName) {
+	return packageName.replace(SCOPED_PACKAGE_PATTERN, (_, scope, name) => `${scope}-${name}`);
+}
+/**
+* Extracts the scope from a scoped package name (e.g. `@fledge/workflow` becomes `fledge`).
+* Returns the full package name if unscoped.
+*
+* @param packageName - The npm package name.
+* @returns The scope without the `@` prefix.
+*/
+function getScope(packageName) {
+	const match = packageName.match(SCOPED_PACKAGE_PATTERN);
+	return match ? match[1] : packageName;
+}
+/**
+* Returns the default target directory for skill installation.
+* Uses `INIT_CWD` (set by npm/pnpm during postinstall) or falls back to `cwd()`.
+*
+* @returns The absolute path to the project directory.
+*/
+function getProjectDirectory() {
+	return env.INIT_CWD || cwd();
+}
+/**
+* Returns the user's home directory for global skill installation.
+*
+* @returns The absolute path to the home directory.
+*/
+function getGlobalDirectory() {
+	return os.homedir();
+}
+/**
+* Detects whether a package contains a single skill (`skill/` directory)
+* or multiple skills (`skills/` directory with subdirectories).
+*
+* @param packageDirectory - The directory containing the skill package.
+* @returns `'single'` if a `skill/` directory exists, `'multiple'` if a `skills/` directory exists, or `'none'`.
+*/
+function detectSkillLayout(packageDirectory) {
+	if (fs.existsSync(path.join(packageDirectory, "skills"))) return "multiple";
+	if (fs.existsSync(path.join(packageDirectory, "skill"))) return "single";
+	return "none";
+}
+/**
+* Returns the source directories for skills in a package.
+*
+* For a single-skill package, returns one entry with the `skill/` directory
+* and the skill name derived from the package name.
+*
+* For a multi-skill package, returns one entry per subdirectory in `skills/`,
+* with the skill name taken from the subdirectory name.
+*
+* @param packageDirectory - The directory containing the skill package.
+* @param packageName - The npm package name (used for single-skill naming).
+* @returns An array of `{ source, name }` objects.
+*/
+function getSkillSources(packageDirectory, packageName) {
+	const layout = detectSkillLayout(packageDirectory);
+	if (layout === "single") return [{
+		source: path.join(packageDirectory, "skill"),
+		name: getSkillPrefix(packageName)
+	}];
+	if (layout === "multiple") {
+		const skillsDirectory = path.join(packageDirectory, "skills");
+		const scope = getScope(packageName);
+		return fs.readdirSync(skillsDirectory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => ({
+			source: path.join(skillsDirectory, entry.name),
+			name: `${scope}-${entry.name}`
+		}));
+	}
+	return [];
+}
+/**
+* Installs a single skill by copying its source directory to the target
+* skills directory, updating the SKILL.md frontmatter name, and writing
+* a .gitignore.
+*
+* @param options - The install options.
+* @param options.source - The source directory containing the skill files.
+* @param options.name - The target skill name (used as directory name and frontmatter name).
+* @param options.targetBase - The base directory to install into (project root or home).
+*/
+function installSkill({ source, name, targetBase }) {
+	const targetDirectory = path.join(targetBase, SKILLS_DIRECTORY, name);
+	if (fs.existsSync(targetDirectory)) fs.rmSync(targetDirectory, { recursive: true });
+	fs.mkdirSync(path.dirname(targetDirectory), { recursive: true });
+	fs.cpSync(source, targetDirectory, { recursive: true });
+	const skillFile = path.join(targetDirectory, "SKILL.md");
+	if (fs.existsSync(skillFile)) {
+		const content = fs.readFileSync(skillFile, "utf8");
+		const data = parseFrontmatter(content);
+		data.name = name;
+		fs.writeFileSync(skillFile, writeFrontmatter(data, content));
+	}
+	makeScriptsExecutable(targetDirectory);
+	fs.writeFileSync(path.join(targetDirectory, ".gitignore"), "*\n");
+}
+/**
+* Recursively finds `.js` files that start with a shebang and makes them executable.
+*
+* @param directory - The directory to search for scripts.
+*/
+function makeScriptsExecutable(directory) {
+	const entries = fs.readdirSync(directory, { withFileTypes: true });
+	for (const entry of entries) {
+		const fullPath = path.join(directory, entry.name);
+		if (entry.isDirectory()) makeScriptsExecutable(fullPath);
+		else if (entry.name.endsWith(".js")) {
+			if (fs.readFileSync(fullPath, "utf8").startsWith("#!")) fs.chmodSync(fullPath, 493);
+		}
+	}
+}
+/**
+* Lists all installed skills in a given base directory by reading SKILL.md
+* frontmatter from each subdirectory in the skills directory.
+*
+* @param baseDirectory - The base directory to search (project root or home).
+* @returns An array of installed skill records.
+*/
+function listInstalledSkills(baseDirectory) {
+	const skillsDirectory = path.join(baseDirectory, SKILLS_DIRECTORY);
+	if (!fs.existsSync(skillsDirectory)) return [];
+	return fs.readdirSync(skillsDirectory, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => {
+		const skillFile = path.join(skillsDirectory, entry.name, "SKILL.md");
+		if (!fs.existsSync(skillFile)) return null;
+		const data = parseFrontmatter(fs.readFileSync(skillFile, "utf8"));
+		return {
+			name: data.name ?? entry.name,
+			description: data.description ?? "",
+			type: data.metadata?.type ?? "unknown",
+			location: skillFile
+		};
+	}).filter((skill) => skill !== null);
+}
+//#endregion
+//#region ../cli/dist/run-skills.js
+runMain(defineCommand({
+	meta: {
+		name: "skills",
+		description: "Manage skill packages"
+	},
+	subCommands: {
+		install: defineCommand({
+			meta: {
+				name: "install",
+				description: "Install skills from a package into the project"
+			},
+			args: {
+				source: {
+					type: "positional",
+					required: false,
+					description: "Path to the package containing skill(s). Defaults to the current directory."
+				},
+				target: {
+					type: "string",
+					required: false,
+					description: "Target directory to install skills into. Defaults to the project directory."
+				},
+				global: {
+					type: "boolean",
+					default: false,
+					description: "Install skills to the global directory (home) instead of the project"
+				}
+			},
+			run(context) {
+				const source = path.resolve(context.args.source || cwd());
+				const targetBase = context.args.global ? getGlobalDirectory() : context.args.target ? path.resolve(context.args.target) : getProjectDirectory();
+				if (!context.args.global && path.resolve(source) === path.resolve(targetBase)) {
+					const packageName = getPackageName(source);
+					console.warn(`[${packageName}] Skipping, running in own package`);
+					return;
+				}
+				if (detectSkillLayout(source) === "none") throw new Error(`No skill/ or skills/ directory found in "${source}"`);
+				const packageName = getPackageName(source);
+				const skills = getSkillSources(source, packageName);
+				const distScripts = path.join(source, "dist", "scripts");
+				const hasDistScripts = fs.existsSync(distScripts);
+				for (const skill of skills) {
+					installSkill({
+						source: skill.source,
+						name: skill.name,
+						targetBase
+					});
+					if (hasDistScripts) {
+						const targetScripts = path.join(targetBase, SKILLS_DIRECTORY, skill.name, "scripts");
+						fs.mkdirSync(targetScripts, { recursive: true });
+						fs.cpSync(distScripts, targetScripts, { recursive: true });
+						makeScriptsExecutable(targetScripts);
+					}
+					stdout.write(`[${packageName}] Installed skill "${skill.name}"\n`);
+				}
+			}
+		}),
+		list: defineCommand({
+			meta: {
+				name: "list",
+				description: "List installed skills"
+			},
+			args: {
+				type: {
+					type: "string",
+					required: false,
+					description: "Filter by skill type (e.g. \"technology\", \"workflow\")"
+				},
+				global: {
+					type: "boolean",
+					default: false,
+					description: "List globally installed skills instead of project-local"
+				}
+			},
+			run(context) {
+				let skills = listInstalledSkills(context.args.global ? getGlobalDirectory() : getProjectDirectory());
+				if (context.args.type) skills = skills.filter((skill) => skill.type === context.args.type);
+				if (skills.length === 0) {
+					stdout.write("No skills found\n");
+					return;
+				}
+				const nameWidth = Math.max(...skills.map((skill) => skill.name.length));
+				const typeWidth = Math.max(...skills.map((skill) => skill.type.length));
+				const lines = skills.map((skill) => {
+					return `${skill.name.padEnd(nameWidth)}  ${skill.type.padEnd(typeWidth)}  ${skill.description}`;
+				});
+				stdout.write(`${lines.join("\n")}\n`);
+			}
+		})
+	}
+}));
+//#endregion
+export {};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@fledge/workflow",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "author": "René Schapka",
   "license": "MIT",
   "files": [
+    "dist",
     "skills"
   ],
   "publishConfig": {
@@ -14,14 +15,18 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@fledge/cli": "^0.6.0"
+    "@fledge/cli": "^0.8.0"
   },
   "devDependencies": {
     "@antfu/eslint-config": "7.7.3",
-    "eslint": "10.1.0"
+    "@types/node": "25.3.0",
+    "eslint": "10.1.0",
+    "rolldown": "1.0.0-rc.12",
+    "typescript": "5.9.3"
   },
   "scripts": {
     "postinstall": "fledge skills install",
+    "build": "rolldown -c",
     "lint": "eslint . --fix"
   }
 }

package/skills/brief/SKILL.md

@@ -7,17 +7,37 @@ metadata:
   type: workflow
 ---
 
-All CLI commands below use `npx -y @fledge/cli` as the binary prefix (abbreviated as `fledge` in examples). Always use the full `npx -y @fledge/cli <command>` form when executing.
+## 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:
+
+- **`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 schema`** -- Output JSON Schema for brief and tasks frontmatter
 
 ## Step 0: Determine intent
 
 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.
+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.
 
-If unclear, run `npx -y @fledge/cli brief list` to show current briefs and ask.
+If unclear, run `scripts/brief.js list` to show current briefs and ask.
 
 ---
 
@@ -25,7 +45,7 @@ If unclear, run `npx -y @fledge/cli brief list` to show current briefs and ask.
 
 Before writing anything, build an understanding of what exists.
 
-1. Run `npx -y @fledge/cli brief list --status completed` to read summaries of completed features. Note anything relevant to the new feature.
+1. Run `scripts/brief.js list --status completed` 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?
@@ -40,9 +60,9 @@ Proceed to Step 2.
 
 ## Step 2: Draft the brief
 
-Run `npx -y @fledge/cli brief create <name>` to create the brief directory.
+Run `scripts/brief.js create <name>` to create the brief directory.
 
-Write the brief content into `brief.md`. The frontmatter is managed by the CLI. The markdown body should capture:
+Write the brief content into `brief.md`. The frontmatter is managed by the scripts. The markdown body should capture:
 
 - **What**: the user-facing change in one or two sentences
 - **Why**: the motivation or problem being solved
@@ -76,7 +96,7 @@ tasks:
 
 Order tasks by dependency: tasks that others depend on come first within their group.
 
-After writing tasks, run `npx -y @fledge/cli brief validate <name>` to confirm the brief is valid, then run `npx -y @fledge/cli brief start <name>` to transition to active.
+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.
 
 Present the complete brief and task list to the user for review before starting.
 
@@ -84,22 +104,22 @@ Present the complete brief and task list to the user for review before starting.
 
 ## Step 4: Continue a brief
 
-Run `npx -y @fledge/cli brief list` to show all briefs. If the user does not specify which brief, ask them to pick one.
+Run `scripts/brief.js list` to show all briefs. If the user does not specify which brief, ask them to pick one.
 
-Run `npx -y @fledge/cli brief status <name>` to show progress. Read the brief and tasks files to understand the full context.
+Run `scripts/brief.js status <name>` 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
+- **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 `npx -y @fledge/cli brief status <name>` to confirm the update.
+When updating task status, modify the `tasks.md` frontmatter directly, then run `scripts/brief.js status <name>` to confirm the update.
 
 ---
 
 ## Step 5: Complete a brief
 
-Run `npx -y @fledge/cli brief status <name>` to verify all tasks are done.
+Run `scripts/brief.js status <name>` 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)
@@ -110,4 +130,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 `npx -y @fledge/cli brief complete <name>` to transition to completed. The CLI validates that all tasks are done and the summary is present.
+Run `scripts/brief.js complete <name>` to transition to completed. The script validates that all tasks are done and the summary is present.