@benjaminthomas/spec-driven-dev 0.0.0-stage → 1.4.0

package/skills/generative-seo/assets/competitor-analysis-template.md

@@ -0,0 +1,20 @@
+# Competitor & Keyword Analysis
+
+## Competitor landscape
+
+| Competitor | Category term(s) they own | Notes |
+|---|---|---|
+| | | |
+
+## Keyword gap map
+
+| Query | Who ranks/is cited today | Should we contest it? |
+|---|---|---|
+| | | |
+
+## Changelog
+
+<!-- Append a dated entry each `competitors` run. Never delete prior entries. -->
+
+### YYYY-MM-DD
+- 

package/skills/generative-seo/assets/content-plan-template.md

@@ -0,0 +1,15 @@
+# Content Plan
+
+Status values: `todo`, `in-progress`, `blocked (reason)`, `shipped (YYYY-MM-DD)`.
+
+## Phase 0 — foundation (blockers)
+
+| Item | Target query | Status | Notes |
+|---|---|---|---|
+| | | todo | |
+
+## Phase 1
+
+| Item | Target query | Status | Notes |
+|---|---|---|---|
+| | | todo | |

package/skills/generative-seo/assets/geo-config-template.md

@@ -0,0 +1,33 @@
+---
+product_name:
+brand_name:
+domain:
+framework:
+marketing_pages_dir:
+sitemap_mechanism:
+robots_mechanism:
+design_system_doc:
+stats_source:
+docs_dir: docs/seo
+---
+
+# Brand & naming notes
+
+<!--
+Free text. If the product is a sub-brand of a parent company, or the software
+name differs from the company name, state the rule here explicitly, e.g.:
+
+"Acme Corp is the parent company (a services agency). Acme Flow is the
+product. Never write 'is Acme Corp free' or 'who is Acme Corp for' — the
+software is Acme Flow; Acme Corp builds it. Correct brand uses: legal
+operator, IP ownership, author/publisher credit."
+
+If there's no distinction (company name == product name), just say so.
+-->
+
+# House style notes
+
+<!--
+Anything specific to how this project writes: tone, banned phrases, a
+tagline that must appear consistently, units/currency conventions, etc.
+-->

package/skills/generative-seo/assets/geo-playbook-template.md

@@ -0,0 +1,22 @@
+# GEO Playbook — {{product_name}}
+
+Filled in from `geo-config.md` and `references/geo-methodology.md` in the
+generative-seo skill. This file is the project-specific source of truth — the
+skill's reference file has the general evidence; this one has what this project
+has decided to do about it.
+
+## Category / positioning
+
+<!-- What category term is this project trying to own? What's the one-line
+differentiator vs the obvious alternatives? -->
+
+## Content rules specific to this project
+
+<!-- Start from SKILL.md's non-negotiable rules; add anything specific here
+(e.g. "always include a pricing comparison table", "never use the word X"). -->
+
+## What's proven vs still a hypothesis
+
+<!-- Track which tactics this project has actually validated (ranked, got
+cited, drove signups) vs ones still being tried. Update after each `report`
+or `citations` run. -->

package/skills/generative-seo/assets/social-queue-template.md

@@ -0,0 +1,8 @@
+# Social Distribution Queue
+
+Drafts only — nothing here gets posted automatically. Review, edit into your own
+voice, paste, then flip the status marker.
+
+Status markers: `[ ] queued` → `[x] posted YYYY-MM-DD <URL>` or `[-] skipped`.
+
+<!-- Append a new dated H2 per `social` run. Never overwrite prior entries. -->

package/skills/generative-seo/references/geo-methodology.md

@@ -0,0 +1,143 @@
+# GEO Methodology Reference
+
+The evidence behind the rules in SKILL.md, and the full technical checklist for
+`audit` mode. Read this once per project before the first `audit` or `content`
+run; the summary in SKILL.md is enough for later runs.
+
+## Table of contents
+
+1. [The evidence](#the-evidence)
+2. [Technical checklist](#technical-checklist)
+3. [Sitemap / robots by framework](#sitemap--robots-by-framework)
+4. [JSON-LD schema types](#json-ld-schema-types)
+5. [AI-crawler allowlist](#ai-crawler-allowlist)
+
+---
+
+## The evidence
+
+**Answer-first placement.** Research on what generative engines (AI Overviews,
+ChatGPT search, Perplexity) actually quote found citations skew heavily toward
+early-page content — a large share of cited passages come from roughly the first
+third of the page. Practical takeaway: don't bury the direct answer under a long
+intro, definitions section, or history lesson. State it, then elaborate.
+
+**Statistics and quotable lines.** Studies analyzing what content gets cited by
+AI answer engines (Princeton's GEO paper; independent studies from SEO tooling
+vendors) found that adding concrete statistics, direct quotes, and citations to
+sources measurably increases the odds a passage gets pulled into an AI-generated
+answer — reported lifts in the 30–40%+ range for visibility, depending on the
+study and baseline. This is the single highest-leverage on-page lever available.
+
+**Extractable structure.** AI engines assemble answers from passages, not whole
+pages. Content that mirrors how people actually ask ("How do I…", "What is…",
+"X vs Y") in H2/H3 headings, uses genuine Q&A blocks, comparison tables, and a
+TL;DR/summary block gets extracted more cleanly than prose that requires reading
+top-to-bottom to make sense.
+
+**Self-contained passages.** Because retrieval is passage-level, a section that
+depends on context from three paragraphs earlier ("as mentioned above...") reads
+as incomplete when lifted alone — which is exactly how it will be consumed.
+
+**Freshness signals.** Visible author, published date, and last-updated date are
+both a trust signal to AI crawlers and a genuine correctness signal — stale
+numbers get corrected by AI engines using other sources instead. Re-verify and
+refresh anything older than about 6 months, especially anything with a number
+in it.
+
+**Structured Q&A + schema.** `FAQPage` JSON-LD gives engines an unambiguous,
+pre-parsed question/answer pair to lift verbatim — lower effort for the engine
+than extracting an answer from prose, which matters when the engine is choosing
+between two similarly good sources.
+
+**What has weak or no proven effect (don't over-invest):** `llms.txt` files and
+generic schema markup are commonly recommended but have thin independent
+evidence of directly causing AI-citation lift — treat them as cheap hygiene
+(an hour of work, do it once) rather than a strategy. The actual strategy is the
+content quality levers above, plus off-site signals (third-party mentions in
+roundups/directories/forums/video) and fast technical indexing.
+
+---
+
+## Technical checklist
+
+Run through all of these for `audit` mode; report failures with file:line.
+
+1. **Sitemap** includes every indexable page with an honest `lastModified`;
+   excludes anything robots disallows; no auth-gated URLs. See framework map below.
+2. **Robots** disallows app/API/auth routes; explicitly allows AI-answer-engine
+   bots (see allowlist below) unless the user has a specific reason to block
+   AI training/retrieval (rare — confirm before ever adding a disallow for these).
+3. Every marketing/content page has: unique `title` (not duplicating a sitewide
+   template), unique `description` (~140–160 chars), a canonical URL, and
+   OG + Twitter/X card metadata.
+4. JSON-LD present and valid — see schema-type table below.
+5. `llms.txt` in the site root — a markdown index of key pages with one-line
+   descriptions. Low proven impact; still a cheap one-time hedge (see evidence
+   section — don't over-invest beyond the first pass).
+6. All public content is server-rendered or otherwise present in the initial
+   HTML response — many AI crawlers don't execute JavaScript, so client-only
+   marketing copy is invisible to them.
+7. **Live checks**: fetch `/robots.txt`, `/sitemap.xml` (or the framework's
+   equivalent), `/llms.txt`, and the homepage on the live domain — confirm they
+   match the repo and return 200; spot-check that sitemap URLs resolve.
+8. Heading hygiene: exactly one H1 per page; H2s phrased as the questions the
+   page targets, where the page targets a specific query.
+9. Internal linking: every content page links to its category/pillar page and
+   vice versa; pillar pages link out to their spokes.
+10. Core Web Vitals sanity: no oversized unoptimized images (use the framework's
+    image component if it has one), no obvious layout shift from late-loading
+    content, no render-blocking resources that are trivially deferrable.
+
+---
+
+## Sitemap / robots by framework
+
+Confirm the actual files in the repo before assuming — frameworks change these
+mechanisms across versions.
+
+| Framework | Sitemap | Robots | Metadata |
+|---|---|---|---|
+| Next.js (App Router) | `app/sitemap.ts` (dynamic) or `public/sitemap.xml` | `app/robots.ts` or `public/robots.txt` | `generateMetadata` / static `metadata` export per route; root `metadataBase` in root layout |
+| Astro | `@astrojs/sitemap` integration (generates at build) or manual `public/sitemap.xml` | `public/robots.txt` | Per-page `<head>` in `.astro` files, or a shared `<SEO>` component |
+| Remix / React Router | A resource route returning XML (e.g. `app/routes/sitemap[.]xml.tsx`) | A resource route or `public/robots.txt` | `meta` export per route |
+| SvelteKit | `src/routes/sitemap.xml/+server.ts` | `static/robots.txt` | `<svelte:head>` per page |
+| Plain static site | Hand-maintained or generated `sitemap.xml` at the root | `robots.txt` at the root | Per-HTML-file `<head>` tags |
+| WordPress / Webflow / other CMS | Usually auto-generated by an SEO plugin (Yoast, RankMath) or the platform itself | Same — check the plugin/platform settings, don't hand-edit generated files | Plugin-managed fields per page/post |
+
+If none of these match, ask the user rather than guessing — inventing a
+mechanism that doesn't fit the framework produces code that won't build.
+
+## JSON-LD schema types
+
+| Page type | Schema | Notes |
+|---|---|---|
+| Every page (sitewide, once) | `Organization` | Name, logo, sameAs (social profiles) |
+| Homepage / pricing (for a product) | `SoftwareApplication` + `Offer` | Only if the product genuinely is software with a price; don't force this onto a services business |
+| Any page with a real FAQ | `FAQPage` | Must match the visible on-page Q&A exactly — don't add schema for content that isn't rendered |
+| Blog / article content | `Article` + `author` + `datePublished` + `dateModified` | Keep `dateModified` in sync with the visible "last updated" date |
+| Blog / article content | `BreadcrumbList` | Only where there's a real breadcrumb trail |
+| Ranked list/roundup content | `ItemList` | For "best X" style pages |
+
+Sanitize any inline JSON-LD script against injection if the data includes
+user-controlled or dynamic strings (e.g. `JSON.stringify(data).replace(/</g,
+"\\u003c")` in a Node/JS context) — this is standard defensive practice for
+inlining JSON into HTML, not framework-specific.
+
+## AI-crawler allowlist
+
+Bot user-agents to explicitly allow in `robots.txt` (or the framework's robots
+mechanism) so AI answer engines can retrieve and potentially cite the content —
+disallowing these is usually the opposite of what a project pursuing AI-search
+visibility wants:
+
+- `OAI-SearchBot`, `ChatGPT-User`, `GPTBot` (OpenAI)
+- `ClaudeBot`, `Claude-SearchBot`, `Claude-User` (Anthropic)
+- `PerplexityBot`, `Perplexity-User` (Perplexity)
+- `Bingbot`, `Google-Extended` (Microsoft/Google AI training + retrieval)
+- `CCBot` (Common Crawl — feeds many downstream AI training sets)
+
+If the user has an explicit reason to keep content out of AI training data
+(e.g. a paywalled or licensed-content business model), confirm before adding
+these — the default recommendation is "allow all" for anyone wanting AI-search
+visibility, but that's not universal.

package/skills/spec-checkpoint/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: spec-checkpoint
+description: >
+  Create a comprehensive checkpoint commit with detailed analysis of all changes. Use this skill
+  when the user says "checkpoint", "commit everything", "save my progress", "create a commit",
+  or wants to stage and commit all current changes with a well-crafted message. Also use when
+  the user says "/spec-checkpoint" (or their host's equivalent invocation syntax) or asks to
+  snapshot current work. This skill stages all changes and creates a descriptive commit — it
+  does not push.
+license: MIT
+---
+
+# Checkpoint Commit
+
+Create a checkpoint commit that captures all current changes — but only after the code passes lint, type check, and build.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `commands` (lint/typecheck/test/build), `git.commit_style`, and `layout`/`repos`.
+
+**Multi-repo:** run this in every listed repo that has changes, making one commit per repo with the same subject. **Monorepo:** run the checks for the packages that changed, or the root commands if that's how the repo works.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## Instructions
+
+### Step 1: Analyze Changes
+
+Run these commands to understand the full picture:
+
+1. `git status` — see all tracked and untracked files
+2. `git diff` — see detailed changes in tracked files
+3. `git diff --cached` — see already-staged changes
+4. `git log -5 --oneline` — understand this repo's commit message style
+
+### Step 2: Quality Checks
+
+Use `commands` from `.spec-driven.yml`. For any that are missing, find the repo's own lint, typecheck, test, and build commands — `package.json` scripts (with the
+repo's package manager), `Makefile`, `pyproject.toml`, `Cargo.toml`, CI config, or `CLAUDE.md`/
+`AGENTS.md`. Run each one the repo has; skip (and say so) any it doesn't. If any fail, fix the
+issues before proceeding — do not skip or ignore failures.
+
+Iterate until every check passes cleanly. Only then move to the next step.
+
+### Step 3: Stage Everything
+
+Stage all changes — tracked modifications, deletions, and new untracked files:
+
+```bash
+git add -A
+```
+
+Then review `git status` again. If anything staged looks like it could hold secrets —
+`.env*`, `*.pem`, `*_rsa`, `credentials.json`, `secrets.*`, or an unfamiliar filename that might
+contain an API key — unstage it (`git restore --staged <file>`) and tell the user what was
+excluded and why, rather than committing it silently. Don't rely on the filename alone for
+anything you don't recognize; skim its diff if you're unsure.
+
+### Step 4: Craft the Commit Message
+
+Write a commit message in the config's `git.commit_style` (`conventional` → `feat: …`, `ticket` → `STP-123: …` using the ticket ID from the branch name, `freeform`). Without config, follow the project's existing conventions (observed from `git log`). Structure:
+
+- **First line**: clear, concise summary in imperative mood (50-72 chars)
+  - Use conventional commit prefixes where the project uses them: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`, etc.
+- **Body** (separated by blank line): a short TL;DR of the changes — 1-3 sentences max. No bullet lists, no file-by-file breakdowns, no lengthy explanations.
+- **Footer**: co-author attribution, naming whichever agent/model is actually running this
+  skill — never hardcode a specific vendor or model name, since this skill runs under many
+  different hosts
+
+### Step 5: Commit
+
+Create the commit using a heredoc for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+{first line}
+
+{tldr}
+
+Co-Authored-By: {agent name} <noreply@example.com>
+EOF
+)"
+```
+
+Fill in `{agent name}` with whatever the current agent/model actually identifies as (e.g. "Claude", "Codex", "Cursor Agent") — if your host has no clean way to identify itself, omit the footer entirely rather than guessing.
+
+### Step 6: Report
+
+Display:
+- The commit hash and message summary
+- Files changed count
+- Insertions/deletions summary
+
+## Important
+
+- Stage and commit everything except files that look like secrets or credentials (see Step 3) — check contents, not just filenames, before assuming something is safe to commit
+- If the repo has no git history, run `git init` first
+- All quality checks (lint, type-check, build) MUST pass before committing — fix issues, don't skip them
+- Keep the commit body short — a TL;DR, not an essay
+- Follow the project's existing commit conventions (check the log first)
+- Do not push — only commit locally

package/skills/spec-create/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-create
+description: >
+  Create a structured feature specification with self-contained task files organized into
+  parallel execution batches. Use this skill when the user says "create a spec", "plan this feature",
+  "write up an implementation plan", "break this into tasks", or after any planning conversation
+  where the user wants to capture decisions as actionable spec files. Also use when the user
+  says "/spec-create" (or their host's equivalent invocation syntax) or wants to decompose a
+  feature into work items that agents can implement independently. This skill produces local
+  spec files under specs/{feature}/ — no GitHub integration.
+license: MIT
+---
+
+# Create Feature Specification
+
+Transform a planning conversation into a structured spec folder that enables parallel agent implementation. The spec breaks a feature into self-contained task files — each one detailed enough that a coder agent can pick it up cold and implement it without reading anything else.
+
+The key insight: implementation plans that live in a single file are either too large for a context window or too shallow for independent execution. By splitting into one file per task with full context in each, we enable multiple agents to work in parallel while keeping each agent's context focused.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `layout`/`repos` and `specs_dir`.
+
+**Monorepo / multi-repo:** every task names its package or repo, and its file paths are relative to that. Keep each task inside one repo. Cross-repo work becomes separate tasks, with the contract (API shape, event, schema) written into both.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## When to Use
+
+- After a planning conversation where requirements and technical details have been discussed
+- When the user asks to create a spec, plan a feature, or break work into tasks
+- When the user wants to prepare work for parallel agent implementation
+
+## Instructions
+
+### Step 1: Gather Requirements
+
+If a `{specs_dir}/*/investigation.md` (default `specs/`) from `spec-investigate` exists for this work, read it first and treat it as the evidence base: carry its VERIFIED facts, affected files, risks, and acceptance criteria into the spec, reuse its folder (`specs/{feature-slug}/`) instead of naming a new one in Step 2, and turn its open questions/UNKNOWNs into items for the user or `action-required.md` rather than guessing.
+
+If the conversation already contains planning context (requirements discussed, technical decisions made, architecture outlined), extract all of it. Review the entire conversation to ensure nothing is lost — the spec is the single source of truth, and anything not captured here disappears.
+
+If no planning conversation exists, interview the user:
+- What does this feature do and why does it matter?
+- What are the acceptance criteria?
+- What technical constraints or decisions have been made?
+- What files, APIs, schemas, or patterns are involved?
+
+### Step 2: Name the Feature
+
+Choose a kebab-case name that clearly identifies the feature (e.g., `add-user-auth`, `migrate-to-postgres`, `dashboard-redesign`). This becomes the folder name under `specs/`.
+
+### Step 3: Decompose into Tasks
+
+Break the implementation into atomic tasks. Each task should:
+- Be completable in a single coding session by one agent
+- Have a clear, specific scope (one concern per task)
+- Produce working, testable code when complete
+- Not overlap in files modified with other tasks in the same batch
+
+Think carefully about granularity. Too coarse and agents can't work in parallel. Too fine and the overhead of context-switching between tasks dominates. A good task typically creates or modifies 1-5 files around a single concern.
+
+Tests ship with the code they cover: fill in each task's **Tests** section (see the task template) instead of creating separate "write tests" tasks. Only add a standalone testing task for cross-cutting suites (e.g. a new E2E harness) or when the user asks for one.
+
+### Step 4: Build the Dependency Graph
+
+For each task, identify:
+- **What it depends on**: which tasks must complete before this one can start
+- **What depends on it**: which tasks are blocked until this one finishes
+
+Tasks with no dependencies form Batch 1. Tasks whose dependencies are all in Batch 1 form Batch 2. And so on. All tasks within a batch can execute in parallel.
+
+When assigning batches, verify that tasks within the same batch do not modify overlapping files. If two tasks in the same batch would touch the same file, move one to a later batch — parallel agents on the same branch cannot safely modify the same file.
+
+### Step 5: Create the Spec Folder
+
+Create the following structure at `specs/{feature-name}/`:
+
+```
+specs/{feature-name}/
+├── README.md
+├── requirements.md
+├── action-required.md
+└── tasks/
+    ├── task-01-{name}.md
+    ├── task-02-{name}.md
+    └── ...
+```
+
+Read the templates in `references/` before writing each file:
+- `references/readme-template.md` — for the README (dependency graph, batch table, status tracking)
+- `references/task-template.md` — for each task file (self-contained with all context)
+- `references/requirements-template.md` — for the requirements document
+- `references/action-required-template.md` — for manual human steps
+
+Task files are numbered with zero-padded two-digit prefixes in topological order: Batch 1 tasks first, then Batch 2, etc. Within a batch, order is arbitrary but stable.
+
+### Step 6: Write Self-Contained Task Files
+
+This is the most important step. Each task file is the **only thing** a coder agent will read before implementing. It must contain everything the agent needs:
+
+- **Description**: what to build and why it matters in context
+- **Dependency context**: what prior tasks produce that this task needs (summarized in prose, not just filenames). The agent should not need to read other task files.
+- **Technical details**: CLI commands, code snippets, schemas, file paths, env vars, API endpoints — every implementation-specific detail from the planning conversation
+- **Files to create/modify**: explicit list with purpose for each
+- **Acceptance criteria**: specific, verifiable conditions
+
+Review each task file with fresh eyes: could an agent who has never seen the planning conversation implement this correctly using only this file? If not, add what's missing.
+
+### Step 7: Extract Manual Actions
+
+Identify any steps that require human action (account creation, API key setup, DNS configuration, environment variables, third-party service registration, etc.). Write these to `action-required.md` grouped by timing (Before/During/After implementation). If none exist, note "No manual steps required."
+
+### Step 8: Report to User
+
+After creating the spec, display:
+
+```
+Feature specification created at specs/{feature-name}/
+
+Files created:
+- README.md (dependency graph, {N} batches, {T} tasks)
+- requirements.md
+- action-required.md
+- tasks/ ({T} task files)
+
+Batch breakdown:
+- Batch 1: {count} tasks (parallel) — {brief description}
+- Batch 2: {count} tasks (parallel) — {brief description}
+- ...
+
+Next steps:
+1. Review action-required.md for tasks you need to complete manually
+2. Review the requirements and task files
+3. Use /spec-implement to start parallel implementation
+```
+
+## Critical Rules
+
+- Every task file must be fully self-contained — this is the entire point of the spec structure. A coder agent reading only that file must know exactly what to do.
+- Capture ALL technical details from the planning conversation. The spec is the single source of truth — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. Anything not captured here is lost.
+- Tasks within the same batch must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
+- Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
+- Put tests in each task's Tests section, not in separate testing tasks (unless the user asks, or it's a cross-cutting suite).
+- Number task files in topological order (batch 1 first, then batch 2, etc.) for easy scanning.

package/skills/spec-create/references/action-required-template.md

@@ -0,0 +1,53 @@
+# Action Required Template
+
+Use this structure for the action-required.md at the root of each spec folder. This file captures manual steps that require human action and cannot be automated by agents.
+
+## Template (when manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+Manual steps that must be completed by a human. These cannot be automated.
+
+## Before Implementation
+
+- [ ] **{Action}** — {Brief reason why this is needed}
+- [ ] **{Action}** — {Brief reason}
+
+## During Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+## After Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+---
+
+> These tasks are also referenced in context within the relevant task files.
+```
+
+## Template (when no manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+No manual steps required for this feature. All tasks can be implemented automatically.
+```
+
+## Common Manual Steps
+
+- Account creation (third-party services, OAuth apps)
+- API key generation and setup
+- Environment variable configuration
+- DNS or domain settings
+- Billing or subscription setup
+- Third-party service registration (webhooks, integrations)
+- Certificate provisioning
+- Access permissions or IAM roles
+
+## Key Points
+
+- Group actions by timing: before, during, and after implementation. This helps the user know when they need to act.
+- Keep descriptions brief — one line explaining what to do and why.
+- Also reference these manual steps in the relevant task files so agents know to pause or skip that part.

package/skills/spec-create/references/readme-template.md

@@ -0,0 +1,53 @@
+# README Template
+
+Use this structure for the README.md at the root of each spec folder. The README serves as the orchestration index — the `spec-implement` skill reads it to determine batch order, task assignments, and completion status.
+
+## Template
+
+```markdown
+# {Feature Name}
+
+## Overview
+
+{One paragraph summary of what the feature does and why it exists.}
+
+## Quick Links
+
+- [Requirements](./requirements.md) — full requirements and acceptance criteria
+- [Action Required](./action-required.md) — manual steps needing human action
+
+## Dependency Graph
+
+​```mermaid
+graph TD
+    task-01-name["01: Task Title"]
+    task-02-name["02: Task Title"]
+    task-03-name["03: Task Title"]
+    task-01-name --> task-03-name
+    task-02-name --> task-03-name
+​```
+
+## Batches
+
+| Batch | Tasks | Description |
+|------|-------|-------------|
+| 1 | task-01, task-02 | {Brief description of what this batch accomplishes} |
+| 2 | task-03 | {Brief description} |
+
+## Task Status
+
+### Batch 1
+- [ ] [task-01-{name}](./tasks/task-01-{name}.md) — {One-line title}
+- [ ] [task-02-{name}](./tasks/task-02-{name}.md) — {One-line title}
+
+### Batch 2
+- [ ] [task-03-{name}](./tasks/task-03-{name}.md) — {One-line title}
+```
+
+## Key Points
+
+- The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
+- The **Batches** table provides a scannable overview of what runs in parallel.
+- The **Task Status** section uses markdown checkboxes that the `spec-implement` skill updates as tasks complete. The orchestrator parses these to determine which batch to resume from.
+- Links to task files use relative paths pointing into the `tasks/` subfolder.
+- Tasks without dependencies have no incoming arrows in the graph — these form Batch 1.

package/skills/spec-create/references/requirements-template.md

@@ -0,0 +1,54 @@
+# Requirements Template
+
+Use this structure for the requirements.md at the root of each spec folder.
+
+## Template
+
+```markdown
+# Requirements: {Feature Name}
+
+## Summary
+
+{What the feature does and why it exists — 2-3 paragraphs covering the problem, the solution, and the expected outcome.}
+
+## Goals
+
+- {Goal 1}
+- {Goal 2}
+- {Goal 3}
+
+## Non-Goals
+
+{Explicitly out of scope — things that might seem related but are not part of this feature.}
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Acceptance Criteria
+
+{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Assumptions
+
+{Things assumed to be true that could affect implementation if they turn out to be false.}
+
+- {Assumption 1}
+- {Assumption 2}
+
+## Technical Constraints
+
+{Architecture decisions, technology choices, or constraints that affect all tasks.}
+
+- {Constraint 1}
+- {Constraint 2}
+```
+
+## Key Points
+
+- The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
+- Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.