@oaklandzoo/ostup 0.3.0 → 0.5.0

package/src/brief/sample-briefs.mjs

@@ -0,0 +1,304 @@
+// brief/sample-briefs.mjs: fixture briefs used by tests + dry-run flows. One per profile.
+
+import { SCHEMA_VERSION } from './schema.mjs';
+
+export const BOOKING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'lodge-booking',
+    display_name: 'Lodge Booking',
+    summary: 'A booking site for a boutique ski lodge with deposits, calendar sync, and a guest dashboard.',
+    owner_or_client: 'Hakuba Lodge LLC',
+  },
+  classification: {
+    site_profile: 'booking',
+    confidence: 0.94,
+    why: ['Booking + deposit explicit', 'Calendar/availability is a core flow', 'Guest dashboard implied'],
+    secondary_profiles: ['saas-dashboard'],
+  },
+  audience: { primary: 'small_business', buyer: 'Lodge owner', end_users: ['Travel guests', 'Lodge admins'] },
+  business_model: {
+    types: ['booking_revenue', 'deposit'],
+    pricing_notes: '$200-600/night peak; 30% deposit at booking',
+  },
+  scope: {
+    must_have_sections: ['hero', 'availability calendar', 'rooms', 'amenities', 'about', 'contact'],
+    core_flows: ['booking', 'payment', 'contact_form'],
+    non_goals: ['Channel manager integration v1', 'Multi-property support v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'Booking', fields: ['date_start', 'date_end', 'guest_name', 'status', 'deposit_status'], source: 'intake' },
+      { name: 'Room', fields: ['name', 'capacity', 'nightly_rate'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres', 'blob'],
+  },
+  brand: {
+    vibe: ['warm', 'rustic', 'premium'],
+    inspiration_urls: [],
+    color_notes: 'Espresso, sand, walnut. Earthy.',
+    font_notes: 'Serif header + clean sans body.',
+    logo_notes: 'Mountain silhouette + lodge name.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'booking',
+    addons: ['postgres', 'email', 'payments'],
+    template_paths: ['templates/base', 'templates/profiles/booking'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can request dates for a room',
+      'Admin receives booking-request email',
+      'Deposit checkout can be initiated',
+    ],
+    visual_checks: ['Hero readable on mobile', 'Calendar mobile-friendly'],
+    deploy_checks: ['Live URL returns 200', 'OG image renders'],
+  },
+};
+
+export const SAAS_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'tasktrace',
+    display_name: 'TaskTrace',
+    summary: 'A SaaS dashboard for solo founders to trace AI agent actions across their codebases.',
+    owner_or_client: 'GG Solo',
+  },
+  classification: {
+    site_profile: 'saas-dashboard',
+    confidence: 0.92,
+    why: ['Subscription billing planned', 'Auth + dashboard required', 'Multi-tenant data implied'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'founder', buyer: 'Solo dev', end_users: ['Solo developers', 'Small teams'] },
+  business_model: {
+    types: ['subscription', 'dashboard'],
+    pricing_notes: '$19/mo solo, $49/mo team',
+  },
+  scope: {
+    must_have_sections: ['landing hero', 'pricing', 'login', 'dashboard shell', 'settings', 'billing'],
+    core_flows: ['auth', 'payment', 'dashboard', 'contact_form'],
+    non_goals: ['Custom roles v1', 'SSO v1'],
+  },
+  data_model: {
+    needs_storage: true,
+    entities: [
+      { name: 'User', fields: ['email', 'name', 'created_at', 'plan'], source: 'intake' },
+      { name: 'Trace', fields: ['user_id', 'repo', 'agent', 'action', 'timestamp'], source: 'intake' },
+    ],
+    recommended_storage: ['postgres'],
+  },
+  brand: {
+    vibe: ['credible', 'fast', 'minimal'],
+    inspiration_urls: ['https://linear.app', 'https://vercel.com'],
+    color_notes: 'Dark mode default. Neutral grays + one accent.',
+    font_notes: 'Geist or system sans.',
+    logo_notes: 'Geometric mark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'production_2_4_weeks',
+    budget_posture: 'under_50_month',
+    must_use: ['Stripe', 'Neon'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'saas-dashboard',
+    addons: ['auth', 'payments', 'postgres'],
+    template_paths: ['templates/base', 'templates/profiles/saas-dashboard'],
+  },
+  verification: {
+    acceptance_tests: [
+      'User can sign up and log in',
+      'Stripe subscription can be initiated',
+      'Authenticated user sees the dashboard shell',
+    ],
+    visual_checks: ['Dashboard readable on mobile', 'Login page focused on the form'],
+    deploy_checks: ['Live URL returns 200 unauthenticated landing', 'Auth flow round-trips'],
+  },
+};
+
+export const BLOG_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'goodshin-notes',
+    display_name: 'Goodshin Notes',
+    summary: 'A content engine for technical essays and case studies, MDX-based, SEO-first, with RSS and sitemap.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'blog',
+    confidence: 0.93,
+    why: ['Content engine explicit', 'MDX requested', 'SEO + RSS are core flows'],
+    secondary_profiles: ['portfolio'],
+  },
+  audience: { primary: 'creator', buyer: 'GG', end_users: ['Engineers', 'Indie hackers', 'Designers'] },
+  business_model: {
+    types: ['content_traffic', 'brand_awareness'],
+    pricing_notes: 'No revenue v1; lead-gen for consulting',
+  },
+  scope: {
+    must_have_sections: ['homepage with latest 6', 'individual post page', 'tag index', 'about', 'rss', 'sitemap'],
+    core_flows: ['content_crud', 'newsletter'],
+    non_goals: ['Member-gated posts v1', 'Comments v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Post', fields: ['title', 'slug', 'date', 'tags', 'body_mdx'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['quiet', 'opinionated', 'craft'],
+    inspiration_urls: ['https://overreacted.io', 'https://jvns.ca'],
+    color_notes: 'Off-white background, dark text, restrained accent.',
+    font_notes: 'Serif headers, mono code, sans body.',
+    logo_notes: 'Wordmark only.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: [],
+    must_avoid: ['JS-heavy content tools', 'analytics that track readers'],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'blog',
+    addons: ['mdx'],
+    template_paths: ['templates/base', 'templates/profiles/blog'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can read a post',
+      'RSS feed validates',
+      'Sitemap includes every post',
+    ],
+    visual_checks: ['Post body has comfortable line length', 'Code blocks readable on mobile'],
+    deploy_checks: ['Live URL returns 200', '/rss.xml returns valid XML'],
+  },
+};
+
+export const LEAD_GEN_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'palm-roofing',
+    display_name: 'Palm Roofing Co.',
+    summary: 'A lead-gen site for a roofing company that captures contact requests and routes them to the owner by email.',
+    owner_or_client: 'Palm Roofing Co.',
+  },
+  classification: {
+    site_profile: 'lead-gen',
+    confidence: 0.95,
+    why: ['Service company explicit', 'Contact-request flow is the primary action', 'No ecommerce signals'],
+    secondary_profiles: ['marketing'],
+  },
+  audience: { primary: 'small_business', buyer: 'Roofing co. owner', end_users: ['Homeowners with roof issues'] },
+  business_model: {
+    types: ['lead_capture', 'brand_awareness'],
+    pricing_notes: 'Free quotes; revenue is offline at job acceptance',
+  },
+  scope: {
+    must_have_sections: ['hero', 'services', 'service area', 'testimonials', 'faq', 'contact form'],
+    core_flows: ['contact_form'],
+    non_goals: ['Online payments v1', 'Customer portal v1'],
+  },
+  data_model: {
+    needs_storage: false,
+    entities: [{ name: 'Lead', fields: ['name', 'email', 'phone', 'address', 'message', 'created_at'], source: 'intake' }],
+    recommended_storage: [],
+  },
+  brand: {
+    vibe: ['trustworthy', 'local', 'no-nonsense'],
+    inspiration_urls: [],
+    color_notes: 'Navy and white. Accent orange for CTAs.',
+    font_notes: 'Bold sans for headlines.',
+    logo_notes: 'Wordmark with palm icon.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: {
+    deadline: 'mvp_7_days',
+    budget_posture: 'free_tier_first',
+    must_use: ['Resend'],
+    must_avoid: [],
+  },
+  scaffold: {
+    base: 'next',
+    profile: 'lead-gen',
+    addons: ['email'],
+    template_paths: ['templates/base', 'templates/profiles/lead-gen'],
+  },
+  verification: {
+    acceptance_tests: [
+      'Visitor can submit the contact form',
+      'Owner receives the lead by email',
+      'JSON-LD LocalBusiness schema renders',
+    ],
+    visual_checks: ['Hero CTA above the fold on mobile', 'Service area map placeholder or text present'],
+    deploy_checks: ['Live URL returns 200', '/contact form posts to /api/contact'],
+  },
+};
+
+export const MARKETING_BRIEF = {
+  schema_version: SCHEMA_VERSION,
+  project: {
+    name: 'launch-soon',
+    display_name: 'Launch Soon',
+    summary: 'A single-page marketing site that announces a product, captures interest emails, and links to the GitHub repo.',
+    owner_or_client: 'GG',
+  },
+  classification: {
+    site_profile: 'marketing',
+    confidence: 0.85,
+    why: ['No data persistence beyond email list', 'Single primary CTA', 'No transaction flow'],
+    secondary_profiles: ['lead-gen'],
+  },
+  audience: { primary: 'founder', buyer: 'GG', end_users: ['Early-interest visitors'] },
+  business_model: { types: ['brand_awareness'], pricing_notes: 'Free; pre-launch' },
+  scope: {
+    must_have_sections: ['hero', 'features', 'pricing', 'email signup', 'footer'],
+    core_flows: ['newsletter'],
+    non_goals: ['Multi-page v1', 'Blog v1'],
+  },
+  data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+  brand: {
+    vibe: ['bold', 'clear', 'modern'],
+    inspiration_urls: [],
+    color_notes: 'High contrast.',
+    font_notes: 'System sans, large hero.',
+    logo_notes: 'Wordmark.',
+  },
+  inputs: { ingested: false, source_path: null, manifest_path: null },
+  constraints: { deadline: 'demo_today', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+  scaffold: {
+    base: 'next',
+    profile: 'marketing',
+    addons: [],
+    template_paths: ['templates/base', 'templates/profiles/marketing'],
+  },
+  verification: {
+    acceptance_tests: ['Visitor can submit email', 'Hero is readable on mobile'],
+    visual_checks: ['Hero readable at 420x900'],
+    deploy_checks: ['Live URL returns 200'],
+  },
+};
+
+// Alias export so that profile-name-derived lookups work consistently.
+export const SAAS_DASHBOARD_BRIEF = SAAS_BRIEF;
+
+export const SAMPLE_BRIEFS = {
+  marketing: MARKETING_BRIEF,
+  'lead-gen': LEAD_GEN_BRIEF,
+  booking: BOOKING_BRIEF,
+  blog: BLOG_BRIEF,
+  'saas-dashboard': SAAS_BRIEF,
+};

package/src/brief/schema.mjs

@@ -0,0 +1,176 @@
+// brief/schema.mjs: shape of brief.json + validation. Schema version 1.0.0.
+
+export const SCHEMA_VERSION = '1.0.0';
+
+export const PROFILES = ['marketing', 'lead-gen', 'booking', 'blog', 'storefront', 'saas-dashboard', 'directory', 'portfolio'];
+
+export const ADDONS = ['auth', 'payments', 'email', 'postgres', 'mdx', 'blob', 'analytics'];
+
+export const AUDIENCES = ['small_business', 'founder', 'agency', 'creator', 'community', 'other'];
+
+export const BUSINESS_MODELS = [
+  'lead_capture',
+  'booking_revenue',
+  'deposit',
+  'subscription',
+  'one_time_sale',
+  'content_traffic',
+  'dashboard',
+  'operations',
+  'brand_awareness',
+];
+
+export const CORE_FLOWS = [
+  'contact_form',
+  'booking',
+  'payment',
+  'auth',
+  'dashboard',
+  'content_crud',
+  'search_filter',
+  'newsletter',
+  'file_upload_download',
+  'other',
+];
+
+export const DATA_KINDS = [
+  'none',
+  'leads',
+  'bookings',
+  'products_orders',
+  'users_accounts',
+  'content',
+  'listings',
+  'files',
+  'unsure',
+];
+
+export const DEADLINES = ['demo_today', 'mvp_7_days', 'production_2_4_weeks', 'none'];
+
+export const BUDGET_POSTURES = ['free_tier_first', 'under_50_month', 'under_250_month', 'paid_ok'];
+
+const STRING = (v) => typeof v === 'string';
+const NONEMPTY = (v) => STRING(v) && v.trim().length > 0;
+const ARRAY_OF = (pred) => (v) => Array.isArray(v) && v.every(pred);
+
+export function validateBrief(brief) {
+  const errors = [];
+  if (!brief || typeof brief !== 'object') {
+    return { ok: false, errors: ['brief must be an object'] };
+  }
+
+  if (brief.schema_version !== SCHEMA_VERSION) {
+    errors.push(`schema_version must be ${SCHEMA_VERSION}, got ${brief.schema_version}`);
+  }
+
+  const p = brief.project;
+  if (!p || typeof p !== 'object') {
+    errors.push('project missing');
+  } else {
+    if (!NONEMPTY(p.name)) errors.push('project.name required');
+    if (!NONEMPTY(p.summary)) errors.push('project.summary required');
+    if (p.summary && (p.summary.length < 20 || p.summary.length > 240)) {
+      errors.push('project.summary must be 20-240 chars');
+    }
+  }
+
+  const c = brief.classification;
+  if (!c || typeof c !== 'object') {
+    errors.push('classification missing');
+  } else {
+    if (!PROFILES.includes(c.site_profile)) {
+      errors.push(`classification.site_profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (typeof c.confidence !== 'number' || c.confidence < 0 || c.confidence > 1) {
+      errors.push('classification.confidence must be number 0-1');
+    }
+    if (!ARRAY_OF(NONEMPTY)(c.why)) {
+      errors.push('classification.why must be array of non-empty strings');
+    }
+  }
+
+  const a = brief.audience;
+  if (!a || typeof a !== 'object') {
+    errors.push('audience missing');
+  } else {
+    if (!AUDIENCES.includes(a.primary)) {
+      errors.push(`audience.primary must be one of: ${AUDIENCES.join(', ')}`);
+    }
+  }
+
+  const bm = brief.business_model;
+  if (!bm || typeof bm !== 'object') {
+    errors.push('business_model missing');
+  } else if (!Array.isArray(bm.types) || !bm.types.every((t) => BUSINESS_MODELS.includes(t))) {
+    errors.push(`business_model.types must be array of values from: ${BUSINESS_MODELS.join(', ')}`);
+  }
+
+  const scope = brief.scope;
+  if (!scope || typeof scope !== 'object') {
+    errors.push('scope missing');
+  } else {
+    if (!ARRAY_OF(NONEMPTY)(scope.must_have_sections) || scope.must_have_sections.length === 0) {
+      errors.push('scope.must_have_sections must be non-empty array');
+    }
+    if (!ARRAY_OF(NONEMPTY)(scope.core_flows) || scope.core_flows.length === 0) {
+      errors.push('scope.core_flows must be non-empty array');
+    }
+  }
+
+  const dm = brief.data_model;
+  if (!dm || typeof dm !== 'object') {
+    errors.push('data_model missing');
+  } else if (typeof dm.needs_storage !== 'boolean') {
+    errors.push('data_model.needs_storage must be boolean');
+  }
+
+  const brand = brief.brand;
+  if (!brand || typeof brand !== 'object') {
+    errors.push('brand missing');
+  } else if (!ARRAY_OF(NONEMPTY)(brand.vibe)) {
+    errors.push('brand.vibe must be array of strings');
+  }
+
+  const constraints = brief.constraints;
+  if (!constraints || typeof constraints !== 'object') {
+    errors.push('constraints missing');
+  } else {
+    if (!DEADLINES.includes(constraints.deadline)) {
+      errors.push(`constraints.deadline must be one of: ${DEADLINES.join(', ')}`);
+    }
+    if (!BUDGET_POSTURES.includes(constraints.budget_posture)) {
+      errors.push(`constraints.budget_posture must be one of: ${BUDGET_POSTURES.join(', ')}`);
+    }
+  }
+
+  const sc = brief.scaffold;
+  if (!sc || typeof sc !== 'object') {
+    errors.push('scaffold missing');
+  } else {
+    if (!PROFILES.includes(sc.profile)) {
+      errors.push(`scaffold.profile must be one of: ${PROFILES.join(', ')}`);
+    }
+    if (!Array.isArray(sc.addons) || !sc.addons.every((a) => ADDONS.includes(a))) {
+      errors.push(`scaffold.addons must be array of values from: ${ADDONS.join(', ')}`);
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function emptyBrief() {
+  return {
+    schema_version: SCHEMA_VERSION,
+    project: { name: '', display_name: '', summary: '', owner_or_client: '' },
+    classification: { site_profile: 'marketing', confidence: 0, why: [], secondary_profiles: [] },
+    audience: { primary: 'small_business', buyer: '', end_users: [] },
+    business_model: { types: [], pricing_notes: '' },
+    scope: { must_have_sections: [], core_flows: [], non_goals: [] },
+    data_model: { needs_storage: false, entities: [], recommended_storage: [] },
+    brand: { vibe: [], inspiration_urls: [], color_notes: '', font_notes: '', logo_notes: '' },
+    inputs: { ingested: false, source_path: null, manifest_path: null },
+    constraints: { deadline: 'mvp_7_days', budget_posture: 'free_tier_first', must_use: [], must_avoid: [] },
+    scaffold: { base: 'next', profile: 'marketing', addons: [], template_paths: ['templates/base'] },
+    verification: { acceptance_tests: [], visual_checks: [], deploy_checks: [] },
+  };
+}

package/src/mvp-flow.mjs

@@ -17,6 +17,8 @@ import { renderSummary } from './summary.mjs';
 import { substitute, buildTokenMap } from './substitute.mjs';
 import { REGISTRY, OPTIONAL_REGISTRY } from './templates.mjs';
 import { run as exec, isDryRun } from './exec.mjs';
+import { loadBrief, writeBriefFiles } from './brief/index.mjs';
+import { applyProfileOverlay } from './brief/profile-router.mjs';
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
@@ -33,7 +35,23 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
 
   preflightOrExit();
 
-  const answers = await runProjectPrompts({ flags });
+  let brief = null;
+  if (flags.brief) {
+    brief = await loadBrief(flags.brief);
+    process.stdout.write(`Loaded brief from ${resolve(flags.brief)}\n`);
+    process.stdout.write(`  Profile: ${brief.classification.site_profile} (confidence ${brief.classification.confidence})\n`);
+    process.stdout.write(`  Add-ons: ${(brief.scaffold.addons || []).join(', ') || '(none)'}\n`);
+  }
+
+  const promptFlags = brief
+    ? {
+        ...flags,
+        name: flags.name || brief.project.name,
+        profile: flags.profile || 'goodshin',
+      }
+    : flags;
+
+  const answers = await runProjectPrompts({ flags: promptFlags });
   if (!answers || answers.cancelled) {
     process.stdout.write('Cancelled.\n');
     const err = new Error('user cancelled prompts');
@@ -41,6 +59,14 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
     throw err;
   }
 
+  if (brief) {
+    answers.displayName = brief.project.display_name || answers.displayName;
+    answers.description = brief.project.summary || answers.description;
+    if (brief.inputs?.source_path && !answers.ingestPath) {
+      answers.ingestPath = brief.inputs.source_path;
+    }
+  }
+
   printAnswersSummary(answers);
   if (!flags.yes) {
     const proceed = await confirmProceed();
@@ -76,6 +102,22 @@ export async function runMvp({ flags = {}, cwd = process.cwd() } = {}) {
   });
 
   await overlayKit({ targetDir, tokens });
+  if (brief) {
+    await writeBriefFiles({ targetDir, brief, force: true });
+    const overlay = await applyProfileOverlay({
+      targetDir,
+      profile: brief.scaffold.profile,
+      tokens,
+      dryRun: isDryRun(),
+    });
+    if (overlay.applied) {
+      process.stdout.write(`[brief] applied profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else if (isDryRun()) {
+      process.stdout.write(`[brief] would apply profile overlay '${brief.scaffold.profile}': ${overlay.files.length} file(s)\n`);
+    } else {
+      process.stdout.write(`[brief] profile overlay '${brief.scaffold.profile}': ${overlay.reason}\n`);
+    }
+  }
   await writeProjectEnvFiles({ targetDir, collected: creds.collected });
   await ensureGitignoreEnv({ targetDir });
 

package/src/templates.mjs

@@ -28,6 +28,9 @@ export const REGISTRY = [
   { src: '.claude/commands/add-storage.md',   dest: '.claude/commands/add-storage.md' },
   { src: '.claude/commands/generate-image-prompt.md', dest: '.claude/commands/generate-image-prompt.md' },
   { src: '.claude/commands/generate-image.md', dest: '.claude/commands/generate-image.md' },
+  { src: '.claude/commands/resume.md',         dest: '.claude/commands/resume.md' },
+  { src: '.claude/commands/handoff-doctor.md', dest: '.claude/commands/handoff-doctor.md' },
+  { src: '.claude/commands/break-into-stories.md', dest: '.claude/commands/break-into-stories.md' },
   { src: 'CLAUDE.md',                          dest: 'CLAUDE.md' },
   { src: 'AGENTS.md',                          dest: 'AGENTS.md' },
   { src: 'START_HERE.md',                      dest: 'START_HERE.md' },
@@ -39,6 +42,7 @@ export const REGISTRY = [
   { src: 'tasks/.gitkeep',                     dest: 'tasks/.gitkeep' },
   { src: 'inputs/README.md',                   dest: 'inputs/README.md' },
   { src: 'scripts/screenshot.sh',              dest: 'scripts/screenshot.sh', executable: true },
+  { src: 'scripts/verify.sh',                  dest: 'scripts/verify.sh', executable: true },
 ];
 
 export const OPTIONAL_REGISTRY = [

package/templates/.claude/commands/break-into-stories.md

@@ -0,0 +1,101 @@
+---
+description: Break a PRD into vertical stories (each story is independently shippable) before generating granular tasks. Sits between /create-prd and /generate-tasks. Borrowed pattern from BMAD; kept light.
+---
+
+# /break-into-stories
+
+A PRD is a description. Tasks are atoms. **Stories are the missing middle layer.** A story is a small vertical slice that can be shipped on its own and feels meaningful to the operator on a deployed URL.
+
+Use this command after `/create-prd` and before `/generate-tasks`. It produces `tasks/stories-<feature>.md` with 3-7 stories.
+
+## Step 1: locate the PRD
+
+```bash
+ls tasks/prd-*.md
+```
+
+If the operator named a feature (e.g. `/break-into-stories user-auth`), use `tasks/prd-user-auth.md`.
+
+If no name: ask the operator which PRD.
+
+## Step 2: read the PRD + the brief
+
+```bash
+cat tasks/prd-<feature>.md
+[ -f docs/brief.md ] && head -80 docs/brief.md
+```
+
+## Step 3: derive stories
+
+For each story, fill this shape:
+
+```markdown
+## Story <N>: <one-line goal>
+
+**Why this is a story:** <one sentence on why this is a meaningful vertical slice>
+
+**User journey:** <2-3 sentences describing what the operator or end user does>
+
+**Acceptance:**
+- <observable behavior 1>
+- <observable behavior 2>
+
+**Deployable check:** <one sentence on what you can show on the live URL after this story ships>
+
+**Out of scope for this story:** <bullets of things explicitly NOT in this story; they belong to other stories>
+```
+
+### Rules for cutting stories
+
+1. **Vertical, not horizontal.** A story crosses UI + API + data if needed. It does NOT say "build the API for X" as a story; that is a task.
+2. **Shippable.** Each story can be merged + deployed and produces an observable change on the live URL.
+3. **Small.** 30 minutes to 2 hours of agent work each. If a story feels bigger, split it.
+4. **Independent where possible.** Story 2 should not require Story 1's completion unless there is a hard dependency (then state it).
+5. **Acceptance is observable.** "Visitor can click X and see Y" not "The reducer handles X."
+6. **3 to 7 stories per PRD.** More than 7 means the PRD is too big; less than 3 means you do not need stories, just tasks.
+
+## Step 4: write `tasks/stories-<feature>.md`
+
+```markdown
+# Stories: <feature>
+
+> Source PRD: `tasks/prd-<feature>.md`
+> Generated by `/break-into-stories` on <YYYY-MM-DD>.
+> Each story is independently shippable.
+
+## Story order (recommended)
+
+1. Story 1 — <goal>
+2. Story 2 — <goal>
+3. ...
+
+## Stories
+
+<the N stories from Step 3>
+
+## Dependencies
+
+<if any: "Story 3 depends on Story 1 because ..." else "All stories are independent.">
+
+## Next step
+
+For the first story, run `/generate-tasks` referencing `Story 1` to break it into atoms. Implement, deploy, verify, then move to the next story.
+```
+
+## Step 5: report
+
+```
+Stories generated: tasks/stories-<feature>.md (N stories)
+
+Recommended first story: Story 1 — <goal>
+  Estimated agent work: <30 min | 1 hr | 2 hr>
+
+Next: /generate-tasks for Story 1, then implement.
+```
+
+## Hard rules
+
+- Stories never cross PRDs. One PRD → one stories file.
+- Each story's acceptance criteria must be observable from the live URL after deploy, or via a `curl` probe (for backend stories).
+- If a story has no deployable check, it is not a story; it is a task. Roll it into another story.
+- Mark dependencies explicitly. Do not pretend stories are independent when one needs another's API.