@forgeailab/create-spark 0.1.2 → 0.2.0

package/.claude/skills/architecture-cutline/SKILL.md

@@ -0,0 +1,96 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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/.claude/skills/board-review/SKILL.md

@@ -0,0 +1,77 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Edit
+---
+
+# 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/.claude/skills/code-review/SKILL.md

@@ -0,0 +1,76 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+---
+
+# 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/.claude/skills/execute-task/SKILL.md

@@ -0,0 +1,80 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# 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/.claude/skills/idea-sharpen/SKILL.md

@@ -0,0 +1,65 @@
+---
+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`.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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/.claude/skills/implementation-brief/SKILL.md

@@ -0,0 +1,87 @@
+---
+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`.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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.

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

@@ -0,0 +1,95 @@
+---
+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`.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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/.claude/skills/mvp-grill/SKILL.md

@@ -0,0 +1,60 @@
+---
+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.
+allowed-tools:
+  - Read
+  - Write
+---
+
+# 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.