@oaklandzoo/ostup 0.2.0 → 0.4.0

package/README.md

@@ -102,6 +102,29 @@ The tool will ask you a series of questions. Answer each one. When the
 tool finishes, you will see a live deploy URL. Open it in your browser
 to confirm the site is up.
 
+## Use (operator brief mode, recommended for real projects)
+
+If you want the agent to start with a richer context (business goal,
+audience, business model, day-one flows, brand, constraints), run the
+10-question intake first:
+
+```
+ostup brief
+```
+
+That writes `docs/brief.md`, `docs/brief.json`, and `tasks/prd-initial-build.md`
+in the current folder. Then scaffold the project with the brief:
+
+```
+ostup init --brief ./docs/brief.json
+```
+
+The tool classifies one of 8 site profiles (marketing, lead-gen,
+booking, blog, storefront, saas-dashboard, directory, portfolio),
+picks the right add-ons (auth, payments, email, postgres, mdx, blob,
+analytics), and applies a profile-specific overlay so the agent has a
+clear day-one plan.
+
 ## Questions the tool will ask
 
 | Question | What to answer |

package/bin/cli.mjs

@@ -10,7 +10,7 @@ loadDotEnv();
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
-const SUBCOMMANDS = new Set(['init', 'update']);
+const SUBCOMMANDS = new Set(['init', 'update', 'brief']);
 
 async function readPkg() {
   const raw = await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8');
@@ -37,6 +37,10 @@ function parseArgs(argv) {
     else if (a.startsWith('--config=')) flags.config = a.slice('--config='.length);
     else if (a === '--ingest') flags.ingest = argv[++i];
     else if (a.startsWith('--ingest=')) flags.ingest = a.slice('--ingest='.length);
+    else if (a === '--brief') flags.brief = argv[++i];
+    else if (a.startsWith('--brief=')) flags.brief = a.slice('--brief='.length);
+    else if (a === '--target') flags.target = argv[++i];
+    else if (a.startsWith('--target=')) flags.target = a.slice('--target='.length);
     else if (a.startsWith('-')) {
       process.stderr.write(`unknown flag: ${a}\n`);
       process.exit(1);
@@ -57,6 +61,7 @@ function printHelp() {
       '',
       'Commands:',
       '  init                Scaffold a new project (interactive or with --yes).',
+      '  brief               Run the 10-question operator intake; write docs/brief.md + brief.json.',
       '  update              Refresh bundled templates from the pinned source.',
       '',
       'Flags for `ostup init`:',
@@ -66,9 +71,16 @@ function printHelp() {
       '  --profile <name>    Skip the profile prompt (goodshin or default).',
       '  --name <kebab>      Skip the projectName prompt.',
       '  --ingest <path>     Copy operator materials from <path> into inputs/.',
+      '  --brief <path>      Load a brief.json from <path> and write brief files + apply profile overlay.',
       '  --kit-only          Drop the markdown kit into a target dir, no GitHub or Vercel.',
       '  --config <path>     Read .ostup-config.yml from this path (kit-only mode).',
       '',
+      'Flags for `ostup brief`:',
+      '  --brief <path>      Load brief.json from <path> instead of running the intake.',
+      '  --target <dir>      Write brief files into <dir> (default: current working dir).',
+      '  --force             Overwrite existing docs/brief.md, docs/brief.json, tasks/prd-initial-build.md.',
+      '  --dry-run           Print what would be written without writing.',
+      '',
       'Global flags:',
       '  --version, -v       Print version and exit.',
       '  --help, -h          Print this help and exit.',
@@ -118,6 +130,18 @@ if (subcommand === 'update') {
   }
 }
 
+if (subcommand === 'brief') {
+  const { runBrief } = await import('../src/brief/index.mjs');
+  try {
+    await runBrief({ flags });
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    const userErrors = new Set(['NO_TTY', 'USER_ABORT', 'BRIEF_NOT_FOUND', 'BRIEF_INVALID', 'BRIEF_EXISTS']);
+    process.exit(userErrors.has(err.code) ? 1 : 2);
+  }
+}
+
 // subcommand === 'init'
 if (flags.kitOnly) {
   const { scaffold } = await import('../src/scaffold.mjs');
@@ -145,6 +169,8 @@ try {
     'NO_GH_CREDS',
     'NO_VERCEL_CREDS',
     'INGEST_PATH_NOT_FOUND',
+    'BRIEF_NOT_FOUND',
+    'BRIEF_INVALID',
   ]);
   process.exit(userErrors.has(err.code) ? 1 : 2);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oaklandzoo/ostup",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Scaffolds a new repo with the Ostup Agent Kit pre-installed: slash commands, doc templates, and a clean working state.",
   "type": "module",
   "bin": {

package/src/brief/classify.mjs

@@ -0,0 +1,218 @@
+// brief/classify.mjs: deterministic profile classifier. AI call only when user explicitly asks.
+
+import { PROFILES, ADDONS } from './schema.mjs';
+
+const SIGNAL_PATTERNS = {
+  booking: [
+    /booking/i, /appointment/i, /calendar/i, /availability/i, /deposit/i,
+    /reservation/i, /lodge/i, /salon/i, /stylist/i, /barber/i, /clinic/i,
+  ],
+  'saas-dashboard': [
+    /subscription/i, /dashboard/i, /\blogin\b/i, /\bteam\b/i, /workspace/i,
+    /billing/i, /multi[- ]?tenant/i, /admin shell/i, /metering/i,
+  ],
+  storefront: [
+    /\bproduct\b/i, /\bcart\b/i, /checkout/i, /\bstore\b/i, /\bsku\b/i,
+    /inventory/i, /ecommerce/i, /\bshop\b/i,
+  ],
+  blog: [
+    /\bblog\b/i, /\barticles?\b/i, /newsletter/i, /\bseo\b/i, /\bcontent engine\b/i,
+    /\brss\b/i, /\bmdx\b/i, /\bessays?\b/i, /\bposts?\b/i,
+  ],
+  directory: [
+    /directory/i, /listings?/i, /\bmap\b/i, /search.*filter/i, /\bprofiles?\b/i,
+    /\bcategories?\b/i,
+  ],
+  'lead-gen': [
+    /\bservices?\b/i, /\bquote\b/i, /estimate/i, /service area/i, /\bcall\b/i,
+    /\bcontact\b/i, /lead capture/i, /\bplumber\b/i, /\broofer\b/i, /\belectrician\b/i,
+    /\blocksmith\b/i, /\blandscap/i, /\bcleaning\b/i,
+  ],
+  portfolio: [
+    /portfolio/i, /case studies/i, /\bwork\b/i, /\bclients\b/i, /\bgallery\b/i,
+    /freelance/i, /agency/i,
+  ],
+};
+
+const ADDON_RULES = {
+  payments: (brief) => {
+    const types = brief.business_model?.types || [];
+    return types.some((t) => ['booking_revenue', 'deposit', 'subscription', 'one_time_sale'].includes(t))
+      || (brief.scope?.core_flows || []).includes('payment');
+  },
+  auth: (brief) => {
+    const types = brief.business_model?.types || [];
+    if (types.includes('subscription') || types.includes('dashboard') || types.includes('operations')) return true;
+    const data = brief.data_model?.entities || [];
+    if (data.some((e) => e.name?.toLowerCase().includes('user'))) return true;
+    return (brief.scope?.core_flows || []).includes('auth') || (brief.scope?.core_flows || []).includes('dashboard');
+  },
+  email: (brief) => {
+    const types = brief.business_model?.types || [];
+    if (types.includes('lead_capture') || types.includes('booking_revenue')) return true;
+    const flows = brief.scope?.core_flows || [];
+    return flows.includes('contact_form') || flows.includes('booking') || flows.includes('newsletter');
+  },
+  postgres: (brief) => {
+    if (brief.data_model?.needs_storage) return true;
+    const recs = brief.data_model?.recommended_storage || [];
+    return recs.includes('postgres');
+  },
+  mdx: (brief) => {
+    const types = brief.business_model?.types || [];
+    if (types.includes('content_traffic')) return true;
+    return (brief.scope?.core_flows || []).includes('content_crud');
+  },
+  blob: (brief) => {
+    const recs = brief.data_model?.recommended_storage || [];
+    if (recs.includes('blob')) return true;
+    return (brief.scope?.core_flows || []).includes('file_upload_download');
+  },
+  analytics: () => false, // Pro-only; never auto-included
+};
+
+const PROFILE_SCORES_MIN_DIFF = 2; // strongest profile must beat runner-up by this much
+
+function tokenize(brief) {
+  const text = [
+    brief.project?.summary || '',
+    brief.project?.display_name || '',
+    (brief.scope?.must_have_sections || []).join(' '),
+    (brief.scope?.core_flows || []).join(' '),
+    brief.business_model?.pricing_notes || '',
+  ].join(' ');
+  return text;
+}
+
+export function deterministicScores(brief) {
+  const text = tokenize(brief);
+  const scores = {};
+  for (const profile of PROFILES) {
+    const patterns = SIGNAL_PATTERNS[profile] || [];
+    scores[profile] = 0;
+    for (const re of patterns) {
+      if (re.test(text)) scores[profile] += 1;
+    }
+  }
+
+  // Boost by business-model signals.
+  const types = brief.business_model?.types || [];
+  if (types.includes('subscription')) {
+    scores['saas-dashboard'] += 3;
+  }
+  if (types.includes('dashboard')) {
+    scores['saas-dashboard'] += 2;
+  }
+  if (types.includes('booking_revenue') || types.includes('deposit')) {
+    scores['booking'] += 3;
+  }
+  if (types.includes('one_time_sale')) {
+    scores['storefront'] += 3;
+  }
+  if (types.includes('content_traffic')) {
+    scores['blog'] += 2;
+  }
+  if (types.includes('lead_capture') && !types.some((t) => ['subscription', 'booking_revenue', 'deposit', 'one_time_sale'].includes(t))) {
+    scores['lead-gen'] += 2;
+  }
+  if (types.length === 1 && types[0] === 'brand_awareness') {
+    scores['marketing'] += 2;
+  }
+
+  // Core-flow boosts.
+  const flows = brief.scope?.core_flows || [];
+  if (flows.includes('booking')) scores['booking'] += 2;
+  if (flows.includes('payment') && (flows.includes('auth') || flows.includes('dashboard'))) scores['saas-dashboard'] += 2;
+  if (flows.includes('search_filter')) scores['directory'] += 2;
+  if (flows.includes('content_crud')) scores['blog'] += 2;
+  if (flows.includes('contact_form') && !flows.includes('payment') && !flows.includes('booking')) scores['lead-gen'] += 1;
+
+  return scores;
+}
+
+export function classify(brief, { explicitProfile = null } = {}) {
+  // Operator picked explicitly. Honor unless empty.
+  if (explicitProfile && PROFILES.includes(explicitProfile)) {
+    const scores = deterministicScores(brief);
+    return {
+      site_profile: explicitProfile,
+      confidence: 1.0,
+      why: [`Operator explicitly selected '${explicitProfile}'`],
+      secondary_profiles: rankRest(scores, explicitProfile),
+      addons: resolveAddons(brief),
+      scores,
+    };
+  }
+
+  const scores = deterministicScores(brief);
+  const ranked = Object.entries(scores).sort(([, a], [, b]) => b - a);
+  const [topProfile, topScore] = ranked[0];
+  const [, secondScore] = ranked[1] || ['marketing', 0];
+
+  let chosen = topProfile;
+  let confidence;
+  if (topScore === 0) {
+    chosen = 'marketing';
+    confidence = 0.5; // fallback default
+  } else if (topScore - secondScore >= PROFILE_SCORES_MIN_DIFF) {
+    confidence = Math.min(0.95, 0.7 + (topScore - secondScore) * 0.05);
+  } else {
+    confidence = Math.min(0.7, 0.55 + topScore * 0.02);
+  }
+
+  return {
+    site_profile: chosen,
+    confidence: round2(confidence),
+    why: explainChoice(brief, scores, chosen),
+    secondary_profiles: rankRest(scores, chosen),
+    addons: resolveAddons(brief),
+    scores,
+  };
+}
+
+function explainChoice(brief, scores, chosen) {
+  const reasons = [];
+  const types = brief.business_model?.types || [];
+  if (chosen === 'booking' && (types.includes('booking_revenue') || types.includes('deposit'))) {
+    reasons.push('Booking or deposit is a primary revenue model');
+  }
+  if (chosen === 'saas-dashboard' && types.includes('subscription')) {
+    reasons.push('Subscription model implies SaaS dashboard scaffold');
+  }
+  if (chosen === 'storefront' && types.includes('one_time_sale')) {
+    reasons.push('Direct product sale requires storefront');
+  }
+  if (chosen === 'blog' && types.includes('content_traffic')) {
+    reasons.push('Content traffic is the primary value model');
+  }
+  if (chosen === 'lead-gen' && types.includes('lead_capture')) {
+    reasons.push('Lead capture is the primary value model');
+  }
+  if (scores[chosen] > 0 && reasons.length === 0) {
+    reasons.push(`Strongest signal match for ${chosen} (score ${scores[chosen]})`);
+  }
+  if (reasons.length === 0) {
+    reasons.push('No strong signals; defaulted to marketing');
+  }
+  return reasons;
+}
+
+function rankRest(scores, chosen) {
+  return Object.entries(scores)
+    .filter(([p, s]) => p !== chosen && s > 0)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 2)
+    .map(([p]) => p);
+}
+
+export function resolveAddons(brief) {
+  const addons = [];
+  for (const addon of ADDONS) {
+    if (ADDON_RULES[addon] && ADDON_RULES[addon](brief)) addons.push(addon);
+  }
+  return addons;
+}
+
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}

package/src/brief/index.mjs

@@ -0,0 +1,126 @@
+// brief/index.mjs: entry point for ostup brief subcommand + runtime helpers.
+
+import { existsSync } from 'node:fs';
+import { writeFile, readFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve, join } from 'node:path';
+import { renderBrief, renderInitialPrdSeed } from './render-brief.mjs';
+import { validateBrief, SCHEMA_VERSION } from './schema.mjs';
+import { runIntake } from './questions.mjs';
+import { classify, resolveAddons } from './classify.mjs';
+
+/**
+ * Load a brief from a JSON path, validate it, return the parsed object.
+ * Throws BRIEF_INVALID if validation fails.
+ */
+export async function loadBrief(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) {
+    const err = new Error(`brief file not found: ${abs}`);
+    err.code = 'BRIEF_NOT_FOUND';
+    throw err;
+  }
+  const raw = await readFile(abs, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    const err = new Error(`brief file is not valid JSON: ${abs}\n${e.message}`);
+    err.code = 'BRIEF_INVALID';
+    throw err;
+  }
+  const result = validateBrief(parsed);
+  if (!result.ok) {
+    const err = new Error(`brief at ${abs} failed validation:\n  ${result.errors.join('\n  ')}`);
+    err.code = 'BRIEF_INVALID';
+    throw err;
+  }
+  return parsed;
+}
+
+/**
+ * Write brief.md + brief.json to <targetDir>/docs/.
+ * Also writes tasks/prd-initial-build.md (PRD seed).
+ *
+ * If force is false and either file exists, throws BRIEF_EXISTS.
+ */
+export async function writeBriefFiles({ targetDir, brief, force = false } = {}) {
+  const docsDir = join(targetDir, 'docs');
+  const tasksDir = join(targetDir, 'tasks');
+  const briefMdPath = join(docsDir, 'brief.md');
+  const briefJsonPath = join(docsDir, 'brief.json');
+  const prdSeedPath = join(tasksDir, 'prd-initial-build.md');
+
+  if (!force) {
+    for (const p of [briefMdPath, briefJsonPath, prdSeedPath]) {
+      if (existsSync(p)) {
+        const err = new Error(`refusing to overwrite ${p} (pass --force to overwrite)`);
+        err.code = 'BRIEF_EXISTS';
+        throw err;
+      }
+    }
+  }
+
+  await mkdir(docsDir, { recursive: true });
+  await mkdir(tasksDir, { recursive: true });
+  await writeFile(briefMdPath, renderBrief(brief), 'utf8');
+  await writeFile(briefJsonPath, JSON.stringify(brief, null, 2) + '\n', 'utf8');
+  await writeFile(prdSeedPath, renderInitialPrdSeed(brief), 'utf8');
+
+  return { briefMdPath, briefJsonPath, prdSeedPath };
+}
+
+/**
+ * `ostup brief` subcommand entry point.
+ *
+ * Modes:
+ *   - interactive (default): runs the 10-question intake
+ *   - with --brief <path>: loads from path, re-renders brief.md + PRD seed
+ *
+ * Always writes brief files into <cwd>/docs/ (or --target). Does NOT scaffold,
+ * does NOT create GitHub repos, does NOT deploy. Pure intake + render.
+ */
+export async function runBrief({ flags = {}, cwd = process.cwd() } = {}) {
+  const targetDir = flags.target ? resolve(flags.target) : cwd;
+
+  let brief;
+  if (flags.brief) {
+    brief = await loadBrief(flags.brief);
+    process.stdout.write(`Loaded brief from ${resolve(flags.brief)}\n`);
+  } else {
+    if (!process.stdin.isTTY && !flags.yes) {
+      const err = new Error(
+        'no TTY detected. Interactive intake cannot run.\nPass --brief <path> to load from a JSON file.'
+      );
+      err.code = 'NO_TTY';
+      throw err;
+    }
+    const result = await runIntake({ defaults: flags.defaults || {} });
+    if (result.cancelled) {
+      process.stdout.write('Cancelled.\n');
+      const err = new Error('user cancelled intake');
+      err.code = 'USER_ABORT';
+      throw err;
+    }
+    brief = result.brief;
+  }
+
+  if (flags.dryRun) {
+    process.stdout.write('\n[brief] would write:\n');
+    process.stdout.write(`  ${join(targetDir, 'docs/brief.md')}\n`);
+    process.stdout.write(`  ${join(targetDir, 'docs/brief.json')}\n`);
+    process.stdout.write(`  ${join(targetDir, 'tasks/prd-initial-build.md')}\n`);
+    process.stdout.write(`\n[brief] classification: ${brief.classification.site_profile} (confidence ${brief.classification.confidence})\n`);
+    process.stdout.write(`[brief] add-ons: ${(brief.scaffold.addons || []).join(', ') || '(none)'}\n`);
+    return { brief, paths: null, dryRun: true };
+  }
+
+  const paths = await writeBriefFiles({ targetDir, brief, force: flags.force });
+  process.stdout.write(`\nBrief written:\n`);
+  process.stdout.write(`  ${paths.briefMdPath}\n`);
+  process.stdout.write(`  ${paths.briefJsonPath}\n`);
+  process.stdout.write(`  ${paths.prdSeedPath}\n`);
+  process.stdout.write(`\nProfile: ${brief.classification.site_profile} (confidence ${brief.classification.confidence})\n`);
+  process.stdout.write(`Add-ons: ${(brief.scaffold.addons || []).join(', ') || '(none)'}\n`);
+
+  return { brief, paths };
+}

package/src/brief/profile-router.mjs

@@ -0,0 +1,89 @@
+// brief/profile-router.mjs: decide which templates to overlay based on the brief's profile + add-ons.
+
+import { resolve, dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { substitute } from '../substitute.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const TEMPLATES_ROOT = resolve(PKG_ROOT, 'templates');
+
+/**
+ * Returns the absolute path to the profile's template overlay folder.
+ * Returns null if the profile has no overlay (yet).
+ */
+export function profileTemplatePath(profile) {
+  const p = resolve(TEMPLATES_ROOT, 'profiles', profile);
+  return existsSync(p) ? p : null;
+}
+
+/**
+ * Recursively list every file in a directory, returning relative paths.
+ */
+async function listFiles(dir, base = dir, out = []) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await listFiles(full, base, out);
+    } else if (entry.isFile()) {
+      out.push(full.slice(base.length + 1));
+    }
+  }
+  return out;
+}
+
+/**
+ * Apply a profile overlay to the target directory.
+ * - Reads every file in templates/profiles/<profile>/
+ * - Substitutes tokens
+ * - Writes to <targetDir>/<relative-path>
+ *
+ * Skip rules:
+ *   - .DS_Store
+ *   - any path containing /node_modules/
+ *
+ * Files with name suffix `.additions` are appended to the existing file at the
+ * destination (used for .env.example.additions). All others are written.
+ */
+export async function applyProfileOverlay({ targetDir, profile, tokens, dryRun = false } = {}) {
+  const overlayPath = profileTemplatePath(profile);
+  if (!overlayPath) {
+    return { applied: false, reason: `no overlay folder for profile '${profile}'`, files: [] };
+  }
+
+  const files = await listFiles(overlayPath);
+  const filtered = files.filter((f) => !f.endsWith('.DS_Store') && !f.includes('/node_modules/'));
+
+  const actions = [];
+  for (const rel of filtered) {
+    const src = join(overlayPath, rel);
+    const isAddition = rel.endsWith('.additions');
+    const dest = isAddition
+      ? join(targetDir, rel.replace(/\.additions$/, ''))
+      : join(targetDir, rel);
+
+    actions.push({ rel, src, dest, isAddition });
+  }
+
+  if (dryRun) {
+    return { applied: false, reason: 'dry-run', files: actions.map((a) => a.rel) };
+  }
+
+  for (const a of actions) {
+    const raw = await readFile(a.src, 'utf8');
+    const out = substitute(raw, tokens);
+    await mkdir(dirname(a.dest), { recursive: true });
+    if (a.isAddition && existsSync(a.dest)) {
+      const existing = await readFile(a.dest, 'utf8');
+      // Append with a separator if not already present
+      const sep = existing.endsWith('\n') ? '' : '\n';
+      await writeFile(a.dest, existing + sep + '\n# --- added by ostup profile overlay ---\n' + out, 'utf8');
+    } else {
+      await writeFile(a.dest, out, 'utf8');
+    }
+  }
+
+  return { applied: true, reason: 'overlay applied', files: actions.map((a) => a.rel) };
+}