@opellen/scaff 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opellen/scaff",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Agile, goal-centric AI harness. Just markdown.",
   "type": "module",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "@inquirer/core": "^11.1.7",
     "@inquirer/prompts": "^8.3.2",
     "chalk": "^5.6.2",
+    "scaff": "^0.0.4",
     "yaml": "^2.8.3"
   }
 }

package/templates/commands/go.md

@@ -31,7 +31,7 @@ tags: [workflow, scaff, go]
    - (PLAN.md absent, task complexity ≥ multi-file) => generate PLAN.md, then report: `"Created [PLAN.md]($DocsDir/PLAN.md)."`
    - (PLAN.md absent, task complexity < multi-file) => proceed without PLAN.md
 5. Execute tasks using the Task Outcome loop below.
-6. After multiple tasks completed, suggest `/scaff:goal checkpoint` to save progress.
+6. Suggest `/scaff:goal checkpoint` only per the checkpoint triggers in the `scaff-flow` skill (platform context-pressure signal, or user pause/session end) — never on task count or goal completion.
 
 ## Task Outcome
 

package/templates/skills/scaff-flow/SKILL.md

@@ -73,10 +73,14 @@ When the trigger fires:
 
 ## Checkpoint Triggers
 
-- (analysis/exploration session getting long, compact approaching) => suggest `/scaff:goal checkpoint`
-- (context window approaching 80% capacity, if platform supports detection) => suggest `/scaff:goal checkpoint`
-- (sequential analysis of multiple functions/modules, intermediate results accumulating) => suggest `/scaff:goal checkpoint`
-- (before ending a session) => suggest `/scaff:goal checkpoint`
+A checkpoint exists to survive context loss (compaction) *mid-goal*. Only two things justify suggesting one:
+
+1. (platform surfaces a compaction-imminent / auto-compact / context-limit notice, or exposes actual context-usage figures nearing the limit — e.g. an injected system warning) => suggest `/scaff:goal checkpoint` NOW. This is the only reliable context-pressure signal. Never estimate your own context % or infer pressure from how long the session "feels" — that estimate tracks turn count, not tokens, and misfires early.
+2. (user explicitly asks to save/pause, or is ending the session) => suggest `/scaff:goal checkpoint`.
+
+On platforms that inject no warning, rule 2 is the only trigger — this is intentional: GOAL.md checkboxes and docs/logs already persist state as work completes, so a missed checkpoint is cheap.
+
+> Do NOT suggest a checkpoint on task count, milestone/goal completion, or a sense that the session has "grown long." At goal completion the right move is `/scaff:goal archive`, not a checkpoint. When in doubt, stay silent.
 
 ## Blocker Handling
 

package/dist/cli.d.ts

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-export {};

package/dist/cli.js

@@ -1,235 +0,0 @@
-#!/usr/bin/env node
-import { resolve } from "node:path";
-import { existsSync } from "node:fs";
-import { install, dryRun } from "./installer.js";
-import { PLATFORM_IDS, DEFAULT_PLATFORM, isValidPlatform, detectInstalledPlatforms } from "./platforms/index.js";
-import { showWelcome } from "./ui/welcome.js";
-import { selectPlatforms } from "./prompts/platform-select.js";
-import { t } from "./i18n/index.js";
-import chalk from "chalk";
-import { brand } from "./ui/colors.js";
-import { extend } from "./extend.js";
-function printUsage() {
-    console.log(`
-scaff — Lightweight context scaffolding for AI coding
-
-Usage:
-  scaff init [options]
-  scaff extend <path> [--force] [--root <dir>]
-
-Options:
-  --docs <dir>      Documentation directory (default: docs)
-  --codebase <dir>  Codebase directory (default: .)
-  --tools <list>    Target platforms: comma-separated, or "all" (default: claude)
-                    Available: ${PLATFORM_IDS.join(", ")}
-  --no-subagent     Disable subagent delegation (enabled by default)
-  --root <dir>      Target directory (default: cwd)
-  --force           Overwrite existing files without prompting
-  -y, --yes         Auto-confirm with detected platforms (skip interactive selection)
-  --dry-run         Preview without writing files
-  -h, --help        Show this help
-
-Commands:
-  init              Install scaff into the current project
-  extend <path>     Install a local extension (reads <path>/scaff-extend.yml)
-`);
-}
-function parseArgs(argv) {
-    let command = null;
-    const positional = [];
-    let docsDir = "docs";
-    let codebaseDir = ".";
-    let tools = null;
-    let subagent = true;
-    let root = process.cwd();
-    let force = false;
-    let yes = false;
-    let isDryRun = false;
-    let help = false;
-    for (let i = 0; i < argv.length; i++) {
-        const arg = argv[i];
-        if (arg === "-h" || arg === "--help") {
-            help = true;
-        }
-        else if (arg === "--docs") {
-            const next = argv[++i];
-            if (!next) {
-                console.error("Error: --docs requires a directory path");
-                process.exit(1);
-            }
-            docsDir = next;
-        }
-        else if (arg === "--codebase") {
-            const next = argv[++i];
-            if (!next) {
-                console.error("Error: --codebase requires a directory path");
-                process.exit(1);
-            }
-            codebaseDir = next;
-        }
-        else if (arg === "--tools") {
-            const next = argv[++i];
-            if (!next) {
-                console.error("Error: --tools requires a platform list");
-                process.exit(1);
-            }
-            if (next === "all") {
-                tools = [...PLATFORM_IDS];
-            }
-            else {
-                tools = next.split(",").map((id) => id.trim());
-                for (const id of tools) {
-                    if (!isValidPlatform(id)) {
-                        console.error(`Error: unknown platform "${id}". Available: ${PLATFORM_IDS.join(", ")}`);
-                        process.exit(1);
-                    }
-                }
-            }
-        }
-        else if (arg === "--no-subagent") {
-            subagent = false;
-        }
-        else if (arg === "--force") {
-            force = true;
-        }
-        else if (arg === "-y" || arg === "--yes") {
-            yes = true;
-        }
-        else if (arg === "--dry-run") {
-            isDryRun = true;
-        }
-        else if (arg === "--root") {
-            const next = argv[++i];
-            if (!next) {
-                console.error("Error: --root requires a directory path");
-                process.exit(1);
-            }
-            root = resolve(next);
-        }
-        else if (!arg.startsWith("-")) {
-            if (command === null) {
-                command = arg;
-            }
-            else {
-                positional.push(arg);
-            }
-        }
-        else {
-            console.error(`Unknown option: ${arg}`);
-            printUsage();
-            process.exit(1);
-        }
-    }
-    return { command, positional, docsDir, codebaseDir, tools, subagent, root, force, yes, dryRun: isDryRun, help };
-}
-async function runExtend(args) {
-    const extPath = args.positional[0];
-    if (!extPath) {
-        console.error("Error: scaff extend requires a path argument");
-        printUsage();
-        process.exit(1);
-    }
-    const resolvedExt = resolve(extPath);
-    if (!existsSync(resolvedExt)) {
-        console.error(`Error: extension path does not exist: ${resolvedExt}`);
-        process.exit(1);
-    }
-    if (!existsSync(args.root)) {
-        console.error(`Error: target directory does not exist: ${args.root}`);
-        process.exit(1);
-    }
-    try {
-        const result = await extend(resolvedExt, {
-            force: args.force,
-            root: args.root,
-        });
-        if (result.commandsAdded.length > 0) {
-            console.log(`${chalk.green("\u2713")} Commands added: ${result.commandsAdded.join(", ")}`);
-        }
-        if (result.commandsSkipped.length > 0) {
-            console.log(`${chalk.yellow("~")} Commands skipped: ${result.commandsSkipped.join(", ")}`);
-        }
-        if (result.hooksApplied.length > 0) {
-            console.log(`${chalk.green("\u2713")} Hooks applied: ${result.hooksApplied.join(", ")}`);
-        }
-        if (result.dependenciesChecked.length > 0) {
-            console.log(`${chalk.green("\u2713")} Dependencies: all found`);
-        }
-        process.exit(0);
-    }
-    catch (err) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
-    }
-}
-async function main() {
-    const args = parseArgs(process.argv.slice(2));
-    if (args.help || !args.command) {
-        printUsage();
-        process.exit(args.help ? 0 : 1);
-    }
-    if (args.command === "extend") {
-        await runExtend(args);
-        return;
-    }
-    if (args.command !== "init") {
-        console.error(`Unknown command: ${args.command}`);
-        printUsage();
-        process.exit(1);
-    }
-    if (!existsSync(args.root)) {
-        console.error(`Error: target directory does not exist: ${args.root}`);
-        process.exit(1);
-    }
-    let tools;
-    if (args.tools) {
-        tools = args.tools;
-    }
-    else if (args.yes) {
-        const detected = detectInstalledPlatforms(args.root);
-        tools = detected.length > 0 ? detected : [DEFAULT_PLATFORM];
-        console.log(chalk.dim(`Auto-selected: ${tools.join(", ")}`));
-    }
-    else if (process.stdin.isTTY && !args.dryRun) {
-        await showWelcome();
-        tools = await selectPlatforms(args.root);
-    }
-    else {
-        tools = [DEFAULT_PLATFORM];
-    }
-    const config = {
-        tools,
-        subagent: args.subagent,
-        root: args.root,
-        docsDir: args.docsDir,
-        codebaseDir: args.codebaseDir,
-        force: args.force,
-    };
-    if (args.dryRun) {
-        const result = dryRun(config);
-        console.log(t("cli.dryRun") + "\n");
-        for (const file of result.files) {
-            console.log(`  ${chalk.green("+")} ${file}`);
-        }
-        return;
-    }
-    const result = await install(config);
-    console.log(t("cli.complete") + "\n");
-    if (result.files.length > 0) {
-        console.log(t("cli.installed"));
-        for (const file of result.files) {
-            console.log(`  ${chalk.green("+")} ${file}`);
-        }
-    }
-    if (result.skipped.length > 0) {
-        console.log("\n" + t("cli.skipped"));
-        for (const file of result.skipped) {
-            console.log(`  ${chalk.yellow("~")} ${file}`);
-        }
-    }
-    console.log("\n" + brand(t("cli.nextSteps")));
-    console.log("  " + chalk.dim("1.") + " " + t("cli.step1"));
-    console.log("  " + chalk.dim("2.") + " " + t("cli.step2").replace("{cmd}", brand("/scaff:scout")));
-    process.exit(0);
-}
-main();

package/dist/extend.d.ts

@@ -1,12 +0,0 @@
-export interface ExtendOptions {
-    force: boolean;
-    root: string;
-}
-export type PromptFn = (question: string) => Promise<string>;
-export interface ExtendResult {
-    commandsAdded: string[];
-    commandsSkipped: string[];
-    hooksApplied: string[];
-    dependenciesChecked: string[];
-}
-export declare function extend(extensionPath: string, opts: ExtendOptions, promptFn?: PromptFn): Promise<ExtendResult>;

package/dist/extend.js

@@ -1,242 +0,0 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, } from "node:fs";
-import { join, dirname, isAbsolute, resolve } from "node:path";
-import { execSync } from "node:child_process";
-import { createInterface } from "node:readline";
-import { parse as parseYaml } from "yaml";
-import { injectHooks } from "./hook-parser.js";
-function createDefaultPrompt() {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let closed = false;
-    rl.on("close", () => {
-        closed = true;
-    });
-    const prompt = (question) => {
-        if (closed)
-            return Promise.resolve("");
-        return new Promise((resolveP) => {
-            rl.question(question, (answer) => {
-                resolveP(answer.trim().toLowerCase());
-            });
-            rl.once("close", () => resolveP(""));
-        });
-    };
-    return { prompt, close: () => rl.close() };
-}
-function readManifest(extensionPath) {
-    const manifestPath = join(extensionPath, "scaff-extend.yml");
-    if (!existsSync(manifestPath)) {
-        throw new Error(`Missing scaff-extend.yml at ${manifestPath}`);
-    }
-    const raw = readFileSync(manifestPath, "utf-8");
-    let parsed;
-    try {
-        parsed = parseYaml(raw);
-    }
-    catch (err) {
-        throw new Error(`Failed to parse scaff-extend.yml: ${err.message}`);
-    }
-    if (!parsed || typeof parsed !== "object") {
-        throw new Error("scaff-extend.yml must be a YAML mapping");
-    }
-    return validateManifest(parsed);
-}
-function validateManifest(raw) {
-    if (typeof raw.name !== "string" || !raw.name) {
-        throw new Error("scaff-extend.yml: 'name' is required");
-    }
-    if (typeof raw.extends !== "string" || !raw.extends) {
-        throw new Error("scaff-extend.yml: 'extends' is required");
-    }
-    if (raw.extends !== "scaff") {
-        throw new Error(`scaff-extend.yml: 'extends' must be "scaff" (got "${raw.extends}"). Extension chains are not supported yet.`);
-    }
-    const commands = [];
-    if (raw.commands !== undefined) {
-        if (!Array.isArray(raw.commands)) {
-            throw new Error("scaff-extend.yml: 'commands' must be a list");
-        }
-        for (const c of raw.commands) {
-            if (typeof c !== "string" || !c) {
-                throw new Error("scaff-extend.yml: each command must be a non-empty string");
-            }
-            commands.push(c);
-        }
-    }
-    const hooks = [];
-    if (raw.hooks !== undefined) {
-        if (!Array.isArray(raw.hooks)) {
-            throw new Error("scaff-extend.yml: 'hooks' must be a list");
-        }
-        for (const h of raw.hooks) {
-            if (!h || typeof h !== "object") {
-                throw new Error("scaff-extend.yml: each hook must be a mapping");
-            }
-            const hook = h;
-            if (typeof hook.id !== "string" || !hook.id) {
-                throw new Error("scaff-extend.yml: hook 'id' is required");
-            }
-            if (typeof hook.target !== "string" || !hook.target) {
-                throw new Error(`scaff-extend.yml: hook '${hook.id}' missing 'target'`);
-            }
-            const hasContent = hook.content !== undefined;
-            const hasFile = hook.file !== undefined;
-            if (hasContent && hasFile) {
-                throw new Error(`scaff-extend.yml: hook '${hook.id}' cannot have both 'content' and 'file'`);
-            }
-            if (!hasContent && !hasFile) {
-                throw new Error(`scaff-extend.yml: hook '${hook.id}' must have either 'content' or 'file'`);
-            }
-            if (hasContent && typeof hook.content !== "string") {
-                throw new Error(`scaff-extend.yml: hook '${hook.id}' 'content' must be a string`);
-            }
-            if (hasFile && typeof hook.file !== "string") {
-                throw new Error(`scaff-extend.yml: hook '${hook.id}' 'file' must be a string`);
-            }
-            hooks.push({
-                id: hook.id,
-                target: hook.target,
-                content: hasContent ? hook.content : undefined,
-                file: hasFile ? hook.file : undefined,
-            });
-        }
-    }
-    const dependencies = [];
-    if (raw.dependencies !== undefined) {
-        if (!Array.isArray(raw.dependencies)) {
-            throw new Error("scaff-extend.yml: 'dependencies' must be a list");
-        }
-        for (const d of raw.dependencies) {
-            if (!d || typeof d !== "object") {
-                throw new Error("scaff-extend.yml: each dependency must be a mapping");
-            }
-            const dep = d;
-            if (typeof dep.name !== "string" || !dep.name) {
-                throw new Error("scaff-extend.yml: dependency 'name' is required");
-            }
-            if (typeof dep.check !== "string" || !dep.check) {
-                throw new Error(`scaff-extend.yml: dependency '${dep.name}' missing 'check'`);
-            }
-            dependencies.push({ name: dep.name, check: dep.check });
-        }
-    }
-    return {
-        name: raw.name,
-        version: typeof raw.version === "string" ? raw.version : undefined,
-        extends: raw.extends,
-        requires: typeof raw.requires === "string" ? raw.requires : undefined,
-        commands,
-        hooks,
-        dependencies,
-    };
-}
-function checkDependencies(deps) {
-    for (const dep of deps) {
-        try {
-            execSync(dep.check, { stdio: "ignore" });
-        }
-        catch {
-            throw new Error(`Dependency '${dep.name}' not found (check: ${dep.check})`);
-        }
-    }
-}
-function commandTargetPath(root, name) {
-    return join(root, ".claude", "commands", "scaff", `${name}.md`);
-}
-function resolveWithinExtension(extensionPath, relPath) {
-    if (isAbsolute(relPath))
-        return relPath;
-    return resolve(extensionPath, relPath);
-}
-async function copyCommands(extensionPath, commands, root, force, ask) {
-    const copied = [];
-    const skipped = [];
-    let forceAll = force;
-    for (const name of commands) {
-        const src = join(extensionPath, "commands", `${name}.md`);
-        if (!existsSync(src)) {
-            throw new Error(`Missing command source file: ${src}`);
-        }
-        const dst = commandTargetPath(root, name);
-        if (existsSync(dst) && !forceAll) {
-            const answer = await ask(`File exists: ${dst}. Overwrite? (y/n/a) `);
-            if (answer === "a" || answer === "all") {
-                forceAll = true;
-            }
-            else if (answer !== "y" && answer !== "yes") {
-                skipped.push(name);
-                continue;
-            }
-        }
-        const dir = dirname(dst);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        const content = readFileSync(src, "utf-8");
-        writeFileSync(dst, content, "utf-8");
-        copied.push(name);
-    }
-    return { copied, skipped };
-}
-function applyHooks(extensionPath, hooks, root) {
-    const applied = [];
-    const byTarget = new Map();
-    for (const hook of hooks) {
-        const list = byTarget.get(hook.target) ?? [];
-        list.push(hook);
-        byTarget.set(hook.target, list);
-    }
-    for (const [target, specs] of byTarget) {
-        const targetPath = isAbsolute(target) ? target : join(root, target);
-        if (!existsSync(targetPath)) {
-            throw new Error(`Hook target file not found: ${targetPath}`);
-        }
-        const original = readFileSync(targetPath, "utf-8");
-        const entries = specs.map((spec) => {
-            let content;
-            if (spec.content !== undefined) {
-                content = spec.content;
-            }
-            else {
-                const filePath = resolveWithinExtension(extensionPath, spec.file);
-                if (!existsSync(filePath)) {
-                    throw new Error(`Hook '${spec.id}' file not found: ${filePath}`);
-                }
-                content = readFileSync(filePath, "utf-8");
-            }
-            // Strip trailing newline so injected content fits cleanly between markers.
-            if (content.endsWith("\n")) {
-                content = content.slice(0, -1);
-            }
-            return { id: spec.id, content };
-        });
-        const next = injectHooks(original, entries);
-        writeFileSync(targetPath, next, "utf-8");
-        for (const spec of specs)
-            applied.push(spec.id);
-    }
-    return applied;
-}
-export async function extend(extensionPath, opts, promptFn) {
-    if (!existsSync(extensionPath)) {
-        throw new Error(`Extension path does not exist: ${extensionPath}`);
-    }
-    const manifest = readManifest(extensionPath);
-    const deps = manifest.dependencies ?? [];
-    checkDependencies(deps);
-    const defaultPrompt = promptFn ? null : createDefaultPrompt();
-    const ask = promptFn ?? defaultPrompt.prompt;
-    let copyResult;
-    try {
-        copyResult = await copyCommands(extensionPath, manifest.commands ?? [], opts.root, opts.force, ask);
-    }
-    finally {
-        defaultPrompt?.close();
-    }
-    const hooksApplied = applyHooks(extensionPath, manifest.hooks ?? [], opts.root);
-    return {
-        commandsAdded: copyResult.copied,
-        commandsSkipped: copyResult.skipped,
-        hooksApplied,
-        dependenciesChecked: deps.map((d) => d.name),
-    };
-}

package/dist/hook-parser.d.ts

@@ -1,15 +0,0 @@
-export interface HookEntry {
-    id: string;
-    content: string;
-}
-/**
- * Validate that a file has properly paired hook markers.
- * Returns list of hook ids found.
- */
-export declare function findHookPoints(fileContent: string): string[];
-/**
- * Inject hook content into a file's text.
- * Returns the modified text.
- * Throws on errors (missing markers, mismatched pairs, non-empty hooks).
- */
-export declare function injectHooks(fileContent: string, hooks: HookEntry[]): string;

package/dist/hook-parser.js

@@ -1,95 +0,0 @@
-const HOOK_BEGIN = /^\s*<!--\s*@hook\s+(\S+)\s*-->/;
-const HOOK_END = /^\s*<!--\s*@end-hook\s+(\S+)\s*-->/;
-/**
- * Validate that a file has properly paired hook markers.
- * Returns list of hook ids found.
- */
-export function findHookPoints(fileContent) {
-    const ids = [];
-    const lines = fileContent.split("\n");
-    let openId = null;
-    for (const line of lines) {
-        const beginMatch = line.match(HOOK_BEGIN);
-        const endMatch = line.match(HOOK_END);
-        if (beginMatch) {
-            if (openId !== null) {
-                throw new Error(`Unclosed hook '${openId}'`);
-            }
-            openId = beginMatch[1];
-        }
-        else if (endMatch) {
-            const endId = endMatch[1];
-            if (openId === null) {
-                throw new Error(`Unexpected hook end '${endId}'`);
-            }
-            if (endId !== openId) {
-                throw new Error(`Mismatched hook end: expected '${openId}', got '${endId}'`);
-            }
-            ids.push(openId);
-            openId = null;
-        }
-    }
-    if (openId !== null) {
-        throw new Error(`Unclosed hook '${openId}'`);
-    }
-    return ids;
-}
-/**
- * Inject hook content into a file's text.
- * Returns the modified text.
- * Throws on errors (missing markers, mismatched pairs, non-empty hooks).
- */
-export function injectHooks(fileContent, hooks) {
-    if (hooks.length === 0) {
-        return fileContent;
-    }
-    const lines = fileContent.split("\n");
-    const result = [];
-    const injected = new Set();
-    const hookMap = new Map(hooks.map((h) => [h.id, h.content]));
-    let openId = null;
-    let openLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const beginMatch = line.match(HOOK_BEGIN);
-        const endMatch = line.match(HOOK_END);
-        if (beginMatch) {
-            if (openId !== null) {
-                throw new Error(`Unclosed hook '${openId}'`);
-            }
-            openId = beginMatch[1];
-            openLine = i;
-            result.push(line);
-        }
-        else if (endMatch) {
-            const endId = endMatch[1];
-            if (openId === null) {
-                throw new Error(`Unexpected hook end '${endId}'`);
-            }
-            if (endId !== openId) {
-                throw new Error(`Mismatched hook end: expected '${openId}', got '${endId}'`);
-            }
-            if (i !== openLine + 1) {
-                throw new Error(`Hook '${openId}' already has content`);
-            }
-            if (hookMap.has(openId)) {
-                result.push(hookMap.get(openId));
-                injected.add(openId);
-            }
-            result.push(line);
-            openId = null;
-        }
-        else {
-            result.push(line);
-        }
-    }
-    if (openId !== null) {
-        throw new Error(`Unclosed hook '${openId}'`);
-    }
-    for (const hook of hooks) {
-        if (!injected.has(hook.id)) {
-            throw new Error(`Hook point '${hook.id}' not found in file`);
-        }
-    }
-    return result.join("\n");
-}

package/dist/i18n/index.d.ts

@@ -1,5 +0,0 @@
-import { type Locale, type MessageKey } from "./messages.js";
-export declare function getLocale(): Locale;
-export declare function setLocale(locale: Locale): void;
-export declare function t(key: MessageKey): string;
-export type { Locale, MessageKey };

package/dist/i18n/index.js

@@ -1,20 +0,0 @@
-import { messages } from "./messages.js";
-function detectLocale() {
-    const raw = process.env.LC_ALL ||
-        process.env.LC_MESSAGES ||
-        process.env.LANG ||
-        "";
-    if (raw.startsWith("ko"))
-        return "ko";
-    return "en";
-}
-let current = detectLocale();
-export function getLocale() {
-    return current;
-}
-export function setLocale(locale) {
-    current = locale;
-}
-export function t(key) {
-    return messages[current][key];
-}