@forgeailab/create-spark 0.1.2 → 0.2.0

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

@@ -0,0 +1,76 @@
+---
+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`.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# 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/.claude/skills/ux-theme/SKILL.md

@@ -0,0 +1,93 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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/.codex/skills/architecture-cutline/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: architecture-cutline
+description: Pick the simplest architecture that can ship the MVP. Use after `.ai/product-spec.md` exists, when the user says "what stack?", "design the architecture", or before scaffolding code. Do NOT use for greenfield exploration without a spec — run `/mvp-spec` first.
+# Generated from .claude/skills/architecture-cutline/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: architecture-cutline
+
+## Goal
+
+Produce `.ai/architecture.md` — the smallest viable technical plan that can ship the spec. Your job is to **aggressively cut**, not to design a beautiful system.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/decision-log.md`
+
+Read these if present:
+
+- `templates/*/template.toml`
+- `packs/*/pack.toml`
+- `presets/*.toml`
+
+If `product-spec.md` is missing, stop and tell the user to run `/mvp-spec` first.
+
+## Rules
+
+- **Default to boring.** Pick the stack the user already knows over the one that scores higher on Twitter.
+- **One database.** No microservices. No event bus. No queues unless the spec literally requires async work.
+- For every decision, also write what you are **NOT building yet**. This is the cutline.
+- If the spec implies something exotic (realtime collab, ML inference, search, multi-tenancy), call it out and propose a faked version for v1.
+- Respect prior choices in `.ai/decision-log.md` unless they conflict with the spec.
+- Choose a scaffold template before choosing packs. Prefer `nextjs` for v1 unless the spec clearly fits a registered planned template; if a planned template is the right destination, name it as planned and give the `nextjs` interim path.
+- Recommend only packs that exist in `packs/*/pack.toml`. Do not recommend a capability if no v1 pack provides it.
+- If the spec implies a capability with no v1 pack, name the gap explicitly in the pack plan and suggest `/new-pack` to author one.
+
+## Output format
+
+Write `.ai/architecture.md` with these sections:
+
+````md
+# Architecture — <name>
+
+## Decision summary
+<one paragraph: the shape of the system in plain English>
+
+## Stack
+- Frontend:
+- Backend / API:
+- Database:
+- Auth:
+- Storage:
+- Payments:
+- Deployment:
+- Testing:
+
+For each, one line on WHY this choice over the obvious alternative.
+
+## Pack plan
+- Chosen scaffold: <template name> (<stable | planned, not yet implemented; use nextjs as interim>)
+- Recommended packs:
+  - <pack-name>: provides <capability tag(s)>; satisfies <spec need>
+- Gaps:
+  - <capability tag>: no v1 pack exists — run `/new-pack` to author one
+  - none
+
+```sh
+spark add <pack-1> <pack-2>
+```
+
+## Repo structure
+<tree of top-level folders only>
+
+## Data model (concrete)
+<tables/collections with columns and types — short>
+
+## API surface (concrete)
+<routes or actions, grouped by feature>
+
+## What we are NOT building yet
+- <thing>: <reason — "fake with X for MVP" or "v2">
+(at least 5 entries; this is the cutline)
+
+## Risks and rollback
+<2–4 risks with a simpler fallback for each>
+````
+
+After writing, append the key choices to `.ai/decision-log.md` and recommend `/ux-theme` or `/mvp-board` next.

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

@@ -0,0 +1,75 @@
+---
+name: board-review
+description: Sanity-check `.ai/board.md` before any task moves to `Approved for execution`. The approval gate between planning and execution. Use after `/mvp-board`, when the user says "is the board good?", "review the plan", or before kicking off coding. Do NOT skip this gate — it is the plan/review/approve boundary the whole system depends on.
+# Generated from .claude/skills/board-review/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: board-review
+
+## Goal
+
+This is the **technical-founder review** that turns a draft board into one approved for execution. Catch the mistakes that compound: missing tasks, oversized tasks, wrong dependencies, risky parallel batches, and overbuilt scope.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read if available:
+
+- `.ai/ux-theme.md`
+- `.ai/decision-log.md`
+
+## Rules
+
+- The whole board does not have to pass at once. You may approve some epics while sending others back.
+- After review, set the status on approved tasks to `Approved for execution`. Tasks needing changes go to `Clarifying` with a note.
+- Verdict per task is binary: **Approved** or **Needs changes**.
+- The reviewer is read-only on code, but **may edit `.ai/board.md`** to flip statuses, split oversized tasks, or add missing tasks.
+
+## Checklist
+
+Walk the board and flag:
+
+- **Missing tasks** — anything in the spec's acceptance criteria with no task covering it.
+- **Oversized tasks** — touches > 5 files, > 3 acceptance criteria, or > one focused session.
+- **Wrong dependencies** — task B depends on A but A does not produce what B needs; or hidden dependency not declared.
+- **Risky parallel batches** — tasks marked parallel-safe that actually share files, schema, routes, or shared components.
+- **Overbuilt parts** — tasks for things the spec's non-goals ruled out.
+- **Vague acceptance criteria** — not observable / testable.
+- **No core-flow-first ordering** — auth or dashboards scheduled before the user's primary action.
+
+## Output format
+
+```md
+## Board review
+
+### Verdict per epic
+- EPIC 1 — <Approved | Needs changes>
+- EPIC 2 — <Approved | Needs changes>
+
+### Issues
+- <TASK-ID>: <category> — <what's wrong> — <suggested fix>
+
+### Tasks to add
+- <NEW-ID>: <title> — <why missing>
+
+### Tasks to split
+- <TASK-ID> → <NEW-ID-a>, <NEW-ID-b>, ...
+
+### Status flips applied to board.md
+- <TASK-ID>: <old> → Approved for execution
+- <TASK-ID>: <old> → Clarifying (<reason>)
+
+### Recommended next
+Run `/parallel-execution` on approved tasks, then `/implementation-brief <ID>`.
+```
+
+After writing the review, edit `.ai/board.md` to apply the status flips. Do not invent new fields — only change statuses and (if explicitly approved by the user) split tasks.

package/.codex/skills/code-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: code-review
+description: Review a completed task's implementation against its acceptance criteria as an independent evaluator, not the implementer. Use after `/execute-task`, when the user says "review this", "is this done?", or before marking a task `Validated`. Do NOT use to fix code — propose patches; only edit when the user explicitly asks.
+# Generated from .claude/skills/code-review/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: code-review
+
+## Goal
+
+Act as the independent reviewer in the planner/implementer/evaluator loop. The implementer is too generous about its own output — your job is to catch what they missed before a task moves to `Validated`.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for high-risk tasks (auth, payments, data migrations, schema, security). Sonnet 4.6 is fine for routine UI/CRUD tasks.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — locate the task and its acceptance criteria
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- the actual diff: `git diff` for unstaged, `git diff --staged`, or `git diff <base>...HEAD`
+
+Read if relevant:
+
+- `.ai/ux-theme.md` for UI tasks
+- `.ai/decision-log.md`
+
+## Rules
+
+- **Read-only by default.** Propose patches in prose. Do not edit files unless the user asks.
+- Check acceptance criteria **one by one**, citing the evidence in the diff (file:line). If a criterion is not verifiable from the diff, say so — do not assume.
+- Look beyond the criteria for: security holes, missing error handling at system boundaries, secrets in code, broken types, unused/dead code added by the executor, scope creep (edits outside the task's declared file list).
+- Distinguish **blocking** issues (must-fix before done) from **nits** (optional). Pile of nits is not a failed review.
+- The verdict is binary: **Pass** or **Needs changes**. No "pass with reservations."
+
+## Workflow
+
+1. Read the task, criteria, and the diff.
+2. Walk through each acceptance criterion against the code.
+3. Scan for security / boundary / scope-creep issues.
+4. Write the verdict.
+
+## Output format
+
+```md
+## Code review — <TASK-ID>: <title>
+
+### Verdict
+Pass | Needs changes
+
+### Acceptance criteria
+- [x|✗] <criterion>
+  Evidence: <file:line> — <one line>
+
+### Blocking issues
+- <file:line> — <problem> — <suggested fix>
+
+### Nits
+- <file:line> — <minor>
+
+### Scope check
+- Files edited match task's declared list: yes | no (<list of out-of-scope files>)
+- New dependencies added: <list or none>
+
+### Security / boundary check
+- <finding or "no issues found">
+
+### Recommended board update
+Status: review → Validated | review → In progress (needs changes)
+```

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

@@ -0,0 +1,76 @@
+---
+name: execute-task
+description: Implement exactly one board task end-to-end, then report changes and a suggested board update. Use when the user says "do TASK-X", "execute the next task", "implement AUTH-001", or hands a task ID to the agent. Do NOT use without a task ID — ask which task, or run `/next-task` first.
+# Generated from .claude/skills/execute-task/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: execute-task
+
+## Goal
+
+Execute one and only one task from `.ai/board.md`, without touching unrelated areas. The output is code changes plus a clean report the user can paste back into the board.
+
+## Recommended model
+
+Sonnet 4.6 (or a comparable cheaper executor). Planning-quality models are overkill here unless the task is marked high-risk.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — locate the task by ID
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read if they exist:
+
+- `.ai/ux-theme.md`
+- `.ai/decision-log.md`
+- A prior `/implementation-brief` for this task if the user provided one
+
+If the task ID is missing, already `Validated`, or not in status `Approved for execution`, stop and tell the user. Approval comes from `/board-review`, not from this skill.
+
+## Rules
+
+- **Do exactly the task in the brief.** No bonus refactors, no "while I'm here" cleanups.
+- If you discover work outside scope, write it down as a follow-up task in the report. Do not silently expand.
+- Stay inside `Files likely to edit` unless a real blocker forces otherwise — then explain why in the report.
+- After editing, run the verification command(s) from the brief. If they fail, fix and re-run. If you cannot fix, mark the task `blocked` with a specific reason.
+- Do not edit `.ai/board.md` directly here — propose the status change in the report and let `/sync-board` apply it.
+- Never mark a task `done` if acceptance criteria are not all checked.
+
+## Workflow
+
+1. Re-read the task, brief, and any spec/architecture sections it touches.
+2. Plan the edits in your head (or in TodoWrite if non-trivial).
+3. Make the changes.
+4. Run verification (build / typecheck / tests / the specific command from the brief).
+5. Write the report.
+
+## Output format
+
+```md
+## Task <ID>: <title> — execution report
+
+### Changed files
+- <path>: <one-line description>
+
+### Acceptance criteria check
+- [x] <criterion> — <how it was verified>
+- [ ] <criterion> — <why not yet>
+
+### Verification
+- Command: `<cmd>`
+- Result: passed | failed | not run (with reason)
+
+### Suggested board update
+Status: In progress → Needs review | Blocked
+(if Blocked) Reason: <specific>
+Validation state: not started
+
+### Follow-up tasks discovered
+- <short title>: <one-line scope>
+
+### Next
+Run `/code-review <ID>` (independent evaluator), then `/qa-verify` for user-facing changes, then `/sync-board` to apply state.
+```

package/.codex/skills/idea-sharpen/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: idea-sharpen
+description: Turn a weak or broad product idea into 2–3 sharper MVP angles and recommend one. Use when the user has an idea but is unsure of the angle, says "is this a good idea?", "what's the best version of this?", or "should I do X or Y?". Do NOT use after the angle is already chosen — switch to `/mvp-grill` or `/mvp-spec`.
+# Generated from .claude/skills/idea-sharpen/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: idea-sharpen
+
+## Goal
+
+Act as a product strategist. Take a vague idea and produce three concrete MVP angles with real tradeoffs, then recommend one. Challenge the idea — do not validate it.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/product-spec.md`
+- `.ai/decision-log.md`
+
+## Rules
+
+- Produce exactly **three angles**, not more. More options means less commitment.
+- Each angle must be genuinely different — not three flavors of the same idea.
+- Each angle must name a specific target user and the core user action.
+- Pick a winner. "It depends" is not an output.
+- Call out what is weak about the original idea. Do not soften.
+- Do not write code, scaffold files, or commit to a stack here.
+
+## Output format
+
+```
+## Original idea
+<one-sentence restatement, sharper than the user's>
+
+## What is weak about it
+<2–4 bullets: vague user, crowded space, no clear pull, etc.>
+
+## Angle A — Fastest MVP
+- Target user:
+- Core action:
+- What it does NOT do:
+- Time to first usable version:
+- Why this could win:
+- Why this could fail:
+
+## Angle B — Most differentiated
+<same shape>
+
+## Angle C — Most monetizable
+<same shape>
+
+## Recommendation
+<one of A/B/C, with the single reason that decides it>
+
+## Next
+Run `/mvp-grill` on the chosen angle.
+```
+
+Append the chosen angle to `.ai/decision-log.md` with the reasoning.

package/.codex/skills/implementation-brief/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: implementation-brief
+description: Generate the exact prompt an executor (Sonnet / Claude Code) should receive to implement one board task without wandering. Use when the user says "give Claude Code the prompt for TASK-X", "prep this task for execution", or right before handing a task to an executor. Do NOT use to actually run the task — that is `/execute-task`.
+# Generated from .claude/skills/implementation-brief/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: implementation-brief
+
+## Goal
+
+Produce a tight, executor-ready brief for one specific board task. The brief is the contract that stops the executor from inventing scope.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 (planning-quality model writes the brief; cheaper model executes it).
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — find the task by ID
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+
+Read if they exist:
+
+- `.ai/ux-theme.md`
+- `.ai/decision-log.md`
+
+If the task ID is not in `board.md`, stop and ask the user.
+
+## Rules
+
+- One task per brief. Never bundle.
+- The brief must be **self-contained** — an executor should not need to re-read the spec to do the work.
+- Quote the acceptance criteria from the board verbatim. Do not paraphrase.
+- List files **to inspect first** separately from files **likely to edit**. Reading comes before writing.
+- Include the exact verification command(s) the executor must run before declaring done.
+- Forbid anything not in scope by name.
+
+## Output format
+
+Return a single fenced block the user can copy into the executor:
+
+```
+# Task brief — <ID>: <title>
+
+## Context
+<2–4 sentences pulled from spec and architecture>
+
+## Goal
+<single sentence>
+
+## Non-goals
+- <thing not to do>
+- <thing not to refactor>
+
+## Acceptance criteria (verbatim from board)
+- [ ] ...
+- [ ] ...
+
+## Files to inspect first
+- <path> — <why>
+
+## Files likely to edit
+- <path>
+
+## UX / theme constraints (if relevant)
+<short reference to `.ai/ux-theme.md` patterns>
+
+## Commands to run
+- <install / build / test>
+
+## Definition of done
+1. Acceptance criteria check, item by item.
+2. Verification command exits 0.
+3. List changed files and one-line per change.
+4. Suggest board status update.
+5. List any follow-up tasks discovered.
+
+## Out of scope (do not touch)
+- <area / file / feature>
+```
+
+After returning the brief, recommend `/execute-task <ID>` as the next step.