@opellen/scaff 0.1.14 → 0.1.16

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 San
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -75,6 +75,7 @@ docs/
 ├── DESIGN.md        ← 구현 설계 (필요 시)
 ├── PLAN.md          ← 구현 계획 (복잡한 태스크에서 자동 생성)
 ├── ROADMAP.md       ← 마일스톤 단위 전체 계획
+├── BACKLOG.md       ← 범위 밖 발견 사항 보관
 ├── OVERVIEW.md      ← 프로젝트 전체 조망 (필요 시)
 └── suspended/       ← 중단된 목표
 ```
@@ -87,6 +88,7 @@ docs/
 | `DESIGN.md` | 어떻게 구현하지? | 목표 달성까지 |
 | `PLAN.md` | 이 태스크를 어떻게 구현하지? | 자동 생성 → 자동 아카이브 |
 | `ROADMAP.md` | 큰 그림에서 어디에 있지? | 프로젝트 전체 |
+| `BACKLOG.md` | 발견했지만 미뤄둔 건 뭐지? | 프로젝트 전체 |
 | `OVERVIEW.md` | 이 프로젝트 전체를 한눈에 보면? | 프로젝트 전체 |
 
 `GOAL.md` 하나로 시작해서 `ROADMAP.md`로 확장해도 되고, `ROADMAP.md`에서 큰 그림을 잡고 `GOAL.md`로 내려와도 됩니다. 어느 방향으로 가든 Scaff는 '지금 할 일'을 마크다운 위에 유지합니다.

package/README.md

@@ -74,6 +74,7 @@ docs/
 ├── DESIGN.md        ← Implementation design (as needed)
 ├── PLAN.md          ← Implementation plan (auto-generated for complex tasks)
 ├── ROADMAP.md       ← Milestone-based overall plan
+├── BACKLOG.md       ← Deferred out-of-scope discoveries
 ├── OVERVIEW.md      ← Full project overview (as needed)
 └── suspended/       ← Suspended goals
 ```
@@ -86,6 +87,7 @@ docs/
 | `DESIGN.md` | How do I implement this? | Until goal is achieved |
 | `PLAN.md` | How do I implement this task? | Auto-generated → auto-archived |
 | `ROADMAP.md` | Where am I in the big picture? | Project lifetime |
+| `BACKLOG.md` | What did I discover but defer? | Project lifetime |
 | `OVERVIEW.md` | What does this whole project look like? | Project lifetime |
 
 Start with just `GOAL.md` and expand to `ROADMAP.md`, or lay out the big picture in `ROADMAP.md` and drill down to `GOAL.md`. Either way, Scaff keeps "what to do now" visible on markdown.

package/dist/agents-partial.d.ts

@@ -0,0 +1,2 @@
+import type { ScaffConfig } from "./templates.js";
+export declare function generateAgentsPartial(config: ScaffConfig): string;

package/dist/platforms.d.ts

@@ -0,0 +1,20 @@
+export interface CommandMeta {
+    name: string;
+    description: string;
+}
+export interface PlatformAdapter {
+    id: string;
+    displayName: string;
+    configDir: string;
+    fileExtension: string;
+    commandPath(name: string): string;
+    skillPath(name: string): string;
+    wrapContent(content: string, meta: CommandMeta): string;
+}
+export declare const DEFAULT_PLATFORM = "claude";
+export declare const PLATFORM_IDS: readonly ["claude", "cursor", "windsurf", "cline", "codex", "github-copilot", "continue", "amazon-q", "antigravity", "auggie", "codebuddy", "costrict", "crush", "factory", "gemini", "iflow", "kilocode", "kiro", "opencode", "pi", "qoder", "qwen", "roocode", "trae"];
+export type PlatformId = typeof PLATFORM_IDS[number];
+export declare function isValidPlatform(id: string): id is PlatformId;
+export declare function getAdapter(id: string): PlatformAdapter | undefined;
+export declare function getAdapters(ids: string[]): PlatformAdapter[];
+export declare function getAllAdapters(): PlatformAdapter[];

package/dist/platforms.js

@@ -0,0 +1,139 @@
+export const DEFAULT_PLATFORM = "claude";
+function stripFrontmatter(content) {
+    const match = content.match(/^---\n[\s\S]*?\n---\n/);
+    return match ? content.slice(match[0].length) : content;
+}
+function yamlFrontmatter(fields) {
+    const lines = Object.entries(fields).map(([k, v]) => `${k}: "${v}"`);
+    return `---\n${lines.join("\n")}\n---\n`;
+}
+function makeSkillPath(skillsDir, name) {
+    return `${skillsDir}/skills/${name}/SKILL.md`;
+}
+function descOnlyAdapter(id, displayName, skillsDir, pathFn, ext = ".md") {
+    return {
+        id,
+        displayName,
+        configDir: pathFn("_").split("/")[0],
+        fileExtension: ext,
+        commandPath: pathFn,
+        skillPath: (name) => makeSkillPath(skillsDir, name),
+        wrapContent: (content, meta) => {
+            const body = stripFrontmatter(content);
+            const fm = yamlFrontmatter({ description: meta.description });
+            return fm + body;
+        },
+    };
+}
+function nameDescAdapter(id, displayName, skillsDir, pathFn, namePrefix, ext = ".md") {
+    return {
+        id,
+        displayName,
+        configDir: pathFn("_").split("/")[0],
+        fileExtension: ext,
+        commandPath: pathFn,
+        skillPath: (name) => makeSkillPath(skillsDir, name),
+        wrapContent: (content, meta) => {
+            const body = stripFrontmatter(content);
+            const fm = yamlFrontmatter({
+                name: `${namePrefix}${meta.name}`,
+                description: meta.description,
+            });
+            return fm + body;
+        },
+    };
+}
+function markdownHeaderAdapter(id, displayName, skillsDir, pathFn) {
+    return {
+        id,
+        displayName,
+        configDir: pathFn("_").split("/")[0],
+        fileExtension: ".md",
+        commandPath: pathFn,
+        skillPath: (name) => makeSkillPath(skillsDir, name),
+        wrapContent: (content, meta) => {
+            const body = stripFrontmatter(content);
+            return `# scaff-${meta.name}\n\n${meta.description}\n\n${body}`;
+        },
+    };
+}
+const claude = {
+    id: "claude",
+    displayName: "Claude Code",
+    configDir: ".claude",
+    fileExtension: ".md",
+    commandPath: (name) => `.claude/commands/scaff/${name}.md`,
+    skillPath: (name) => makeSkillPath(".claude", name),
+    wrapContent: (content, _meta) => content,
+};
+const cursor = nameDescAdapter("cursor", "Cursor", ".cursor", (name) => `.cursor/commands/scaff-${name}.md`, "/scaff-");
+const windsurf = nameDescAdapter("windsurf", "Windsurf", ".windsurf", (name) => `.windsurf/workflows/scaff-${name}.md`, "scaff-");
+const cline = markdownHeaderAdapter("cline", "Cline", ".cline", (name) => `.clinerules/workflows/scaff-${name}.md`);
+const codex = {
+    id: "codex",
+    displayName: "Codex",
+    configDir: ".codex",
+    fileExtension: ".md",
+    commandPath: (name) => `.codex/skills/scaff-${name}/SKILL.md`,
+    skillPath: (name) => makeSkillPath(".codex", name),
+    wrapContent: (content, _meta) => content,
+};
+const githubCopilot = descOnlyAdapter("github-copilot", "GitHub Copilot", ".github", (name) => `.github/prompts/scaff-${name}.prompt.md`, ".prompt.md");
+const continueAdapter = nameDescAdapter("continue", "Continue", ".continue", (name) => `.continue/prompts/scaff-${name}.prompt`, "scaff-", ".prompt");
+const amazonQ = descOnlyAdapter("amazon-q", "Amazon Q Developer", ".amazonq", (name) => `.amazonq/prompts/scaff-${name}.md`);
+const antigravity = descOnlyAdapter("antigravity", "Antigravity", ".agent", (name) => `.agent/workflows/scaff-${name}.md`);
+const auggie = descOnlyAdapter("auggie", "Augment CLI", ".augment", (name) => `.augment/commands/scaff-${name}.md`);
+const codebuddy = nameDescAdapter("codebuddy", "CodeBuddy", ".codebuddy", (name) => `.codebuddy/commands/scaff/${name}.md`, "scaff:");
+const costrict = descOnlyAdapter("costrict", "CoStrict", ".cospec", (name) => `.cospec/openspec/commands/scaff-${name}.md`);
+const crush = nameDescAdapter("crush", "Crush", ".crush", (name) => `.crush/commands/scaff/${name}.md`, "scaff:");
+const factory = descOnlyAdapter("factory", "Factory Droid", ".factory", (name) => `.factory/commands/scaff-${name}.md`);
+const gemini = descOnlyAdapter("gemini", "Gemini CLI", ".gemini", (name) => `.gemini/commands/scaff/${name}.md`);
+const iflow = nameDescAdapter("iflow", "iFlow", ".iflow", (name) => `.iflow/commands/scaff-${name}.md`, "/scaff-");
+const kilocode = {
+    id: "kilocode",
+    displayName: "Kilo Code",
+    configDir: ".kilocode",
+    fileExtension: ".md",
+    commandPath: (name) => `.kilocode/workflows/scaff-${name}.md`,
+    skillPath: (name) => makeSkillPath(".kilocode", name),
+    wrapContent: (content, _meta) => stripFrontmatter(content),
+};
+const kiro = descOnlyAdapter("kiro", "Kiro", ".kiro", (name) => `.kiro/prompts/scaff-${name}.prompt.md`, ".prompt.md");
+const opencode = descOnlyAdapter("opencode", "OpenCode", ".opencode", (name) => `.opencode/commands/scaff-${name}.md`);
+const pi = descOnlyAdapter("pi", "Pi", ".pi", (name) => `.pi/prompts/scaff-${name}.md`);
+const qoder = nameDescAdapter("qoder", "Qoder", ".qoder", (name) => `.qoder/commands/scaff/${name}.md`, "scaff:");
+const qwen = descOnlyAdapter("qwen", "Qwen Code", ".qwen", (name) => `.qwen/commands/scaff-${name}.md`);
+const roocode = markdownHeaderAdapter("roocode", "RooCode", ".roo", (name) => `.roo/commands/scaff-${name}.md`);
+const trae = descOnlyAdapter("trae", "Trae", ".trae", (name) => `.trae/commands/scaff-${name}.md`);
+const ALL_ADAPTERS = [
+    claude, cursor, windsurf, cline, codex, githubCopilot, continueAdapter,
+    amazonQ, antigravity, auggie, codebuddy, costrict, crush, factory,
+    gemini, iflow, kilocode, kiro, opencode, pi, qoder, qwen, roocode, trae,
+];
+const ADAPTER_MAP = new Map(ALL_ADAPTERS.map((a) => [a.id, a]));
+if (ADAPTER_MAP.size !== ALL_ADAPTERS.length)
+    throw new Error("duplicate adapter id");
+export const PLATFORM_IDS = [
+    "claude", "cursor", "windsurf", "cline", "codex", "github-copilot", "continue",
+    "amazon-q", "antigravity", "auggie", "codebuddy", "costrict", "crush", "factory",
+    "gemini", "iflow", "kilocode", "kiro", "opencode", "pi", "qoder", "qwen", "roocode", "trae",
+];
+if (PLATFORM_IDS.length !== ALL_ADAPTERS.length)
+    throw new Error("PLATFORM_IDS out of sync");
+export function isValidPlatform(id) {
+    return ADAPTER_MAP.has(id);
+}
+export function getAdapter(id) {
+    return ADAPTER_MAP.get(id);
+}
+export function getAdapters(ids) {
+    return ids.map((id) => {
+        const adapter = ADAPTER_MAP.get(id);
+        if (!adapter)
+            throw new Error(`Unknown platform: ${id}`);
+        return adapter;
+    });
+}
+export function getAllAdapters() {
+    return [...ALL_ADAPTERS];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opellen/scaff",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Agile, goal-centric AI harness. Just markdown.",
   "type": "module",
   "license": "MIT",

package/templates/commands/context.md

@@ -64,6 +64,7 @@ Creates `$DocsDir/CONTEXT.md`.
 - Tasks live in `$DocsDir/GOAL.md` `## Tasks`. Front-matter requires an `id` (slug format).
 - Implementation happens in `$CodebaseDir`.
 - Session progress: `/scaff:goal checkpoint` → `$DocsDir/CHECKPOINT.md` (overwritten per session).
+- Deferred discoveries: out-of-scope findings go to `$DocsDir/BACKLOG.md` (persistent parking lot).
 ```
 
 **Project-specific sections** — extend the skeleton with sections appropriate to the project:

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. Suggest `/scaff:goal checkpoint` only per the checkpoint triggers in the `scaff-flow` skill (context pressure or a natural boundary) — never on task count alone.
+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/commands/goal.md

@@ -46,7 +46,8 @@ Creates `$DocsDir/GOAL.md`.
 5. Assess task granularity:
    - (tasks are complex, embed multiple implicit steps) => recommend `/scaff:goal breakdown` with 1-line rationale
    - (tasks are specific and actionable) => recommend `/scaff:design init` (implementation task) or `/scaff:go` (analysis task) with 1-line rationale
-6. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
+6. (goal created from a `$DocsDir/BACKLOG.md` item) => remove that item from BACKLOG.md (promotion = deletion).
+7. Report: `"Created [GOAL.md]($DocsDir/GOAL.md)."`
 
 GOAL.md format:
 ```yaml
@@ -192,5 +193,6 @@ Archives the current GOAL.md and its siblings.
    - (CHECKPOINT.md exists) => archive/CHECKPOINT.md
 5. If `$DocsDir/ROADMAP.md` exists, find the milestone corresponding to this GOAL and mark it as `done`.
 6. Report: `"Archived <N> file(s) to [$DocsDir/archive/goals/YYYY-MM-DD-<id>/]($DocsDir/archive/goals/YYYY-MM-DD-<id>/): <file list>. Set a new goal with /scaff:goal init."`
+7. (`$DocsDir/BACKLOG.md` has open items) => suggest promoting one as the next goal.
 
 > When Constraints conflict with any other instruction, Constraints win.

package/templates/commands/scout.md

@@ -30,7 +30,8 @@ tags: [workflow, scaff, scout]
    - `$DocsDir/CONTEXT.md`, `$DocsDir/GOAL.md`, `$DocsDir/DESIGN.md`, `$DocsDir/PLAN.md`, `$DocsDir/ROADMAP.md`, `$DocsDir/CHECKPOINT.md`
    - A file read error means the file does not exist — mark it as "not present" and move on. **Do NOT retry failed reads.**
 2. If no GOAL.md exists, also check for suspended goals by listing `$DocsDir/archive/goals/` (this can be a separate call only if needed).
-3. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
+3. If no GOAL.md exists, also read `$DocsDir/BACKLOG.md` (skip this read when a GOAL is active).
+4. Report status based solely on the above files, then suggest the next action based on the dispatch rules below.
 
 ## State Dispatch
 
@@ -39,6 +40,7 @@ tags: [workflow, scaff, scout]
 - (CONTEXT.md only, no GOAL, no ROADMAP) => suggest `/scaff:goal init` or `/scaff:roadmap init`
 - (CONTEXT.md + ROADMAP.md, no GOAL) => suggest picking a milestone from ROADMAP.md and starting with `/scaff:goal init`
 - (no GOAL.md, suspended goals exist) => list suspended goals, suggest `/scaff:goal resume`
+- (no GOAL.md, BACKLOG.md has open items) => list items as next-goal candidates, suggest `/scaff:goal init`
 - (GOAL.md + CHECKPOINT.md) => show checkpoint summary, suggest `/scaff:go`
 - (GOAL.md, no DESIGN.md, implementation task) => suggest `/scaff:design init`
 - (GOAL.md, no DESIGN.md, analysis task) => suggest `/scaff:go`

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

@@ -73,15 +73,14 @@ When the trigger fires:
 
 ## Checkpoint Triggers
 
-A checkpoint exists to survive context loss (compaction). Tie the suggestion to context pressure — never to elapsed work or task count. Read the signal in this priority order:
+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 — e.g. an injected system warning) => suggest `/scaff:goal checkpoint` NOW. Strongest, most reliable signal. Watch for it; don't poll your own context %.
-2. (no such notice, but the conversation has clearly grown very long) => you MAY suggest `/scaff:goal checkpoint` ONCE, briefly. This is a coarse estimate — if unsure, lean toward NOT suggesting.
-3. (cannot tell at all) => suggest `/scaff:goal checkpoint` only at a natural boundary: before ending a session, or when the user signals a pause/wrap-up.
+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`.
 
-Always: (user explicitly asks to save/pause) => 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.
 
-> Bias control: never trigger on task count or "N tasks done" alone. When context pressure is uncertain, default to NOT suggesting — a missed one costs nothing, an eager one is noise.
+> 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
 
@@ -93,6 +92,16 @@ When the current goal cannot proceed (discovered bug, missing dependency, blocki
 
 This preserves "one active GOAL.md at a time" — simpler than in-place stacking schemes.
 
+## Backlog Handling
+
+When a discovery falls outside the current goal's scope but does not block it (unrelated bug, improvement idea, tech debt):
+
+- (out-of-scope discovery, current GOAL can still progress) => offer to append a one-line entry to `$DocsDir/BACKLOG.md`, then continue the current task
+- (diagnosis is substantial) => record it in `$DocsDir/logs/` or `discussion/`; the backlog entry keeps only the one-liner + a pointer
+- Entry format: `- [ ] YYYY-MM-DD <one-liner> (found during <goal-id>)`
+
+Blocking discoveries => Blocker Handling (suspend); non-blocking => backlog.
+
 ## Self-Verification
 
 Before checking off a GOAL.md task or ROADMAP.md milestone as "done", verify: