@forgeailab/create-spark 0.1.2 → 0.2.0

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

@@ -0,0 +1,93 @@
+---
+name: mvp-board
+description: Convert the spec and architecture into an executable Markdown board of epics and tasks. Use when the user says "build the board", "break this into tasks", "what should I build first?", or after `.ai/product-spec.md` and `.ai/architecture.md` are in place. Do NOT use to update an existing board after code changes — that is `/sync-board`.
+# Generated from .claude/skills/mvp-board/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: mvp-board
+
+## Goal
+
+Produce `.ai/board.md` — the cockpit for the whole project. Every task is sized for one Claude Code session, has acceptance criteria, and declares whether it can run in parallel.
+
+This is the most important artifact in the system. The board is truth; chat is steering.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read if they exist:
+
+- `.ai/ux-theme.md`
+- `.ai/decision-log.md`
+
+If spec or architecture is missing, stop and tell the user.
+
+## Rules
+
+- Every task must fit in one focused execution session. If a task touches more than ~5 files or has more than 3 acceptance criteria, split it.
+- Every task must declare **Depends on** and **Parallel-safe**. No exceptions.
+- Order tasks so the **core flow comes online first**, then polish. Auth and dashboards are not core — the user's primary action is.
+- Mark explicit non-tasks for things the spec ruled out, so they do not silently re-enter scope.
+- Use stable IDs (e.g. `AUTH-001`, `FEED-002`) so other skills can reference them.
+
+## Output format
+
+Write `.ai/board.md`:
+
+```md
+# MVP Board
+
+## Rules
+- Only execute one task at a time unless marked parallel-safe.
+- Every task must have acceptance criteria.
+- Completed tasks must list changed files and verification result.
+- New discoveries become new tasks, not silent scope expansion.
+
+## Status legend
+Clarifying | Approved for planning | Approved for execution | In progress | Needs review | Validated | Blocked | Cut from MVP
+
+New tasks start in `Clarifying`. They only move to `Approved for execution` via `/board-review`. Execution skills must refuse to act on tasks not in `Approved for execution`.
+
+---
+
+## EPIC 1: <name>
+
+### TASK <ID>: <short title>
+Status: Clarifying
+Priority: P0 | P1 | P2
+Agent owner: planner | sonnet | reviewer
+Human owner: <name or @handle>
+Depends on: <ID> | none
+Parallel-safe: yes | no
+Risk: low | medium | high
+Validation state: not started | code-reviewed | qa-verified | both
+Linked PR: <url or none>
+Demo URL: <url or none>
+
+Acceptance criteria:
+- [ ] <observable>
+- [ ] <observable>
+
+Files likely touched:
+- <path>
+
+Execution prompt:
+Use `/implementation-brief <ID>`, then `/execute-task <ID>`, then `/code-review <ID>` and `/qa-verify`.
+
+---
+
+(repeat for every task)
+
+## Cut from MVP
+- <thing>: <reason>
+```
+
+After writing, recommend `/board-review` as the next step. Tasks must not move to execution until reviewed and approved.

package/.codex/skills/mvp-grill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mvp-grill
+description: Grill a rough product idea with sharp questions until it is buildable. Use when the user says "I want to build X", "help me make an MVP", "is this idea good?", or hands over a vague concept. Do NOT use once `.ai/product-spec.md` already exists — switch to `/mvp-spec` or `/architecture-cutline` instead.
+# Generated from .claude/skills/mvp-grill/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: mvp-grill
+
+## Goal
+
+Turn a messy idea into something concrete enough to plan. You are a skeptical product partner, not a cheerleader. Ask only the questions that change scope or architecture.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5. This is a planning task — do not delegate to a fast executor.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/product-spec.md`
+- `.ai/decision-log.md`
+
+If `.ai/product-spec.md` already has a target user, core loop, and MVP features, stop and tell the user the idea is past the grilling stage.
+
+## Rules
+
+- Max **5 questions per round**. Wait for answers before the next round.
+- Only ask questions that change scope, architecture, or the definition of "done." Skip cosmetic or curious questions.
+- Force a real answer. If the user dodges, ask a sharper version.
+- Stop grilling once you can write a coherent one-sentence product, target user, core loop, and MVP feature list. Then write to `.ai/decision-log.md` and recommend `/mvp-spec`.
+- Never write code or scaffold files in this skill.
+
+## Question pool (pick the highest-leverage 5 each round)
+
+- Who exactly is the target user? Be specific — not "developers" but "indie hackers shipping their first paid SaaS."
+- What is the one painful thing they do today that this replaces?
+- What is the single most important user action in the product?
+- What is the first use case that must work end-to-end?
+- What can be faked manually for v1 (no automation, no integration)?
+- Where does the data come from?
+- Is auth required for v1, or can it be skipped?
+- Is payment required for v1?
+- What does "done" mean for the first release?
+- What must absolutely NOT be built yet?
+- What is the launch constraint (date, demo, audience)?
+- What is the success metric you would actually check?
+
+## Output format
+
+After each round, return:
+
+1. **Summary so far** — what you have locked in.
+2. **Open questions** — up to 5, numbered, sharp.
+3. **Gaps** — what is still too vague to plan around.
+4. **Next** — either "answer the questions above" or "ready for `/mvp-spec`".
+
+When grilling ends, append a short entry to `.ai/decision-log.md` capturing the locked-in answers.

package/.codex/skills/mvp-spec/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mvp-spec
+description: Convert a grilled idea into a single concise MVP specification that an executor can build from. Use when the user says "write the spec", "let's lock the MVP", or after `/mvp-grill` has settled the open questions. Do NOT use if `.ai/product-spec.md` already exists and is current — edit it directly or run `/risk-check` first.
+# Generated from .claude/skills/mvp-spec/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: mvp-spec
+
+## Goal
+
+Produce `.ai/product-spec.md` — the single source of truth for what the MVP is. Technical enough that Sonnet/Claude Code can execute without guessing, short enough to fit in working memory.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/decision-log.md` (this is the input — do not re-grill)
+- existing `.ai/product-spec.md` (update in place rather than rewrite)
+
+If the decision log is missing the answers needed, stop and tell the user to run `/mvp-grill` first. Do not invent answers.
+
+## Rules
+
+- One spec, one MVP slice. If the user wants v1 and v2, write v1 only.
+- Every section must fit on one screen. If it does not, you are over-specifying.
+- **Non-goals are mandatory.** A spec without a non-goals list always leaks scope.
+- Acceptance criteria must be checkable, not aspirational.
+- Do not pick a stack here — that is `/architecture-cutline`'s job.
+- Do not write tasks here — that is `/mvp-board`'s job.
+
+## Output format
+
+Write `.ai/product-spec.md` with exactly these sections:
+
+```md
+# Product Spec — <name>
+
+## 1. One-sentence product
+<who it is for, what it does, what they get>
+
+## 2. Target user
+<specific persona, not a category>
+
+## 3. Core user journey
+<3–7 numbered steps from open-app to win>
+
+## 4. MVP feature list
+- <feature>: <one-line description>
+(keep this list aggressively short)
+
+## 5. Non-goals
+- <thing we will NOT build for MVP>
+(at least 5 entries; this section is mandatory)
+
+## 6. Data model
+<entities and their key fields, no SQL>
+
+## 7. Screens / pages
+- <route>: <purpose>
+
+## 8. Integrations
+<auth, payments, third-party APIs, or "none">
+
+## 9. Risks
+<technical, product, or scope risks — 3–5 bullets>
+
+## 10. Acceptance criteria
+- [ ] <observable, testable statement>
+(these are what makes MVP "done")
+```
+
+After writing, return a short summary and recommend `/architecture-cutline` next.

package/.codex/skills/new-pack/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: new-pack
+description: Scaffold a new local feature-pack directory under `packs/` with a minimal manifest, empty files and skills directories, and an empty task stub. Prompts for install mode (`copy` or `hybrid`); a `hybrid` pack additionally scaffolds a companion `libs/spark-<name>/` workspace package and writes a `[runtime_package]` block into the new manifest. Use when a needed capability has no v1 pack.
+# Generated from .claude/skills/new-pack/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: new-pack
+
+## Goal
+
+Create a minimal pack skeleton that a human or executor can fill in later. This skill only scaffolds the pack directory (and, in `hybrid` mode, a companion workspace package under `libs/`); it does not implement the integration.
+
+## Recommended model
+
+Sonnet 4.6 or GPT-5 family executor.
+
+## Inputs
+
+Required from the user:
+
+- `<name>` — pack directory name, for example `realtime-supabase`
+- `category=<category>` — one of the v1 category values
+- `mode=<mode>` — install mode, either `copy` or `hybrid`
+
+If any of these values is missing, ask for it before writing files. When asking for `mode`, explain the difference:
+
+- `copy` — pack ships its full runtime logic as files copied into the consumer project. The user owns the code in place. This is the right default for stable framework glue (config files, route handlers, env wiring).
+- `hybrid` — pack ships only thin wiring files and imports its runtime logic from a versioned npm helper package `@forgeailab/spark-<name>` published from `libs/spark-<name>/`. Choose this when the logic is the same across every consumer project and bug fixes should land in one place.
+
+## Valid categories
+
+- `db`
+- `auth`
+- `payments`
+- `email`
+- `ui`
+- `ai`
+- `infra`
+- `testing`
+- `deploy`
+- `analytics`
+- `storage`
+
+## Rules
+
+- Validate that `<name>` is a single directory segment. Reject names containing `/`, `..`, spaces, or shell metacharacters.
+- Validate that `packs/<name>/` does not already exist. If it exists, stop and report the collision.
+- Validate that `category` is exactly one of the allowed categories above.
+- Validate that `mode` is exactly `copy` or `hybrid`.
+- Pack scaffold (both modes) creates only these paths:
+  - `packs/<name>/pack.toml`
+  - `packs/<name>/files/`
+  - `packs/<name>/skills/`
+  - `packs/<name>/tasks.yaml`
+- Additionally in `hybrid` mode, validate that `libs/spark-<name>/` does not already exist, then create the companion workspace package:
+  - `libs/spark-<name>/package.json`
+  - `libs/spark-<name>/tsconfig.json`
+  - `libs/spark-<name>/src/index.ts`
+  - `libs/spark-<name>/test/index.test.ts`
+  - `libs/spark-<name>/README.md`
+- `tasks.yaml` must be an empty stub file.
+- Leave `provides`, `requires`, and `conflicts` empty. Do not guess capability tags.
+- The pack's `[dependencies].runtime` MUST NOT redeclare the helper package — the CLI adds it implicitly from `[runtime_package]`.
+
+## `pack.toml` skeleton — `copy` mode
+
+Write this manifest, replacing `<name>` and `<category>`:
+
+```toml
+name = "<name>"
+version = "0.1.0"
+category = "<category>"
+description = "TODO: describe what this pack adds."
+provides = []
+requires = []
+conflicts = []
+```
+
+## `pack.toml` skeleton — `hybrid` mode
+
+In `hybrid` mode, the manifest gains a `[runtime_package]` table pointing at the companion helper:
+
+```toml
+name = "<name>"
+version = "0.1.0"
+category = "<category>"
+description = "TODO: describe what this pack adds."
+provides = []
+requires = []
+conflicts = []
+
+[runtime_package]
+package = "@forgeailab/spark-<name>"
+version = "^0.1"
+```
+
+## `libs/spark-<name>/` skeleton — `hybrid` mode only
+
+`package.json`:
+
+```json
+{
+  "name": "@forgeailab/spark-<name>",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": false,
+  "devDependencies": {
+    "bun-types": "latest",
+    "typescript": "latest"
+  }
+}
+```
+
+`tsconfig.json`:
+
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "include": ["src/**/*", "test/**/*"]
+}
+```
+
+`src/index.ts`: empty `export {};` placeholder.
+`test/index.test.ts`: minimal `test('placeholder', () => expect(true).toBe(true));`.
+`README.md`: one-line description plus a "Why is this in libs/ vs packages/?" note (it is a library consumers import from, not internal CLI plumbing).
+
+## Output format
+
+After creating the skeleton, return:
+
+```md
+## New pack scaffolded
+
+- Pack: `<name>`
+- Category: `<category>`
+- Install mode: `<mode>`
+- Created:
+  - `packs/<name>/pack.toml`
+  - `packs/<name>/files/`
+  - `packs/<name>/skills/`
+  - `packs/<name>/tasks.yaml`
+  <!-- hybrid mode only -->
+  - `libs/spark-<name>/package.json`
+  - `libs/spark-<name>/tsconfig.json`
+  - `libs/spark-<name>/src/index.ts`
+  - `libs/spark-<name>/test/index.test.ts`
+  - `libs/spark-<name>/README.md`
+
+Next: fill in `provides`, `requires`, files, tasks, and any pack-shipped skills before installing it.
+In hybrid mode, also implement the runtime helper under `libs/spark-<name>/src/` and re-run `bun install`.
+```

package/.codex/skills/next-task/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: next-task
+description: Pick the next best board task to work on, with the reasoning. Use when the user says "what should I do next?", "what's next?", or after `/sync-board` finishes. Do NOT use to plan a whole batch — that is `/parallel-execution`.
+# Generated from .claude/skills/next-task/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: next-task
+
+## Goal
+
+Recommend the single next task (or smallest parallel batch) the user should execute now, based on the current state of the board.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5. Picking the next move is a planning call.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+- `.ai/product-spec.md`
+
+Read if available:
+
+- `.ai/architecture.md`
+- `.ai/execution-log.md`
+
+## Rules
+
+Decision order, in priority:
+
+1. **Unblock the core user flow first.** The user's primary action in the spec must work end-to-end before anything else.
+2. **Prefer tasks whose dependencies are satisfied.** A task with unmet `Depends on:` is not eligible.
+3. **Prefer tasks with clear acceptance criteria** over vague ones.
+4. **Batch parallel-safe tasks** only when the user explicitly asked for parallelism.
+5. **Schedule QA after every feature batch**, not at the end of the project.
+6. **Do not pick polish before core works.** Empty states and copy come after the loop is alive.
+
+Only recommend tasks in status `Approved for execution`. If nothing is approved, recommend `/board-review` instead.
+
+## Output format
+
+```md
+## Next recommended
+
+### Task
+- <TASK-ID>: <title>
+
+### Why now
+<one line — usually one of: "unblocks core flow", "prerequisites just landed", "highest-risk path">
+
+### Dependencies satisfied
+- <DEP-ID>: <status> ✓
+
+### Risk
+<low | medium | high — and the specific risk if not low>
+
+### Suggested execution
+Run `/implementation-brief <TASK-ID>`, then `/execute-task <TASK-ID>`.
+
+### Alternative
+<one other reasonable pick + one-line reason, or "none — this is the clear next step">
+```

package/.codex/skills/pack-add/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: pack-add
+description: Safely install feature packs by dry-running `spark add`, showing the plan, waiting for explicit approval, running the real install, and syncing the board. Use when the user asks to add one or more packs.
+# Generated from .claude/skills/pack-add/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: pack-add
+
+## Goal
+
+Install packs through the board-aware workflow: dry-run first, show the plan, get explicit confirmation, install, then sync the board so seeded tasks appear.
+
+## Recommended model
+
+Sonnet 4.6 or GPT-5 family executor.
+
+## Inputs
+
+Read these if present:
+
+- `spark.config.json`
+- `.ai/architecture.md`
+- `.ai/board.md`
+- `.spark/state.json`
+
+The user must provide one or more pack names. If no pack is named, stop and ask for the pack list or recommend `/pack-resolve`.
+
+## Rules
+
+- Always run `spark add <pack...> --dry-run` before any real install.
+- Present the dry-run diff or plan to the user in compact form: packs, dependencies, files, env vars, skills, and board tasks.
+- Wait for explicit confirmation before installing. Accept only clear approval such as "yes", "approved", or "install".
+- If the dry-run fails, stop. Do not attempt the real install.
+- If the user declines or gives an ambiguous answer, stop with no filesystem changes.
+- On approval, run `spark add <pack...>` with the same pack arguments as the dry-run.
+- After a successful install, invoke `/sync-board` so seeded tasks are reflected in `.ai/board.md`.
+- Do not mark any seeded task `Approved for execution` or `Validated`; board-review and review skills own those transitions.
+
+## Workflow
+
+1. Confirm the pack arguments exactly as provided.
+2. Run `spark add <pack...> --dry-run`.
+3. Summarize the plan and ask the user for explicit approval.
+4. If approved, run `spark add <pack...>`.
+5. If install succeeds, run `/sync-board`.
+6. Report the installed packs, changed files summary, and board sync result.
+
+## Output format
+
+Before approval:
+
+- Dry-run command
+- Planned pack order
+- Files/env/skills/tasks summary
+- Confirmation question
+
+After install:
+
+- Install command
+- Result
+- `/sync-board` result
+- Any follow-up tasks or blockers

package/.codex/skills/pack-resolve/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: pack-resolve
+description: Recommend the right scaffold template and concrete feature packs from `.ai/product-spec.md` and `.ai/architecture.md`. Annotates each recommended pack as `copy` or `hybrid` based on whether its manifest declares `[runtime_package]`. Use when the user asks which packs to install, wants a scaffold/preset recommendation, or scope changed after architecture. This skill only plans; it never installs.
+# Generated from .claude/skills/pack-resolve/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: pack-resolve
+
+## Goal
+
+Recommend a scaffold template and a concrete pack set from the current product spec and architecture. The output should be directly actionable, but this skill must not execute any install.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read these if present:
+
+- `templates/*/template.toml`
+- `packs/*/pack.toml`
+- `presets/*.toml`
+- `spark.config.json`
+
+If the spec or architecture is missing, stop and tell the user to run `/mvp-spec` and `/architecture-cutline` first.
+
+## Rules
+
+- Do not run `bunx create-spark`, `spark add`, or `spark preset`. This is a planning skill only.
+- Resolve from the registry, not from memory. Pack names must come from `packs/*/pack.toml`; templates must come from `templates/*/template.toml`.
+- Prefer the smallest pack set that satisfies the spec and architecture. Do not install "usual SaaS" packs unless the capability is actually required.
+- Group packs by manifest `category`, and map each pack to the capability tags it provides or satisfies.
+- Annotate each recommended pack as either `copy` or `hybrid`. The classification is derived from the pack's `pack.toml`: presence of a `[runtime_package]` table means `hybrid`; absence means `copy`. Readers must immediately see which packs ship a versioned runtime helper they will import from versus which copy source files into the project.
+- Respect `requires`, `conflicts`, `compatible_scaffolds`, and `requires_runtime` when recommending a set.
+- If a needed capability has no v1 pack, name the gap explicitly and suggest `/new-pack`. Do not invent a pack name or include the missing capability in the command.
+- If the best-fit template has `status = "planned"`, still recommend it as the destination, write `planned, not yet implemented`, suggest `nextjs` as the interim alternative, and make the final command use the executable interim path.
+- If a preset exactly matches the recommended fresh-project pack set, the final command may be `bunx create-spark <name> --template <t> --preset <p>`. Otherwise, or when resolving for an existing project, the final command must be `spark add <pack...>` using only real pack names from the registry.
+- The final answer must end with exactly one fenced `sh` command block and no text after it.
+
+## Capability hints
+
+Use these only as hints; the registry still wins:
+
+- Paid SaaS: `db`, `auth`, `payments`, `email`, `ui-kit`, `deploy-target`.
+- Internal tool: `db`, `auth`, `ui-kit`, optionally `local-runtime`.
+- AI workflow: `ai-sdk`, optional `db`, optional `ui-kit`.
+- Documentation site: `mdx-content` template capability; `astro-starlight` may be the destination but is planned in v1.
+- Realtime/client-first sync: `sync`; if the requested capability is broader than the v1 `sync-zero` pack covers, name the gap.
+
+## Output format
+
+Return these sections:
+
+- `## Scaffold` — recommended template, status, why it fits, and interim alternative if the best fit is planned.
+- `## Packs` — grouped by category. Each bullet must be `<pack-name> (<copy|hybrid>)` followed by `provides:` and the capability tags. Example: `auth-better-auth (hybrid) — provides: auth, session, oauth`.
+- `## Gaps` — missing capabilities and a `/new-pack` suggestion, or `none`.
+- `## Command` — the last section, containing exactly one executable fenced `sh` block.
+
+Do not put any other fenced command block anywhere in the response.

package/.codex/skills/parallel-execution/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: parallel-execution
+description: Decide which board tasks can safely run at the same time and group them into execution batches. Use when the user says "what can run in parallel?", "batch the board", "can I spin up multiple agents?", or after `.ai/board.md` is built. Do NOT use as a license to fan out everything — the output may be one batch.
+# Generated from .claude/skills/parallel-execution/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: parallel-execution
+
+## Goal
+
+Read the board and produce ordered execution batches where every task inside a batch is safe to run in parallel. Conflicts are detected up front, not at merge time.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5. This is dependency analysis — do not rush it.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+- `.ai/architecture.md`
+
+## Rules
+
+- A batch is parallel-safe only if **no two tasks share**:
+  - the same files (likely-edit lists)
+  - the same database schema migration
+  - the same route or layout
+  - the same shared component
+  - the same migration / config file
+- If two tasks conflict, the later one moves to the next batch.
+- Foundations (schema, routing skeleton, theme tokens) usually go alone in Batch 1.
+- Integration / QA / deployment tasks usually go alone in the last batch.
+- Prefer **fewer, safer batches** over many micro-batches.
+- It is fine for the answer to be "no parallelism — run sequentially."
+
+## Output format
+
+```md
+## Execution batches
+
+### Batch 1 — foundations
+- <TASK-ID>: <title>
+- <TASK-ID>: <title>
+Why parallel-safe: <one line>
+
+### Batch 2 — feature work
+- ...
+
+### Batch 3 — integration / QA
+- ...
+
+## Conflicts detected
+- <TASK-A> ⇄ <TASK-B>: <shared resource>
+
+## Recommended execution mode
+- Sequential: <which tasks>
+- Parallel with worktrees / subagents: <which tasks>
+- Background: <which tasks, if any>
+
+## Notes for the executor
+- <e.g. "DB migration must finish before Batch 2 starts">
+```
+
+After returning the plan, recommend `/execute-task <ID>` for the first batch.