@forgeailab/create-spark 0.1.2 → 0.1.3

package/.codex/skills/qa-verify/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: qa-verify
+description: Verify the app actually runs and the feature works end-to-end, not just that code compiles. Use after a feature batch lands, before a demo, when the user says "does this actually work?", "run it and check", or before flipping a task to `Validated`. Do NOT use as a substitute for `/code-review` — they cover different failure modes.
+# Generated from .claude/skills/qa-verify/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: qa-verify
+
+## Goal
+
+Boot the app, click through the real user flow, and confirm the acceptance criteria hold when humans actually use the product. Type-checks and unit tests pass != feature works.
+
+## Recommended model
+
+Sonnet 4.6. This is execution, not judgment.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — task(s) being verified
+- `.ai/product-spec.md` — the core user journey
+
+Read if useful:
+
+- `.ai/ux-theme.md` for empty / loading / error patterns
+- `README.md` / `package.json` for the run command
+
+## Rules
+
+- Always run the app. If you cannot launch it, report that explicitly — do not claim verification from reading code.
+- Walk the **core user journey from `product-spec.md`**, not just the changed feature. Regressions in adjacent flows count.
+- Check empty / loading / error / mobile states for every screen touched. MVPs feel broken at the seams, not the happy path.
+- Capture exact commands and outputs so the user can reproduce.
+- Use a real browser or device when relevant (Playwright MCP if available). Curl-ing an API endpoint is not UI verification.
+
+## Workflow
+
+1. Find the run command (project README, `package.json` scripts, or ask).
+2. Boot the app. Note the URL.
+3. Walk the core journey step by step from the spec.
+4. Re-walk the specific feature(s) from the task(s).
+5. Probe empty / loading / error / mobile.
+6. Write the report.
+
+## Output format
+
+```md
+## QA verification — <TASK-ID(s)> / <feature name>
+
+### Boot
+- Command: `<cmd>`
+- Result: app running at <url> | failed (<reason>)
+
+### Core user journey (from spec)
+- [x|✗] Step 1: <description> — <observation>
+- [x|✗] Step 2: ...
+
+### Feature-specific checks
+- [x|✗] <acceptance criterion> — <observation>
+
+### Edge states
+- Empty state: <ok | broken | missing>
+- Loading state: <ok | broken | missing>
+- Error state: <ok | broken | missing>
+- Mobile / narrow viewport: <ok | broken>
+
+### Broken flows discovered
+- <one-line description> — <repro steps>
+
+### Recommended board update
+- <TASK-ID>: review → Validated | review → In progress
+- New tasks to add: <list or none>
+```

package/.codex/skills/risk-check/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: risk-check
+description: Detect whether the project is drifting — scope creep, architecture creep, hidden dependencies, missing tests, unclear tasks, plus stale hybrid-pack helper versions (more than two minor versions behind the latest published). Use every few sessions, when the user says "are we on track?", "is this getting out of hand?", or before a demo. The anti-overthinking and anti-feature-creep skill.
+# Generated from .claude/skills/risk-check/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: risk-check
+
+## Goal
+
+Be the brake. Compare the current state of the project to the spec and architecture, and call out where reality is drifting. Recommend concrete cuts.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- `.ai/board.md`
+- `.ai/decision-log.md` if it exists
+- `.spark/state.json` if it exists
+- `packs/*/pack.toml` if pack state exists and the registry is available
+
+Sample reality:
+
+- `git log --oneline -30`
+- top-level directory listing
+- list of dependencies in `package.json` / `pyproject.toml` / equivalent
+
+## Rules
+
+- Compare **what is in the code now** to **what the spec said**. Highlight gaps in both directions: missing must-haves, plus things built that the spec did not ask for.
+- Treat the spec's non-goals list as a checklist of things that should NOT be present in code. Violations are creep, not features.
+- Recommend cuts, not additions. The default fix is "remove or defer," not "build more."
+- Distinguish **drift** (planned scope grew quietly) from **discovery** (new task properly added to the board). Discovery is fine; silent drift is not.
+- For pack-level drift, inspect `.spark/state.json` when present. For each installed pack, determine its provided capabilities from state or from `packs/<name>/pack.toml`; if none of those capabilities are referenced in `.ai/product-spec.md` or `.ai/architecture.md`, flag it as drift.
+- The pack-level drift recommendation is exactly: **review or revert the pack-install commit via git**. Do not suggest a CLI removal command; v1 has no pack uninstall flow.
+- For each installed pack whose manifest declares `[runtime_package]` (hybrid pack), inspect the consumer project's `package.json` (`dependencies` + `devDependencies`) for the named helper. Compare the installed version against the latest published version on the npm registry (use `bun pm view <pkg> version` or `npm view <pkg> version` via Bash). If the installed version is more than two minor versions behind the latest, flag it under "Stale helper". A `file:` specifier counts as "local dev link" and is NOT stale.
+
+## Checklist
+
+- **Scope creep** — features in code that are not in `MVP feature list`, or are in `Non-goals`.
+- **Architecture creep** — services / dependencies / abstractions beyond what `architecture.md` declared.
+- **Pack-level drift** — installed packs whose provided capabilities are not justified by the spec or architecture.
+- **Stale helper** — hybrid packs whose helper package is more than two minor versions behind the latest on npm.
+- **Unclear tasks** — open board tasks without observable acceptance criteria.
+- **Missing tests / verification** — tasks marked `Validated` with no run command or no review.
+- **Hidden dependencies** — packages added not justified by a task or decision.
+- **Stalled tasks** — tasks in `In progress` for more than ~2 sessions with no commits.
+
+## Output format
+
+```md
+## Pack-level drift
+- no drift detected
+- <pack-name>: provides <capability tag(s)>; none are referenced in `.ai/product-spec.md` or `.ai/architecture.md` — **recommend: review or revert the pack-install commit via git**
+
+## Stale helper
+- no stale helpers
+- <pack-name>: helper `<helper-package>` installed at <installed-version>, latest is <latest-version> — **recommend: `bun update <helper-package>`**
+
+## Risk check
+
+### Scope creep
+- <thing built / in progress> — not in spec / in non-goals — **recommend: cut | defer | keep with decision log entry**
+
+### Architecture creep
+- <new service / dep / abstraction> — **recommend: revert | document in architecture.md**
+
+### Unclear tasks
+- <TASK-ID>: criteria are vague — **recommend: rewrite or send to `/board-review`**
+
+### Hidden dependencies
+- <package> added in <commit> — justification: <none | <task>>
+
+### Stalled tasks
+- <TASK-ID>: in progress since <when> — **recommend: split | unblock | drop**
+
+### Summary
+- Drift severity: low | medium | high
+- Suggested next action: <one line>
+```

package/.codex/skills/sync-board/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: sync-board
+description: Update `.ai/board.md` to reflect actual code progress — apply status changes from execution reports, add discovered tasks, and recommend the next batch. Use after `/execute-task`, at the end of a working session, or when the user says "update the board", "sync progress", "what's next?". Do NOT use to create the initial board — that is `/mvp-board`.
+# Generated from .claude/skills/sync-board/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: sync-board
+
+## Goal
+
+Keep `.ai/board.md` in sync with reality. The board is the source of truth — if it drifts from what is actually built, the whole system breaks.
+
+## Recommended model
+
+Sonnet 4.6. This is mechanical reconciliation, not planning.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+
+Read if available:
+
+- the most recent `/execute-task` report in the conversation
+- `git status` and `git log` (one screenful) to confirm what actually changed
+- `.ai/execution-log.md` if it exists
+
+## Rules
+
+- **Trust git, not claims.** If a report says a file changed but git disagrees, flag it and do not advance the task.
+- Never set status to `Validated` directly from execution. `Validated` requires a `/code-review` pass and, for user-facing changes, a `/qa-verify` pass. Update `Validation state` accordingly: `code-reviewed`, `qa-verified`, or `both`.
+- Status flow is: `In progress` → `Needs review` → `Validated`. `Blocked` can come from any state.
+- Never move a task to `Approved for execution`. That is `/board-review`'s job.
+- New work discovered during execution becomes a new task in `Clarifying`, at the bottom of the relevant epic — not a silent edit to an existing task.
+- Tasks the user explicitly cut go in the `Cut from MVP` section with a reason — never delete them.
+- If a task is `Blocked`, record the specific blocker in a `Blocked by:` line.
+- When a PR is opened, update `Linked PR:`. When a preview deploy exists, update `Demo URL:`.
+- Append a one-line entry per state change to `.ai/execution-log.md` (create it if missing).
+
+## Workflow
+
+1. Read the board and the latest execution report.
+2. Run `git status` and a short `git log` to confirm actual changes.
+3. For each affected task: update status, append changed-files and verification result.
+4. Add any follow-up tasks discovered.
+5. Identify the next recommended task (or batch) based on dependencies.
+6. Write the updated board and append to the execution log.
+
+## Output format
+
+After writing, return:
+
+```md
+## Board synced
+
+### Status changes
+- <TASK-ID>: <old> → <new>
+
+### Tasks added
+- <NEW-TASK-ID>: <title> (in <EPIC>)
+
+### Blockers
+- <TASK-ID>: <reason>
+
+### Next recommended
+- <TASK-ID> (or batch from `/parallel-execution`)
+- Why now: <one line>
+
+### Drift detected
+- <e.g. "claimed edit to foo.ts but git shows no change"> | none
+```

package/.codex/skills/ux-theme/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ux-theme
+description: Define the visual and product direction (vibe, layout, color, typography, component style) before coding starts. Use when the user says "what should this look like?", "pick a theme", "make it feel like Linear/Notion/Vercel", or right before scaffolding UI. Do NOT use for fine-grained component styling — that belongs in execution.
+# Generated from .claude/skills/ux-theme/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: ux-theme
+
+## Goal
+
+Produce `.ai/ux-theme.md` — a concrete visual direction that every executor task can consult. Lovable-style theme control: one clear vibe, one set of patterns, one reference product.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for the direction. Sonnet 4.6 can implement against it later.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- `.ai/decision-log.md`
+
+## Rules
+
+- Pick **one** vibe. Not "minimal but playful but also enterprise."
+- Name **one** reference product to imitate. "Linear-style productivity SaaS" beats "clean and modern."
+- Give concrete tokens (color names, type scale, spacing) so executors do not invent their own.
+- Define empty / loading / error patterns up front — these are where MVPs feel broken.
+- Do not generate full design files. This is a brief, not Figma.
+
+## Reference directions (pick one or describe a new one)
+
+- Linear-style productivity SaaS
+- Notion-like workspace
+- Vercel-like developer tool
+- Stripe-like admin dashboard
+- Arc-like playful consumer app
+
+## Output format
+
+Write `.ai/ux-theme.md`:
+
+```md
+# UX Theme — <name>
+
+## Vibe
+<one sentence>
+
+## Reference product
+<one product, with a link or short description of what to copy>
+
+## Layout style
+<sidebar + content / centered single column / dashboard grid / etc.>
+
+## Color direction
+- Background:
+- Surface:
+- Text primary:
+- Text muted:
+- Accent:
+- Danger:
+(prefer Tailwind palette names or hex)
+
+## Typography
+- Display:
+- Body:
+- Mono:
+- Scale: <e.g. 12 / 14 / 16 / 20 / 24 / 32>
+
+## Component style
+- Corners: <radius>
+- Borders: <weight, color>
+- Shadows: <none / soft / layered>
+- Buttons: <filled / outlined / ghost variants>
+- Inputs: <style>
+
+## Patterns
+- Empty state:
+- Loading state:
+- Error state:
+- Table:
+- Card:
+- Dialog / modal:
+
+## Constraints
+- <hard "no" rules, e.g. "no gradients", "no emoji in UI">
+```
+
+After writing, recommend `/mvp-board` next.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeailab/create-spark",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Interactive scaffolder for spark projects with guided pack picker.",
   "type": "module",
   "publishConfig": {
@@ -9,16 +9,19 @@
   "files": [
     "src",
     "README.md",
-    "templates",
     "packs",
-    "presets"
+    "presets",
+    "templates",
+    ".claude",
+    ".codex",
+    "scripts"
   ],
   "bin": {
     "create-spark": "./src/cli.ts"
   },
   "dependencies": {
-    "@forgeailab/spark": "^0.1.2",
-    "@forgeailab/spark-schema": "^0.1.2",
+    "@forgeailab/spark": "^0.1.3",
+    "@forgeailab/spark-schema": "^0.1.3",
     "@clack/prompts": "latest",
     "citty": "latest",
     "picocolors": "latest"

package/scripts/sync-skills.ts

@@ -0,0 +1,223 @@
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  parseSkillFrontmatter,
+  serializeSkillFrontmatter,
+  toCodexFrontmatter,
+} from "@forgeailab/spark-skill-utils";
+
+type SkillOutput = {
+  name: string;
+  content: string;
+};
+
+type Diff =
+  | { type: "missing"; path: string }
+  | { type: "extra"; path: string }
+  | { type: "changed"; path: string };
+
+type SyncResult = {
+  ok: boolean;
+  count: number;
+  diffs: Diff[];
+};
+
+type TreeEntry = {
+  type: "dir" | "file";
+  content?: string;
+};
+
+export function transformSkillMarkdown(markdown: string, skillName: string): string {
+  const { frontmatter, body } = parseSkillFrontmatter(markdown);
+  const codexFrontmatter = toCodexFrontmatter(frontmatter);
+  const outputFrontmatter = serializeSkillFrontmatter(codexFrontmatter, {
+    trailingComments: [
+      `# Generated from .claude/skills/${skillName}/SKILL.md — DO NOT EDIT directly`,
+    ],
+  });
+
+  return `---\n${outputFrontmatter}\n---\n${body}`;
+}
+
+async function collectSkillOutputs(root: string): Promise<SkillOutput[]> {
+  const sourceRoot = join(root, ".claude", "skills");
+  const entries = await readdir(sourceRoot, { withFileTypes: true });
+  const outputs: SkillOutput[] = [];
+
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillName = entry.name;
+    const sourceFile = join(sourceRoot, skillName, "SKILL.md");
+    if (!existsSync(sourceFile)) {
+      continue;
+    }
+
+    const source = await readFile(sourceFile, "utf8");
+    outputs.push({
+      name: skillName,
+      content: transformSkillMarkdown(source, skillName),
+    });
+  }
+
+  return outputs;
+}
+
+async function writeOutputs(targetRoot: string, outputs: SkillOutput[]): Promise<void> {
+  await rm(targetRoot, { force: true, recursive: true });
+  await mkdir(targetRoot, { recursive: true });
+
+  for (const output of outputs) {
+    const skillDir = join(targetRoot, output.name);
+    await mkdir(skillDir, { recursive: true });
+    await writeFile(join(skillDir, "SKILL.md"), output.content, "utf8");
+  }
+}
+
+async function collectTree(root: string): Promise<Map<string, TreeEntry>> {
+  const tree = new Map<string, TreeEntry>();
+
+  if (!existsSync(root)) {
+    return tree;
+  }
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const absolutePath = join(dir, entry.name);
+      const relativePath = relative(root, absolutePath).split(sep).join("/");
+
+      if (entry.isDirectory()) {
+        tree.set(relativePath, { type: "dir" });
+        await walk(absolutePath);
+        continue;
+      }
+
+      if (entry.isFile()) {
+        tree.set(relativePath, {
+          type: "file",
+          content: await readFile(absolutePath, "utf8"),
+        });
+      }
+    }
+  }
+
+  await walk(root);
+  return tree;
+}
+
+async function diffTrees(expectedRoot: string, actualRoot: string): Promise<Diff[]> {
+  const expected = await collectTree(expectedRoot);
+  const actual = await collectTree(actualRoot);
+  const paths = Array.from(new Set([...expected.keys(), ...actual.keys()])).sort();
+  const diffs: Diff[] = [];
+
+  for (const path of paths) {
+    const expectedEntry = expected.get(path);
+    const actualEntry = actual.get(path);
+
+    if (!expectedEntry) {
+      diffs.push({ type: "extra", path });
+      continue;
+    }
+
+    if (!actualEntry) {
+      diffs.push({ type: "missing", path });
+      continue;
+    }
+
+    if (
+      expectedEntry.type !== actualEntry.type ||
+      (expectedEntry.type === "file" && expectedEntry.content !== actualEntry.content)
+    ) {
+      diffs.push({ type: "changed", path });
+    }
+  }
+
+  return diffs;
+}
+
+export async function syncSkills(
+  targetRoot = process.cwd(),
+  options: { check?: boolean } = {},
+): Promise<SyncResult> {
+  const root = resolve(targetRoot);
+  const targetRootPath = join(root, ".codex", "skills");
+  const outputs = await collectSkillOutputs(root);
+
+  if (!options.check) {
+    await writeOutputs(targetRootPath, outputs);
+    return { ok: true, count: outputs.length, diffs: [] };
+  }
+
+  const tempRoot = await mkdtemp(join(tmpdir(), "sync-skills-"));
+  const expectedRoot = join(tempRoot, "skills");
+
+  try {
+    await writeOutputs(expectedRoot, outputs);
+    const diffs = await diffTrees(expectedRoot, targetRootPath);
+    return { ok: diffs.length === 0, count: outputs.length, diffs };
+  } finally {
+    await rm(tempRoot, { force: true, recursive: true });
+  }
+}
+
+function parseArgs(argv: string[]): { check: boolean; root: string } {
+  const positional: string[] = [];
+  let check = false;
+
+  for (const arg of argv) {
+    if (arg === "--check") {
+      check = true;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional.length > 1) {
+    throw new Error("Expected at most one positional argument: target project root");
+  }
+
+  return {
+    check,
+    root: positional[0] ?? process.cwd(),
+  };
+}
+
+function printDiffs(diffs: Diff[]): void {
+  for (const diff of diffs) {
+    console.error(`${diff.type}: ${diff.path}`);
+  }
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const result = await syncSkills(args.root, { check: args.check });
+
+    if (!result.ok) {
+      console.error(".codex/skills is out of sync. Run bun run scripts/sync-skills.ts.");
+      printDiffs(result.diffs);
+      process.exit(1);
+    }
+
+    if (args.check) {
+      console.log(`.codex/skills is in sync (${result.count} skills).`);
+    } else {
+      console.log(`Synced ${result.count} skills into .codex/skills.`);
+    }
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}