claude-code-ultimate-optimal-framework 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# claude-os
+
+Scaffold a Claude Code workspace with routing, memory, and self-updating architecture — in one command.
+
+## What It Creates
+
+A 3-layer routing system that tells Claude exactly what to load (and what to skip) for every task. Keeps token usage low, memory high, and context relevant.
+
+```
+your-workspace/
+├── CLAUDE.md                 ← Master map (always loaded)
+├── CONTEXT.md                ← Task router
+├── PROJECT-REGISTRY.md       ← Project index
+├── company/                  ← Brand voice, products, SOPs
+├── departments/              ← One workspace per department
+├── products/                 ← One workspace per product
+├── projects/                 ← Time-bounded initiatives (auto-created)
+└── _system/                  ← Infrastructure docs + project templates
+```
+
+## Usage
+
+```bash
+npx claude-os init
+```
+
+The CLI will ask you about:
+- Company name, description, tagline, website, industry
+- Which departments exist
+- Products and services
+- VPS or local server infrastructure (optional)
+- Where to create the workspace
+
+Then it generates the entire folder structure with customized files.
+
+## How the System Works
+
+### 3-Layer Routing
+
+| Layer | File | Purpose | Size |
+|-------|------|---------|------|
+| 1 | `CLAUDE.md` | Always loaded — the map | ≤200 lines |
+| 2 | `CONTEXT.md` | Task router — where to go | 30-50 lines |
+| 3 | `[workspace]/CONTEXT.md` | Scoped instructions per task | 25-80 lines |
+
+### Self-Updating
+
+Paste or speak unstructured thoughts and Claude routes them to the right files automatically:
+
+- *"Our brand voice is warm but direct..."* → updates `company/voice-brand.md`
+- *"We're launching a new service called X..."* → updates `company/products.md`
+- *"We need a new onboarding process..."* → creates `company/sops/sop-onboarding.md`
+
+### Auto-Scaffolding
+
+Say `"New project: [describe what you need]"` and Claude:
+1. Infers the project type (biz-initiative / va-workflow / product-build)
+2. Creates the folder structure from the right template
+3. Registers it in `PROJECT-REGISTRY.md` and `CLAUDE.md`
+
+### Token Management
+
+Every workspace has a **"Skip These"** column — telling Claude what NOT to load. This prevents context bloat on large workspaces.
+
+## Local Development
+
+```bash
+git clone <this repo>
+cd claude-os
+npm install
+node bin/claude-os.js
+```
+
+## Publishing
+
+```bash
+npm publish
+```
+
+## Requirements
+
+- Node.js 18+
+- Claude Code (claude.ai/code)

package/bin/claude-os.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../src/init.js';
+
+run();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "claude-code-ultimate-optimal-framework",
+  "version": "1.0.0",
+  "description": "Scaffold a Claude Code workspace with routing, memory, and self-updating architecture",
+  "type": "module",
+  "bin": {
+    "claude-code-ultimate-optimal-framework": "./bin/claude-os.js"
+  },
+  "scripts": {
+    "dev": "node bin/claude-os.js"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.0",
+    "chalk": "^5.4.1",
+    "fs-extra": "^11.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "workspace",
+    "scaffold",
+    "anthropic"
+  ],
+  "author": "ProSulum",
+  "license": "MIT"
+}

package/src/init.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { gatherConfig } from './prompts.js';
+import { scaffold } from './scaffold.js';
+
+export async function run() {
+  try {
+    const config = await gatherConfig();
+
+    console.log(chalk.bold.cyan('\n  Building workspace...\n'));
+
+    const root = await scaffold(config);
+
+    const deptList = config.departments.map(d => `    • ${d}`).join('\n');
+    const productList = config.products.length
+      ? config.products.map(p => `    • ${p.name} → products/${p.slug}/`).join('\n')
+      : '    (none)';
+
+    console.log(chalk.bold.green('  ✓ Workspace created!\n'));
+    console.log(chalk.white(`  Location: ${chalk.cyan(root)}\n`));
+
+    console.log(chalk.bold('  What was created:\n'));
+    console.log(`  ${chalk.cyan('CLAUDE.md')}          — master map (always loaded)`);
+    console.log(`  ${chalk.cyan('CONTEXT.md')}         — task router`);
+    console.log(`  ${chalk.cyan('PROJECT-REGISTRY.md')} — project index`);
+    console.log(`  ${chalk.cyan('company/')}           — brand, products, SOPs`);
+    console.log(`  ${chalk.cyan('departments/')}       — ${config.departments.length} department workspace(s)`);
+    if (deptList) console.log(deptList);
+    console.log(`  ${chalk.cyan('products/')}          — product workspaces`);
+    console.log(productList);
+    console.log(`  ${chalk.cyan('projects/')}          — time-bounded projects (auto-created)`);
+    console.log(`  ${chalk.cyan('_system/')}           — infra docs + project templates\n`);
+
+    console.log(chalk.bold('  Next steps:\n'));
+    console.log(`  1. Open the workspace in Claude Code:`);
+    console.log(`     ${chalk.gray(`claude "${root}"`)}\n`);
+    console.log(`  2. Fill in the ${chalk.cyan('[TBD]')} placeholders by pasting or speaking:`);
+    console.log(`     ${chalk.gray('"Our brand voice is professional but warm..."')}`);
+    console.log(`     ${chalk.gray('"Our main product is X, which does Y..."')}\n`);
+    console.log(`  3. Create your first project:`);
+    console.log(`     ${chalk.gray('"New project: [describe what you need]"')}\n`);
+
+    if (config.infra.hasVps) {
+      console.log(`  4. Update ${chalk.cyan('_system/infra/vps.md')} with your deployed apps.\n`);
+    }
+
+    console.log(chalk.gray('  The workspace is self-updating — dump thoughts, voice notes,'));
+    console.log(chalk.gray('  or brain dumps directly into Claude and it will route them.\n'));
+
+  } catch (err) {
+    if (err.name === 'ExitPromptError') {
+      console.log(chalk.gray('\n  Cancelled.\n'));
+      process.exit(0);
+    }
+    console.error(chalk.red('\n  Error: ') + err.message);
+    process.exit(1);
+  }
+}

package/src/prompts.js

@@ -0,0 +1,137 @@
+import { input, checkbox, confirm, select } from '@inquirer/prompts';
+import chalk from 'chalk';
+
+const ALL_DEPARTMENTS = [
+  { name: 'Marketing', value: 'marketing' },
+  { name: 'Sales', value: 'sales' },
+  { name: 'Operations', value: 'operations' },
+  { name: 'Networking & BD', value: 'networking' },
+  { name: 'HR & Recruiting', value: 'hr' },
+  { name: 'Finance', value: 'finance' },
+  { name: 'Customer Success', value: 'customer-success' },
+  { name: 'Product', value: 'product' },
+  { name: 'Engineering', value: 'engineering' },
+];
+
+export async function gatherConfig() {
+  console.log(chalk.bold.cyan('\n  Claude OS — Workspace Setup\n'));
+  console.log(chalk.gray('  This will scaffold a Claude Code workspace with routing, memory,\n  and self-updating architecture.\n'));
+
+  // --- Company info ---
+  console.log(chalk.bold('  Company Info\n'));
+
+  const companyName = await input({
+    message: 'Company name:',
+    validate: v => v.trim().length > 0 || 'Required',
+  });
+
+  const companyDescription = await input({
+    message: 'What does the company do? (1-2 sentences):',
+    validate: v => v.trim().length > 0 || 'Required',
+  });
+
+  const companyTagline = await input({
+    message: 'Tagline or value prop (optional — press Enter to skip):',
+  });
+
+  const companyWebsite = await input({
+    message: 'Website (optional):',
+  });
+
+  const industry = await input({
+    message: 'Industry or niche:',
+    validate: v => v.trim().length > 0 || 'Required',
+  });
+
+  // --- Departments ---
+  console.log(chalk.bold('\n  Departments\n'));
+
+  const selectedDepts = await checkbox({
+    message: 'Which departments does this company have?',
+    choices: ALL_DEPARTMENTS,
+    instructions: '  Space to select · Enter to confirm',
+  });
+
+  const customDeptInput = await input({
+    message: 'Custom departments? (comma-separated, or Enter to skip):',
+  });
+
+  const customDepts = customDeptInput
+    .split(',')
+    .map(d => d.trim().toLowerCase().replace(/\s+/g, '-'))
+    .filter(Boolean);
+
+  const departments = [...selectedDepts, ...customDepts];
+
+  // --- Products ---
+  console.log(chalk.bold('\n  Products & Services\n'));
+
+  const addProducts = await confirm({
+    message: 'Add products or services now?',
+    default: true,
+  });
+
+  const products = [];
+  if (addProducts) {
+    let addMore = true;
+    while (addMore) {
+      const productName = await input({
+        message: `Product/service name:`,
+        validate: v => v.trim().length > 0 || 'Required',
+      });
+      const productDescription = await input({
+        message: `Short description:`,
+      });
+      const productSlug = productName.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+      products.push({ name: productName, slug: productSlug, description: productDescription });
+
+      addMore = await confirm({ message: 'Add another product/service?', default: false });
+    }
+  }
+
+  // --- Infrastructure ---
+  console.log(chalk.bold('\n  Infrastructure\n'));
+
+  const hasVps = await confirm({ message: 'Does this client have a VPS for app deployment?', default: false });
+  let vpsHost = '';
+  let vpsSshAlias = '';
+  if (hasVps) {
+    vpsHost = await input({ message: 'VPS IP or hostname:' });
+    vpsSshAlias = await input({ message: 'SSH alias (from ~/.ssh/config):' });
+  }
+
+  const hasLocalServer = await confirm({ message: 'Does this client have an always-on local machine (Mac Mini, NUC, etc.)?', default: false });
+  let localServerName = '';
+  if (hasLocalServer) {
+    localServerName = await input({ message: 'What is it called? (e.g. "Mac Mini"):' });
+  }
+
+  // --- Output directory ---
+  console.log(chalk.bold('\n  Output\n'));
+
+  const outputDir = await input({
+    message: 'Where should the workspace be created? (full path or . for current directory):',
+    default: '.',
+  });
+
+  return {
+    company: {
+      name: companyName.trim(),
+      description: companyDescription.trim(),
+      tagline: companyTagline.trim(),
+      website: companyWebsite.trim(),
+      industry: industry.trim(),
+      date: new Date().toISOString().split('T')[0],
+    },
+    departments,
+    products,
+    infra: {
+      hasVps,
+      vpsHost,
+      vpsSshAlias,
+      hasLocalServer,
+      localServerName,
+    },
+    outputDir: outputDir.trim(),
+  };
+}

package/src/scaffold.js

@@ -0,0 +1,93 @@
+import path from 'path';
+import fs from 'fs-extra';
+import {
+  generateClaudeMd,
+  generateContextMd,
+  generateProjectRegistry,
+  generateCompanyContextMd,
+  generateVoiceBrand,
+  generateProductsMd,
+  generateDeptContextMd,
+  generateProductContextMd,
+  generateSystemContextMd,
+  generateVpsMd,
+  generateLocalServerMd,
+  generateBizInitiativeTemplateMd,
+  generateVaWorkflowTemplateMd,
+  generateProductBuildTemplateMd,
+} from './templates.js';
+
+export async function scaffold(config) {
+  const root = config.outputDir === '.'
+    ? process.cwd()
+    : path.resolve(config.outputDir);
+
+  const write = async (relPath, content) => {
+    const fullPath = path.join(root, relPath);
+    await fs.ensureDir(path.dirname(fullPath));
+    await fs.writeFile(fullPath, content, 'utf8');
+  };
+
+  const mkdir = async (relPath) => {
+    await fs.ensureDir(path.join(root, relPath));
+  };
+
+  // ── Root files ──
+  await write('CLAUDE.md', generateClaudeMd(config));
+  await write('CONTEXT.md', generateContextMd(config));
+  await write('PROJECT-REGISTRY.md', generateProjectRegistry(config));
+
+  // ── company/ ──
+  await write('company/CONTEXT.md', generateCompanyContextMd(config));
+  await write('company/voice-brand.md', generateVoiceBrand(config));
+  await write('company/products.md', generateProductsMd(config));
+  await mkdir('company/sops');
+
+  // ── departments/ ──
+  for (const dept of config.departments) {
+    await write(`departments/${dept}/CONTEXT.md`, generateDeptContextMd(dept, config));
+    await mkdir(`departments/${dept}/assets`);
+    await mkdir(`departments/${dept}/output`);
+  }
+
+  // ── products/ ──
+  for (const product of config.products) {
+    await write(`products/${product.slug}/CONTEXT.md`, generateProductContextMd(product, config));
+    await mkdir(`products/${product.slug}/specs`);
+    await mkdir(`products/${product.slug}/assets`);
+    await mkdir(`products/${product.slug}/output`);
+  }
+
+  // ── projects/ ──
+  await mkdir('projects');
+
+  // ── _system/ ──
+  await write('_system/CONTEXT.md', generateSystemContextMd(config));
+  await mkdir('_system/infra');
+
+  if (config.infra.hasVps) {
+    await write('_system/infra/vps.md', generateVpsMd(config));
+  }
+
+  if (config.infra.hasLocalServer) {
+    const slug = (config.infra.localServerName || 'local-server')
+      .toLowerCase().replace(/\s+/g, '-');
+    await write(`_system/infra/${slug}.md`, generateLocalServerMd(config));
+  }
+
+  // ── _system/templates/ ──
+  await write('_system/templates/biz-initiative/CONTEXT.md', generateBizInitiativeTemplateMd());
+  await mkdir('_system/templates/biz-initiative/assets');
+  await mkdir('_system/templates/biz-initiative/output');
+
+  await write('_system/templates/va-workflow/CONTEXT.md', generateVaWorkflowTemplateMd());
+  await mkdir('_system/templates/va-workflow/assets');
+  await mkdir('_system/templates/va-workflow/output');
+
+  await write('_system/templates/product-build/CONTEXT.md', generateProductBuildTemplateMd());
+  await mkdir('_system/templates/product-build/specs');
+  await mkdir('_system/templates/product-build/assets');
+  await mkdir('_system/templates/product-build/output');
+
+  return root;
+}

package/src/templates.js

@@ -0,0 +1,927 @@
+// All workspace file generators. Each function takes a config object and returns a string.
+
+const toTitle = str => str.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+
+// ─── CLAUDE.md ───────────────────────────────────────────────────────────────
+
+export function generateClaudeMd(config) {
+  const { company, departments, products } = config;
+  const deptRows = departments.map(d => `│   ├── ${d}/`).join('\n');
+  const productRows = products.length
+    ? products.map(p => `│   ├── ${p.slug}/`).join('\n')
+    : '│   └── (add products as you build them)';
+
+  const navRows = [
+    '| **Capture scattered thoughts / voice notes** | Paste here — I will route and update automatically |',
+    '| **Create a new project** | Say: "New project: [description]" |',
+    '| **Write marketing copy or campaigns** | `departments/marketing/CONTEXT.md` |',
+    '| **Work on a sales process or pipeline** | `departments/sales/CONTEXT.md` |',
+    '| **Design a client workflow or SOP** | `departments/operations/CONTEXT.md` |',
+    ...departments.filter(d => !['marketing','sales','operations'].includes(d)).map(d =>
+      `| **${toTitle(d)} work** | \`departments/${d}/CONTEXT.md\` |`
+    ),
+    ...products.map(p => `| **${p.name} product work** | \`products/${p.slug}/CONTEXT.md\` |`),
+  ].join('\n');
+
+  const infraSection = config.infra.hasVps || config.infra.hasLocalServer ? `
+## Devices & Sync
+
+| Device | Role | Sync |
+|--------|------|------|
+| Primary machine | Development & operations | Full Dropbox |${config.infra.hasVps ? `\n| VPS (${config.infra.vpsHost || 'TBD'}) | Web app deployment | Git only |` : ''}${config.infra.hasLocalServer ? `\n| ${config.infra.localServerName || 'Local Server'} | Always-on automation | Selective sync |` : ''}
+
+---
+` : '';
+
+  return `# ${company.name} — Workspace Map
+
+## What This Is
+
+${company.description}${company.tagline ? `\n\n*${company.tagline}*` : ''}
+
+A workspace system for ${company.name}. An agent drops into a workspace, reads its CONTEXT.md, does its work, and exits.
+
+**CONTEXT.md** (top-level) routes you to the right workspace. This file is the map.
+
+---
+
+## Folder Structure
+
+\`\`\`
+workspace/
+├── CLAUDE.md                       ← You are here (always loaded)
+├── CONTEXT.md                      ← Task router
+├── PROJECT-REGISTRY.md             ← Index of all active projects
+│
+├── company/                        ← Evergreen company knowledge
+│   ├── CONTEXT.md
+│   ├── voice-brand.md              ← Brand voice, tone, messaging rules
+│   ├── products.md                 ← Product catalog
+│   └── sops/                       ← Internal SOPs (add as created)
+│
+├── departments/                    ← Department workspaces
+${deptRows}
+│
+├── products/                       ← Product-specific workspaces
+${productRows}
+│
+├── projects/                       ← Time-bounded initiatives
+│   └── (auto-created per project)
+│
+└── _system/                        ← Infrastructure & templates
+    ├── CONTEXT.md
+    ├── infra/
+${config.infra.hasVps ? '    │   ├── vps.md\n' : ''}${config.infra.hasLocalServer ? `    │   └── ${config.infra.localServerName?.toLowerCase().replace(/\s+/g,'-') || 'local-server'}.md\n` : ''}    └── templates/
+        ├── biz-initiative/
+        ├── va-workflow/
+        └── product-build/
+\`\`\`
+
+---
+
+## Quick Navigation
+
+| Want to... | Go here |
+|------------|---------|
+${navRows}
+| **Write or edit a company SOP** | \`company/CONTEXT.md\` |
+| **Check or update infrastructure** | \`_system/CONTEXT.md\` |
+
+---
+
+## Active Projects
+
+| Slug | Type | Department | Status | Path |
+|------|------|-----------|--------|------|
+| (none yet — projects auto-registered here) | | | | |
+
+---
+
+## New Project Creation
+
+When I say **"New project: [description]"**:
+1. Parse → infer type (biz-initiative / va-workflow / product-build), department, and a slug
+2. Copy the matching template from \`_system/templates/\`
+3. Create \`projects/[slug]/\` with the template files
+4. Add a row to **Active Projects** above and to \`PROJECT-REGISTRY.md\`
+5. Confirm what was created
+
+---
+
+## Naming Conventions
+
+| Content Type | Pattern | Example |
+|-------------|---------|---------|
+| Project folders | \`[slug]/\` | \`q2-newsletter-campaign/\` |
+| Deliverables | \`[slug]-v[n].[ext]\` | \`onboarding-sop-v2.docx\` |
+| SOPs | \`sop-[process].md\` | \`sop-client-onboarding.md\` |
+| Newsletters | \`[YYYY-MM-DD]-[slug].md\` | \`2026-03-10-launch-week.md\` |
+| Social posts | \`[platform]-[slug].md\` | \`linkedin-launch-announce.md\` |
+
+**Statuses:** \`draft\` → \`review\` → \`final\`
+
+---
+
+## Token Rules
+
+**Each workspace is siloed.** Don't load everything.
+
+- Writing copy? → Load \`company/voice-brand.md\`. Skip everything else.
+- Department task? → Load that department's CONTEXT.md. Skip other departments.
+- Infrastructure work? → Load \`_system/infra/\`. Skip company docs.
+
+The CONTEXT.md files tell you what to load per task. Trust them.
+
+---
+${infraSection}
+## Update Protocol
+
+The workspace is **self-updating and self-generating**. When given unstructured input (voice notes, brain dumps, scattered thoughts):
+
+### Routing Table
+
+| Information Type | Update These Files |
+|-----------------|-------------------|
+| Brand voice, tone, audience, messaging | \`company/voice-brand.md\` |
+| Product description, features, positioning | \`company/products.md\` |
+| How a department functions | \`departments/[dept]/CONTEXT.md\` |
+| A business process or repeatable workflow | \`company/sops/sop-[process].md\` (create if new) |
+| New product or major tool | \`company/products.md\` + \`products/[name]/CONTEXT.md\` |
+| Infrastructure or tech changes | \`_system/infra/\` files |
+| New project need | Trigger New Project flow (see above) |
+
+### Steps
+1. **Parse** — extract key facts, discard filler words
+2. **Route** — identify which file(s) this belongs in
+3. **Edit surgically** — fill \`[TBD]\` placeholders, never erase existing content
+4. **Propagate** — if update affects other files, update those too
+5. **Confirm** — tell user what changed and where
+`;
+}
+
+// ─── CONTEXT.md (root task router) ───────────────────────────────────────────
+
+export function generateContextMd(config) {
+  const { company, departments } = config;
+  const deptRows = departments.map(d =>
+    `| ${toTitle(d)} work | \`departments/${d}/CONTEXT.md\` | \`company/voice-brand.md\` (if writing) |`
+  ).join('\n');
+
+  return `# ${company.name} — Task Router
+
+Read this at the start of every session to find the right workspace.
+
+---
+
+## Task → Workspace
+
+| Task | Load | Also Load |
+|------|------|-----------|
+| Unstructured voice/text input | Stay here — run Update Protocol | Nothing |
+| New project scaffolding | Stay here — run New Project flow | \`_system/templates/\` |
+| Company voice / brand | \`company/CONTEXT.md\` | \`company/voice-brand.md\` |
+| Product info | \`company/CONTEXT.md\` | \`company/products.md\` |
+${deptRows}
+| Infrastructure / deployment | \`_system/CONTEXT.md\` | Relevant \`_system/infra/\` file |
+
+---
+
+## Cross-Workspace Flow (One-Way)
+
+\`\`\`
+company/ (brand + products)
+    ↓
+departments/ (tactics + operations)
+    ↓
+products/ (build + ship)
+    ↓
+_system/infra/ (deploy)
+\`\`\`
+
+Context flows downstream only. A department agent never needs to know about infrastructure.
+
+---
+
+## What NOT to Load
+
+- Don't load all department CONTEXT.md files at once — pick the one relevant to the task
+- Don't load \`_system/infra/\` unless doing deployment work
+- Don't load \`company/voice-brand.md\` unless writing copy
+`;
+}
+
+// ─── PROJECT-REGISTRY.md ──────────────────────────────────────────────────────
+
+export function generateProjectRegistry(config) {
+  return `# Project Registry
+
+Index of all time-bounded projects. Rows are auto-appended during project creation.
+
+| Slug | Type | Department | Status | Path | Created | Notes |
+|------|------|-----------|--------|------|---------|-------|
+`;
+}
+
+// ─── company/CONTEXT.md ───────────────────────────────────────────────────────
+
+export function generateCompanyContextMd(config) {
+  return `# Company Knowledge
+
+## When to Load What
+
+| Task | Load | Skip |
+|------|------|------|
+| Writing any copy or messaging | \`voice-brand.md\` | \`products.md\`, SOPs |
+| Referencing products / services | \`products.md\` | \`voice-brand.md\` |
+| Writing about a business process | Specific SOP from \`sops/\` | Everything else |
+| Both copy + product context | Both | SOPs |
+
+---
+
+## Folder Contents
+
+- \`voice-brand.md\` — Tone, personality, messaging rules, audience profiles
+- \`products.md\` — Product catalog, descriptions, positioning
+- \`sops/\` — Internal SOPs (created as processes are documented)
+
+---
+
+## SOP Naming
+
+\`sop-[process].md\` — e.g., \`sop-client-onboarding.md\`, \`sop-weekly-reporting.md\`
+`;
+}
+
+// ─── company/voice-brand.md ───────────────────────────────────────────────────
+
+export function generateVoiceBrand(config) {
+  const { company } = config;
+  return `# ${company.name} — Brand Voice & Messaging
+
+**Last updated:** ${company.date}
+
+---
+
+## Company Overview
+
+**What we do:** ${company.description}
+${company.tagline ? `**Tagline:** ${company.tagline}` : '**Tagline:** [TBD]'}
+**Industry:** ${company.industry}
+**Website:** ${company.website || '[TBD]'}
+
+---
+
+## Brand Voice
+
+**Tone:** [TBD — e.g., professional but approachable, confident, direct]
+
+**Personality traits:**
+- [TBD]
+- [TBD]
+- [TBD]
+
+**We sound like:** [TBD — describe the voice in 1 sentence]
+
+**We never sound:** [TBD — what to avoid]
+
+---
+
+## Messaging Rules
+
+**Core value proposition:** [TBD]
+
+**Key messages:**
+1. [TBD]
+2. [TBD]
+3. [TBD]
+
+**Words we use:** [TBD]
+**Words we avoid:** [TBD]
+
+---
+
+## Audience Profiles
+
+### Primary Audience
+- **Who:** [TBD]
+- **Pain point:** [TBD]
+- **What they want:** [TBD]
+- **How we talk to them:** [TBD]
+
+### Secondary Audience
+- **Who:** [TBD]
+- **Pain point:** [TBD]
+
+---
+
+## Channel-Specific Notes
+
+| Channel | Tone Adjustment | Format |
+|---------|----------------|--------|
+| LinkedIn | [TBD] | [TBD] |
+| Email | [TBD] | [TBD] |
+| Website | [TBD] | [TBD] |
+| Proposals | [TBD] | [TBD] |
+`;
+}
+
+// ─── company/products.md ──────────────────────────────────────────────────────
+
+export function generateProductsMd(config) {
+  const { company, products } = config;
+
+  const productSections = products.length
+    ? products.map(p => `
+## ${p.name}
+
+**Slug:** \`${p.slug}\`
+**Description:** ${p.description || '[TBD]'}
+**Status:** [TBD — e.g., active, in development, sunsetting]
+**Target customer:** [TBD]
+**Key differentiator:** [TBD]
+**Pricing:** [TBD]
+`).join('\n---\n')
+    : `
+## [Product Name]
+
+**Slug:** \`[slug]\`
+**Description:** [TBD]
+**Status:** [TBD]
+**Target customer:** [TBD]
+**Key differentiator:** [TBD]
+**Pricing:** [TBD]
+`;
+
+  return `# ${company.name} — Products & Services
+
+**Last updated:** ${company.date}
+
+---
+${productSections}
+`;
+}
+
+// ─── departments/[dept]/CONTEXT.md ────────────────────────────────────────────
+
+const DEPT_DETAILS = {
+  marketing: {
+    tasks: [
+      ['Write copy or campaign content', '`company/voice-brand.md`', 'All other docs'],
+      ['Research trends or competitors', 'None — use Web Search', 'Company docs'],
+      ['Create social posts', '`company/voice-brand.md`', 'Dept docs'],
+      ['Build a campaign strategy', '`company/products.md`, `voice-brand.md`', 'Infra docs'],
+    ],
+    tools: [
+      ['Web Search MCP', 'Research, trend analysis, competitor intel'],
+      ['`/docx`', 'Written deliverables, campaign briefs'],
+      ['`/pptx`', 'Presentations and pitch decks'],
+    ],
+    goal: 'Generate awareness and qualified leads.',
+  },
+  sales: {
+    tasks: [
+      ['Write outreach or follow-up copy', '`company/voice-brand.md`', 'Infra docs'],
+      ['Build a sales process or playbook', '`company/products.md`', 'Dept docs'],
+      ['Research a prospect', 'None — use Web Search', 'All docs'],
+      ['Create a proposal', '`company/products.md`, `voice-brand.md`', 'Infra docs'],
+    ],
+    tools: [
+      ['Web Search MCP', 'Prospect research, company intel'],
+      ['`/docx`', 'Proposals, follow-up documents'],
+    ],
+    goal: 'Convert prospects into clients.',
+  },
+  operations: {
+    tasks: [
+      ['Design a client workflow', '1-2 relevant SOPs from `company/sops/`', 'Marketing/sales docs'],
+      ['Write an SOP', '1-2 relevant SOPs from `company/sops/`', 'All other docs'],
+      ['Prepare a client deliverable', 'None', 'All docs'],
+      ['Review / revise an SOP', 'The specific SOP being revised', 'All other docs'],
+    ],
+    tools: [
+      ['`/docx`', 'Formatted SOPs and process docs'],
+      ['`/pdf`', 'Final client deliveries'],
+    ],
+    goal: 'Design and document efficient processes.',
+  },
+  networking: {
+    tasks: [
+      ['Find networking events', 'None — use Web Search', 'All docs'],
+      ['Write outreach messages', '`company/voice-brand.md`', 'Infra docs'],
+      ['Build a BD strategy', '`company/products.md`, `voice-brand.md`', 'Dept docs'],
+    ],
+    tools: [
+      ['Web Search MCP', 'Event discovery, contact research'],
+      ['`/docx`', 'Outreach templates, BD plans'],
+    ],
+    goal: 'Build strategic relationships and partnerships.',
+  },
+  hr: {
+    tasks: [
+      ['Write a job posting', '`company/voice-brand.md`', 'Infra docs'],
+      ['Build a recruiting process', '`company/sops/`', 'All other docs'],
+      ['Draft an HR policy', '1-2 relevant SOPs', 'All other docs'],
+    ],
+    tools: [
+      ['`/docx`', 'Job descriptions, HR docs'],
+    ],
+    goal: 'Attract, hire, and retain great people.',
+  },
+  finance: {
+    tasks: [
+      ['Build a financial model', 'None', 'All docs'],
+      ['Write financial copy', '`company/voice-brand.md`', 'Infra docs'],
+      ['Create a report', 'None', 'All docs'],
+    ],
+    tools: [
+      ['`/docx`', 'Financial reports, summaries'],
+    ],
+    goal: 'Maintain financial clarity and health.',
+  },
+  'customer-success': {
+    tasks: [
+      ['Write client-facing communication', '`company/voice-brand.md`', 'Infra docs'],
+      ['Document a client process', '`company/sops/`', 'All other docs'],
+      ['Build an onboarding flow', '`company/products.md`, `voice-brand.md`', 'Dept docs'],
+    ],
+    tools: [
+      ['`/docx`', 'Onboarding docs, client guides'],
+    ],
+    goal: 'Ensure clients succeed and stay.',
+  },
+  product: {
+    tasks: [
+      ['Define product requirements', '`company/products.md`', 'Infra docs'],
+      ['Write product copy', '`company/voice-brand.md`, `products.md`', 'Dept docs'],
+      ['Plan a feature', '`company/products.md`', 'All other docs'],
+    ],
+    tools: [
+      ['Web Search MCP', 'Competitive research, user research'],
+      ['`/docx`', 'PRDs, feature specs'],
+    ],
+    goal: 'Define and evolve the product.',
+  },
+  engineering: {
+    tasks: [
+      ['Build a feature', 'Relevant `products/[name]/CONTEXT.md`', 'Company/dept docs'],
+      ['Deploy an app', '`_system/infra/vps.md`', 'Company docs'],
+      ['Review code or architecture', 'Relevant product CONTEXT.md', 'All other docs'],
+    ],
+    tools: [
+      ['Web Search MCP', 'Library docs, API references'],
+      ['`_system/infra/vps.md`', 'VPS deployment pattern'],
+    ],
+    goal: 'Build and maintain reliable software.',
+  },
+};
+
+function getDefaultDeptDetails(dept) {
+  return {
+    tasks: [
+      ['Main task', 'Relevant files only', 'All other docs'],
+      ['Writing deliverables', '`company/voice-brand.md`', 'Infra docs'],
+    ],
+    tools: [
+      ['`/docx`', 'Written deliverables'],
+      ['Web Search MCP', 'Research'],
+    ],
+    goal: `[TBD — define the goal for ${toTitle(dept)}]`,
+  };
+}
+
+export function generateDeptContextMd(dept, config) {
+  const details = DEPT_DETAILS[dept] || getDefaultDeptDetails(dept);
+  const taskRows = details.tasks.map(([task, load, skip]) =>
+    `| ${task} | ${load} | ${skip} |`
+  ).join('\n');
+  const toolRows = details.tools.map(([tool, purpose]) =>
+    `| ${tool} | ${purpose} |`
+  ).join('\n');
+
+  return `# ${toTitle(dept)} — Department Workspace
+
+**Goal:** ${details.goal}
+
+---
+
+## Task → Load
+
+| Task | Load These | Skip These |
+|------|-----------|-----------|
+${taskRows}
+
+---
+
+## Folder Structure
+
+- \`brief.md\` — Project briefs and intake
+- \`assets/\` — Research, source materials, raw inputs
+- \`output/\` — Finished deliverables (\`[slug]-v[n].[ext]\`)
+
+---
+
+## Skills & Tools
+
+| Tool | Purpose |
+|------|---------|
+${toolRows}
+
+---
+
+## What NOT to Do
+
+- Don't load other departments' CONTEXT.md files
+- Don't load \`_system/infra/\` unless this task involves deployment
+- Don't load all of \`company/\` — pick only what's listed above
+`;
+}
+
+// ─── products/[slug]/CONTEXT.md ───────────────────────────────────────────────
+
+export function generateProductContextMd(product, config) {
+  return `# ${product.name} — Product Workspace
+
+**Description:** ${product.description || '[TBD]'}
+**Status:** [TBD — planning / active / launched]
+
+---
+
+## External Resources
+
+| Resource | Details |
+|----------|---------|
+| Git repo | [URL — add when created] |
+| Supabase project | [ID — add when created] |
+| VPS deployment | [domain — add when deployed] |
+| Tech stack | [TBD — define in specs] |
+
+---
+
+## Task → Load
+
+| Task | Load These | Skip These |
+|------|-----------|-----------|
+| Planning / brief | \`company/products.md\` | Infra docs, \`specs/\` |
+| Technical specs | \`_system/infra/vps.md\` (if VPS deploy) | Company docs |
+| Active development | \`specs/\` (this product) | Company docs |
+| Deployment | \`_system/infra/vps.md\` | All other docs |
+| Writing product copy | \`company/voice-brand.md\`, \`company/products.md\` | \`specs/\` |
+
+---
+
+## Folder Structure
+
+- \`brief.md\` — What to build and why
+- \`specs/\` — Technical specs, DB schema, API design (\`[feature]-spec.md\`)
+- \`assets/\` — Design mockups, reference materials
+- \`output/\` — Build artifacts, deployment notes
+
+---
+
+## Build Pipeline
+
+1. Brief → \`brief.md\`
+2. Specs → \`specs/[feature]-spec.md\`
+3. Build → Git repo (code lives outside this folder)
+4. Deploy → follow \`_system/infra/vps.md\` pattern
+5. Document → update **External Resources** table above
+`;
+}
+
+// ─── _system/CONTEXT.md ───────────────────────────────────────────────────────
+
+export function generateSystemContextMd(config) {
+  const infraFiles = [];
+  if (config.infra.hasVps) infraFiles.push('| Deploy or update a VPS app | `infra/vps.md` | All other docs |');
+  if (config.infra.hasLocalServer) {
+    const fname = config.infra.localServerName?.toLowerCase().replace(/\s+/g, '-') || 'local-server';
+    infraFiles.push(`| ${config.infra.localServerName} tasks | \`infra/${fname}.md\` | All other docs |`);
+  }
+  if (!infraFiles.length) infraFiles.push('| Infrastructure tasks | Relevant `infra/` file | All other docs |');
+
+  return `# System — Infrastructure & Templates
+
+## When to Load
+
+| Task | Load These | Skip |
+|------|-----------|------|
+${infraFiles.join('\n')}
+| Use a project template | \`templates/[type]/CONTEXT.md\` | All other docs |
+
+---
+
+## Folder Contents
+
+- \`infra/\` — Infrastructure reference docs (VPS, local servers)
+- \`templates/\` — Project type templates (biz-initiative, va-workflow, product-build)
+
+---
+
+## What NOT to Do
+
+- Don't load \`_system/\` for anything except infrastructure or template work
+- Don't load company or department docs from here
+`;
+}
+
+// ─── _system/infra/vps.md ────────────────────────────────────────────────────
+
+export function generateVpsMd(config) {
+  const { infra } = config;
+  return `# VPS — Infrastructure Reference
+
+**Host**: \`${infra.vpsHost || 'TBD'}\`
+**SSH alias**: \`${infra.vpsSshAlias || 'TBD'}\` (config: \`~/.ssh/config\`)
+
+---
+
+## Deployed Applications
+
+| App | Domain | Internal Port | Stack | Directory |
+|-----|--------|--------------|-------|-----------|
+| (none yet — add as apps are deployed) | | | | |
+
+---
+
+## Deployment Pattern (All New Apps Follow This)
+
+\`\`\`bash
+# 1. Create app directory
+mkdir ~/docker/[app-name] && cd ~/docker/[app-name]
+
+# 2. Add: docker-compose.yml, Dockerfile, .env
+
+# 3. Start containers
+docker compose up -d
+
+# 4. Add Nginx config
+sudo nano /etc/nginx/sites-enabled/[subdomain.yourdomain.com]
+sudo nginx -t && sudo systemctl reload nginx
+
+# 5. SSL certificate
+sudo certbot --nginx -d [subdomain.yourdomain.com]
+\`\`\`
+
+---
+
+## Nginx Config Template
+
+\`\`\`nginx
+server {
+    listen 80;
+    server_name [subdomain.yourdomain.com];
+    return 301 https://\$server_name\$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name [subdomain.yourdomain.com];
+
+    ssl_certificate /etc/letsencrypt/live/[subdomain.yourdomain.com]/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/[subdomain.yourdomain.com]/privkey.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:[PORT];
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade \$http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host \$host;
+        proxy_cache_bypass \$http_upgrade;
+    }
+}
+\`\`\`
+
+---
+
+## Running Services
+
+nginx, docker, containerd, cron, ssh — all managed by systemd.
+
+---
+
+## Known Issues
+
+- (none yet — document as discovered)
+`;
+}
+
+// ─── _system/infra/local-server.md ────────────────────────────────────────────
+
+export function generateLocalServerMd(config) {
+  const name = config.infra.localServerName || 'Local Server';
+  const slug = name.toLowerCase().replace(/\s+/g, '-');
+  return `# ${name} — Infrastructure Reference
+
+**Role**: Always-on local machine for automation and development.
+**Status**: Powered on continuously.
+
+---
+
+## Capabilities
+
+- [TBD — document what this machine does]
+
+---
+
+## Automation Use Cases
+
+| Use Case | Trigger | Notes |
+|----------|---------|-------|
+| [TBD] | [TBD] | |
+
+---
+
+## Development
+
+Can serve as a development environment for work that doesn't need public hosting.
+`;
+}
+
+// ─── _system/templates/biz-initiative/CONTEXT.md ────────────────────────────
+
+export function generateBizInitiativeTemplateMd() {
+  return `# [PROJECT-NAME] — Business Initiative
+
+**Type:** biz-initiative
+**Department:** [DEPARTMENT]
+**Created:** [YYYY-MM-DD]
+**Status:** active
+**Goal:** [1-sentence goal from project description]
+
+---
+
+## What This Project Is
+
+[Full description from project creation prompt]
+
+---
+
+## Task → Load
+
+| Task | Load These | Skip These |
+|------|-----------|-----------|
+| Research / planning | None — use Web Search | Company docs unless writing copy |
+| Writing deliverables | \`company/voice-brand.md\` | All other docs |
+| Campaign assets | \`company/voice-brand.md\` | All other docs |
+| Final review | \`company/voice-brand.md\` | All other docs |
+
+---
+
+## Folder Structure
+
+- \`brief.md\` — Project brief, goals, and success criteria
+- \`assets/\` — Research, source materials, raw inputs
+- \`output/\` — Finished deliverables (naming: \`[slug]-v[n].[ext]\`)
+
+---
+
+## Process
+
+1. Define goals → \`brief.md\`
+2. Research → \`assets/\`
+3. Create deliverables → working files or directly to \`output/\`
+4. Review against brief goals
+5. Finalize → \`output/[slug]-v[n].[ext]\`
+6. Mark complete → update **Status** above + \`PROJECT-REGISTRY.md\`
+
+---
+
+## Skills & Tools
+
+| Tool | When | Purpose |
+|------|------|---------|
+| Web Search MCP | Research phase | Trend data, event finding, competitor intel |
+| \`/docx\` | Written deliverables | Formatted Word docs for external use |
+| \`/pptx\` | Presentation deliverables | Slide decks |
+`;
+}
+
+// ─── _system/templates/va-workflow/CONTEXT.md ────────────────────────────────
+
+export function generateVaWorkflowTemplateMd() {
+  return `# [PROJECT-NAME] — VA Workflow
+
+**Type:** va-workflow
+**Client:** [CLIENT-NAME]
+**Created:** [YYYY-MM-DD]
+**Status:** active
+**Goal:** [1-sentence goal]
+
+---
+
+## What This Project Is
+
+[Full description from project creation prompt]
+
+---
+
+## Task → Load
+
+| Task | Load These | Skip These |
+|------|-----------|-----------|
+| Design workflow | \`company/sops/\` (1-2 relevant SOPs for style reference) | All other docs |
+| Write SOP | \`company/sops/\` (1-2 relevant SOPs for style reference) | All other docs |
+| Client deliverable prep | None | All docs |
+| Review / revise | The specific SOP being revised | All other docs |
+
+---
+
+## Folder Structure
+
+- \`brief.md\` — Client brief, scope, and requirements
+- \`assets/\` — Client inputs, existing processes, reference materials
+- \`output/\` — Finished SOPs and workflow docs (naming: \`sop-[process]-v[n].[ext]\`)
+
+---
+
+## Process
+
+1. Capture client requirements → \`brief.md\`
+2. Gather inputs → \`assets/\`
+3. Draft SOP / workflow
+4. Review with client feedback
+5. Finalize → \`output/sop-[process]-v[n].[ext]\`
+6. If SOP is company-internal → copy to \`company/sops/sop-[process].md\`
+7. Mark complete → update **Status** above + \`PROJECT-REGISTRY.md\`
+
+---
+
+## Skills & Tools
+
+| Tool | When | Purpose |
+|------|------|---------|
+| \`/docx\` | All SOPs | Formatted Word docs for client delivery |
+| \`/pdf\` | Final delivery | PDF version if client requests it |
+`;
+}
+
+// ─── _system/templates/product-build/CONTEXT.md ──────────────────────────────
+
+export function generateProductBuildTemplateMd() {
+  return `# [PROJECT-NAME] — Product Build
+
+**Type:** product-build
+**Product:** [PRODUCT-NAME]
+**Created:** [YYYY-MM-DD]
+**Status:** planning
+**Goal:** [1-sentence goal]
+
+---
+
+## What This Project Is
+
+[Full description from project creation prompt]
+
+---
+
+## External Resources
+
+| Resource | Details |
+|----------|---------|
+| Git repo | [URL — add when created] |
+| Supabase project | [ID — add when created] |
+| VPS deployment | [domain — add when deployed] |
+| Tech stack | [TBD — define in specs] |
+
+---
+
+## Task → Load
+
+| Task | Load These | Skip These |
+|------|-----------|-----------|
+| Planning / brief | \`company/products.md\` | Infra docs, \`specs/\` |
+| Technical specs | \`_system/infra/vps.md\` (if VPS deploy) | Company docs |
+| Active development | \`specs/\` (this project) | Company docs |
+| Deployment | \`_system/infra/vps.md\` | All other docs |
+| Writing product copy | \`company/voice-brand.md\`, \`company/products.md\` | \`specs/\` |
+
+---
+
+## Folder Structure
+
+- \`brief.md\` — What to build and why
+- \`specs/\` — Technical specs, DB schema, API design (naming: \`[feature]-spec.md\`)
+- \`assets/\` — Design mockups, reference materials
+- \`output/\` — Build artifacts, deployment notes
+
+---
+
+## Build Pipeline
+
+1. Brief → \`brief.md\` (what + why)
+2. Specs → \`specs/[feature]-spec.md\` (tech decisions)
+3. Build → Git repo (code lives outside this folder)
+4. Deploy → follow \`_system/infra/vps.md\` pattern
+5. Document → update **External Resources** table above with live URLs
+6. Mark complete → update **Status** above + \`PROJECT-REGISTRY.md\`
+
+---
+
+## Skills & Tools
+
+| Tool | When | Purpose |
+|------|------|---------|
+| Web Search MCP | Specs phase | Library docs, best practices, API references |
+| \`_system/infra/vps.md\` | Deployment | VPS deployment pattern and commands |
+`;
+}