phewsh 0.3.0 → 0.5.0

package/bin/phewsh.js

@@ -28,7 +28,8 @@ function showBrand() {
   console.log('');
   console.log(`  ${d('😮\u200d💨')} ${d('🤫')}`);
   console.log('');
-  console.log(`  ${b(w('P H E W S H'))}`);
+  console.log(`  ${b(w('█▀█ █░█ █▀▀ █░█ █▀ █░█'))}`);
+  console.log(`  ${b(w('█▀▀ █▀█ ██▄ ▀▄▀ ▄█ █▀█'))}`);
   console.log(`  ${g('Build with clarity. Execute without drift.')}`);
   console.log('');
   console.log(hint);
@@ -36,11 +37,15 @@ function showBrand() {
 }
 
 const COMMANDS = {
-  intent: () => require('../commands/intent'),
-  login:  () => require('../commands/login'),
-  ai:     () => require('../commands/ai'),
-  music:  () => require('../commands/music'),
-  sap:    () => require('../commands/sap'),
+  intent:  () => require('../commands/intent'),
+  clarify: () => require('../commands/clarify'),
+  push:    () => require('../commands/push'),
+  pull:    () => require('../commands/pull'),
+  link:    () => require('../commands/link'),
+  login:   () => require('../commands/login'),
+  ai:      () => require('../commands/ai'),
+  music:   () => require('../commands/music'),
+  sap:     () => require('../commands/sap'),
   help:    showHelp,
   version: showVersion,
 };
@@ -54,17 +59,21 @@ function showHelp() {
   showBrand();
   console.log(`  ${g('v' + pkg.version)}  ·  ${g('phewsh.com')}\n`);
   console.log(`  ${b('Commands')}`);
-  console.log(`    ${w('login')}     Set up identity, API key, and cloud sync`);
-  console.log(`    ${w('intent')}    Structure thinking → vision, plan, next actions`);
+  console.log(`    ${w('clarify')}   Turn messy intent into a structured project spec`);
+  console.log(`    ${w('push')}      Push local .intent/ to cloud`);
+  console.log(`    ${w('pull')}      Pull project from cloud to .intent/`);
+  console.log(`    ${w('link')}      Link local .intent/ to a cloud project`);
+  console.log(`    ${w('intent')}    Manage .intent/ artifacts — status, open, evolve`);
   console.log(`    ${w('ai')}        Run context-aware AI prompts (reads .intent/)`);
+  console.log(`    ${w('login')}     Set up identity, API key, and cloud sync`);
   console.log(`    ${w('sap')}       Sustainable AI Protocol — usage and accountability`);
   console.log(`    ${w('music')}     MBHD music engine`);
   console.log('');
   console.log(`  ${b('Quick start')}`);
-  console.log(`    ${g('phewsh login')}                     Set up identity + API key`);
-  console.log(`    ${g('phewsh intent --init')}             Create .intent/ in any project`);
-  console.log(`    ${g('phewsh intent --sync')}             Push .intent/ to cloud`);
-  console.log(`    ${g('phewsh ai run "what\'s next?"')}    AI with your project context`);
+  console.log(`    ${g('phewsh login')}                          Set up identity + API key`);
+  console.log(`    ${g('phewsh clarify')}                        Compile messy intent → structured spec`);
+  console.log(`    ${g('phewsh push')}                           Sync to cloud`);
+  console.log(`    ${g('phewsh ai run "what\'s next?"')}         AI with your project context`);
   console.log('');
 }
 

package/commands/clarify.js

@@ -0,0 +1,233 @@
+// phewsh clarify
+// Takes raw, messy intent and compiles it into a structured PPS.
+// First run: creates .intent/ + pps.json + .md views.
+// Subsequent runs: updates pps.json fields and regenerates views.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { readPPS, writePPS, createPPS, generateViews } = require('../lib/pps');
+
+const CONFIG_PATH = path.join(os.homedir(), '.phewsh', 'config.json');
+const INTENT_DIR = path.join(process.cwd(), '.intent');
+
+const args = process.argv.slice(3);
+const textFlag = args.indexOf('--text');
+const rawFromFlag = textFlag !== -1 ? args.slice(textFlag + 1).join(' ') : null;
+const isUpdate = args.includes('--update') || args.includes('-u');
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_PATH)) return null;
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8')); } catch { return null; }
+}
+
+function getProjectName() {
+  const existing = readPPS(INTENT_DIR);
+  if (existing?.entity) return existing.entity;
+  const visionPath = path.join(INTENT_DIR, 'vision.md');
+  if (fs.existsSync(visionPath)) {
+    const m = fs.readFileSync(visionPath, 'utf-8').match(/^entity:\s*(.+)$/m);
+    if (m) return m[1].trim();
+  }
+  return path.basename(process.cwd());
+}
+
+async function askForInput() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log('\n  Describe what you\'re building. Be as messy as you want.\n');
+    console.log('  (You\'re the David Rose. PHEWSH is the business registration clerk.)\n');
+    process.stdout.write('  > ');
+    let input = '';
+    rl.on('line', (line) => { input += (input ? ' ' : '') + line.trim(); });
+    rl.on('close', () => resolve(input.trim()));
+  });
+}
+
+async function callClarifyAPI(apiKey, raw, existing) {
+  const isRefine = !!(existing?.intent?.goal);
+
+  const systemPrompt = `You are a project compiler. Your job is to extract clean, structured intent from messy human input.
+
+Return ONLY valid JSON — no markdown, no explanation, no commentary. The JSON must match this exact schema:
+
+{
+  "goal": "one sentence north star (what this is and why it exists)",
+  "success_criteria": ["measurable outcome", "measurable outcome"],
+  "constraints": ["constraint or non-negotiable", "..."],
+  "inputs": ["what this takes in or requires"],
+  "outputs": ["what this produces or delivers"],
+  "tasks": [
+    {"text": "first concrete action to take", "type": "do"},
+    {"text": "second action", "type": "do"}
+  ]
+}
+
+Rules:
+- goal: one sentence, no buzzwords, no hedging
+- success_criteria: 2-5 items, must be measurable or observable
+- constraints: real limits only (budget, time, technical, ethical). 0-3 items.
+- inputs: what the project needs to function (data, people, tools). 1-4 items.
+- outputs: what the project delivers. 1-4 items.
+- tasks: 3-7 concrete next actions, specific enough to act on immediately
+- type options: "do" (manual action), "copy" (command to run), "open" (URL to visit), "install" (package to install)
+${isRefine ? '\nThis is a refinement of existing intent. The previous goal was: ' + existing.intent.goal : ''}`;
+
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: {
+      'x-api-key': apiKey,
+      'anthropic-version': '2023-06-01',
+      'content-type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'claude-sonnet-4-6',
+      max_tokens: 1024,
+      system: systemPrompt,
+      messages: [{ role: 'user', content: raw }],
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.json().catch(() => ({}));
+    throw new Error(err.error?.message || `API error ${response.status}`);
+  }
+
+  const data = await response.json();
+  const text = data.content?.[0]?.text || '';
+
+  // Strip markdown code fences if present
+  const clean = text.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim();
+  return JSON.parse(clean);
+}
+
+function writeViews(intentDir, pps) {
+  const { vision, plan, next } = generateViews(pps);
+  fs.writeFileSync(path.join(intentDir, 'vision.md'), vision);
+  fs.writeFileSync(path.join(intentDir, 'plan.md'), plan);
+  fs.writeFileSync(path.join(intentDir, 'next.md'), next);
+}
+
+async function main() {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+  😮‍💨🤫  phewsh clarify
+
+  Usage:
+    phewsh clarify                    Interactive: describe your project, get structured PPS
+    phewsh clarify --text "..."       Inline: pass raw text directly
+    phewsh clarify --update           Refine existing PPS with new input
+
+  What it does:
+    Takes messy, buzzword-heavy input and compiles it into a structured project spec (PPS).
+    Writes .intent/pps.json as the source of truth.
+    Generates vision.md, plan.md, next.md as human-readable views.
+
+  Requires:
+    phewsh login --set-key            Set your Anthropic API key first
+
+  Examples:
+    phewsh clarify
+    phewsh clarify --text "I want to build a thing that helps people track habits with AI"
+    phewsh clarify --update           After new context or direction change
+    `);
+    return;
+  }
+
+  const config = loadConfig();
+  if (!config?.apiKey) {
+    console.log('\n  No API key found. Run `phewsh login --set-key` first.\n');
+    process.exit(1);
+  }
+
+  const existing = readPPS(INTENT_DIR);
+  if (existing && !isUpdate) {
+    console.log('\n  .intent/pps.json already exists.');
+    console.log('  Run `phewsh clarify --update` to refine, or `phewsh intent --status` to view.\n');
+    return;
+  }
+
+  console.log('\n  😮‍💨🤫  phewsh clarify\n');
+
+  let raw = rawFromFlag;
+  if (!raw) {
+    if (!process.stdin.isTTY) {
+      console.error('\n  Pipe input or use --text "your description"\n');
+      process.exit(1);
+    }
+    raw = await askForInput();
+  }
+
+  if (!raw) {
+    console.log('\n  Nothing to clarify.\n');
+    return;
+  }
+
+  console.log('\n  Compiling...\n');
+
+  let extracted;
+  try {
+    extracted = await callClarifyAPI(config.apiKey, raw, existing);
+  } catch (err) {
+    console.error('\n  Clarify failed:', err.message, '\n');
+    process.exit(1);
+  }
+
+  const entity = getProjectName();
+  let pps;
+
+  if (existing && isUpdate) {
+    // Patch existing PPS with new intent fields, preserve id/created/tasks state
+    pps = {
+      ...existing,
+      intent: {
+        raw,
+        goal: extracted.goal,
+        success_criteria: extracted.success_criteria || [],
+        constraints: extracted.constraints || [],
+        inputs: extracted.inputs || [],
+        outputs: extracted.outputs || [],
+      },
+    };
+    // Merge new tasks (preserve done tasks, add new ones)
+    const doneTasks = existing.tasks.filter(t => t.status === 'done');
+    const newTasks = (extracted.tasks || []).map((t, i) => ({
+      id: `t_${String(Date.now() + i).slice(-6)}`,
+      text: t.text,
+      status: 'open',
+      type: t.type || 'do',
+      blocked_by: null,
+    }));
+    pps.tasks = [...doneTasks, ...newTasks];
+    pps.state.phase = 'plan';
+  } else {
+    pps = createPPS({ entity, raw, intent: extracted });
+    pps.state.phase = 'plan';
+  }
+
+  fs.mkdirSync(INTENT_DIR, { recursive: true });
+  writePPS(INTENT_DIR, pps);
+  writeViews(INTENT_DIR, pps);
+
+  console.log(`  ✓ .intent/pps.json       — structured project spec`);
+  console.log(`  ✓ .intent/vision.md      — ${pps.intent.goal}`);
+  console.log(`  ✓ .intent/plan.md        — ${pps.intent.success_criteria.length} outcomes, ${pps.intent.constraints.length} constraints`);
+  console.log(`  ✓ .intent/next.md        — ${pps.tasks.length} actions\n`);
+  console.log(`  Goal: ${pps.intent.goal}\n`);
+  if (pps.tasks.length > 0) {
+    console.log('  First actions:');
+    pps.tasks.slice(0, 3).forEach(t => console.log(`    ·  ${t.text}`));
+  }
+  console.log(`
+  Next:
+    phewsh intent --status     Review your artifacts
+    phewsh clarify --update    Refine with more context
+    phewsh ai run "..."        Run AI with this context
+  `);
+}
+
+main().catch(err => {
+  console.error('\n  Error:', err.message);
+  process.exit(1);
+});

package/commands/intent.js

@@ -2,6 +2,7 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 const { execSync } = require('child_process');
+const { createPPS, writePPS, generateViews } = require('../lib/pps');
 
 const args = process.argv.slice(3);
 const INTENT_DIR = path.join(process.cwd(), '.intent');
@@ -113,97 +114,40 @@ async function initIntent() {
 
   console.log('\n  Creating .intent/ ...\n');
 
-  fs.mkdirSync(INTENT_DIR, { recursive: true });
-
-  const vision = `---
-entity: ${projectName}
-archetype: product
-created: ${date}
-updated: ${date}
----
-
-# Vision
-
-## North Star
-${what || `What is ${projectName} and why does it exist?`}
-
-## Outcomes
-${goal ? `- ${goal}` : '<!-- What does success look like? 3-5 concrete outcomes. -->'}
-- <!-- Add more outcomes here -->
-
-## Principles
-<!-- Non-negotiable values and constraints. What will you never compromise on? -->
--
--
-
-## Beneficiaries
-<!-- Who benefits from this and how? Be specific. -->
-`;
-
-  const plan = `---
-entity: ${projectName}
-archetype: product
-created: ${date}
-updated: ${date}
----
-
-# Plan
-
-## Current Strategy
-<!-- One paragraph: the approach and why it's the right one right now. -->
-
-## Systems
-<!-- What needs to exist? Key components, tools, structures. -->
-
-## Sequence
-<!-- Phased plan. What must come first? What is blocked on what? -->
-- Phase 1:
-- Phase 2:
-- Phase 3:
-
-## Constraints
-<!-- What limits this? Budget, time, team, technical. Be honest. -->
-
-## Resources
-<!-- What do you have available? Team, tools, existing assets. -->
-`;
-
-  const next = `---
-entity: ${projectName}
-archetype: product
-created: ${date}
-updated: ${date}
----
-
-# Next
-
-## Current State
-${what ? `Building: ${what}` : '<!-- Where things stand right now, honestly. -->'}
-
-## Next Actions
-- [ ] **Refine the vision** — Open the web compass and complete vision.md
-- [ ] **Define Phase 1** — What is the smallest thing you can ship?
-- [ ] **Identify the first blocker** — What is standing between you and execution?
-
-## Blocked
-<!-- What is stuck and why? What decision is needed to unblock it? -->
-
-## Metrics
-<!-- 2-3 numbers that tell you if it's working. -->
-`;
+  // Build a starter PPS and generate views from it
+  const pps = createPPS({
+    entity: projectName,
+    archetype: 'product',
+    raw: [what, goal].filter(Boolean).join(' '),
+    intent: {
+      goal: what || '',
+      success_criteria: goal ? [goal] : [],
+      constraints: [],
+      inputs: [],
+      outputs: [],
+      tasks: [
+        { text: 'Refine the vision — complete vision.md', type: 'do' },
+        { text: 'Define Phase 1 — what is the smallest thing to ship?', type: 'do' },
+        { text: 'Identify the first blocker', type: 'do' },
+      ],
+    },
+  });
 
+  writePPS(INTENT_DIR, pps);
+  const { vision, plan, next } = generateViews(pps);
   fs.writeFileSync(path.join(INTENT_DIR, 'vision.md'), vision);
   fs.writeFileSync(path.join(INTENT_DIR, 'plan.md'), plan);
   fs.writeFileSync(path.join(INTENT_DIR, 'next.md'), next);
 
+  console.log(`  ✓ .intent/pps.json     — Structured project spec (source of truth)`);
   console.log(`  ✓ .intent/vision.md    — The north star`);
   console.log(`  ✓ .intent/plan.md      — The strategy`);
   console.log(`  ✓ .intent/next.md      — What to do right now`);
   console.log(`
-  These files are your persistent context.
-  Drop them in any AI coding session and your tools gain full understanding.
+  Tip: Run \`phewsh clarify\` to have AI compile your messy intent into a precise spec.
 
   Next:
+    phewsh clarify            Compile intent → structured spec with AI
     phewsh intent --open      Open the web compass to go deeper
     phewsh intent --status    Check your progress any time
   `);

package/commands/link.js

@@ -0,0 +1,4 @@
+// phewsh link <cloud-project-id>
+// Associate local .intent/ with a specific cloud project
+const { main } = require('./sync');
+main('link');

package/commands/pull.js

@@ -0,0 +1,4 @@
+// phewsh pull
+// Pull pps.json + artifacts from cloud to local .intent/
+const { main } = require('./sync');
+main('pull');

package/commands/push.js

@@ -0,0 +1,4 @@
+// phewsh push
+// Push local .intent/pps.json + artifacts to cloud (Supabase)
+const { main } = require('./sync');
+main('push');

package/commands/sync.js

@@ -6,6 +6,7 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 const { select, upsert, refreshSession } = require('../lib/supabase');
+const { readPPS, writePPS } = require('../lib/pps');
 
 const CONFIG_PATH = path.join(os.homedir(), '.phewsh', 'config.json');
 const INTENT_DIR = path.join(process.cwd(), '.intent');
@@ -69,18 +70,50 @@ async function push(config, token) {
     token
   );
 
+  // Read pps.json if it exists
+  const localPPS = readPPS(INTENT_DIR);
+  const archetype = localPPS?.archetype || 'product';
+  const projectId = localPPS?.adapters?.phewsh?.cloud_id || null;
+
   if (existing.length > 0) {
     project = existing[0];
-  } else {
-    const created = await upsert('projects', {
-      id: genProjectId(),
+  } else if (projectId) {
+    // Linked to a specific cloud project — fetch it
+    const linked = await select('projects', `id=eq.${projectId}&user_id=eq.${userId}&select=id,name`, token).catch(() => []);
+    project = linked[0] || null;
+  }
+
+  if (!project) {
+    const payload = {
+      id: (localPPS?.adapters?.phewsh?.cloud_id) || genProjectId(),
       user_id: userId,
       name: projectName,
-      archetype: 'product',
-      freeform_text: '',
-    }, token);
+      archetype,
+      freeform_text: localPPS?.intent?.raw || '',
+    };
+    if (localPPS) payload.pps_json = localPPS;
+    const created = await upsert('projects', payload, token);
     project = Array.isArray(created) ? created[0] : created;
     console.log(`  Created project: ${projectName}`);
+  } else if (localPPS) {
+    // Update pps_json on existing project
+    await upsert('projects', {
+      id: project.id,
+      user_id: userId,
+      name: projectName,
+      archetype,
+      freeform_text: localPPS.intent?.raw || '',
+      pps_json: localPPS,
+    }, token).catch(() => {});
+  }
+
+  // Store cloud project_id back into local pps.json for linking
+  if (localPPS && project?.id) {
+    if (!localPPS.adapters) localPPS.adapters = {};
+    if (!localPPS.adapters.phewsh) localPPS.adapters.phewsh = {};
+    localPPS.adapters.phewsh.cloud_id = project.id;
+    localPPS.adapters.phewsh.last_synced = new Date().toISOString();
+    writePPS(INTENT_DIR, localPPS);
   }
 
   // Push each artifact file
@@ -97,42 +130,51 @@ async function push(config, token) {
     }, token);
     pushed.push(file);
   }
+  if (localPPS) pushed.unshift('pps.json');
 
-  console.log(`\n  ✓ Synced to cloud — ${projectName}`);
+  console.log(`\n  ✓ Pushed to cloud — ${projectName} (${project.id})`);
   pushed.forEach(f => console.log(`    ${f}`));
   console.log('');
 }
 
-async function pull(config, token) {
+async function pull(config, token, cloudId = null) {
   const projectName = getProjectName();
   const userId = config.supabaseUserId;
 
-  const projects = await select(
-    'projects',
-    `name=eq.${encodeURIComponent(projectName)}&user_id=eq.${userId}&select=id,name`,
-    token
-  );
+  let query = cloudId
+    ? `id=eq.${cloudId}&user_id=eq.${userId}&select=id,name,pps_json`
+    : `name=eq.${encodeURIComponent(projectName)}&user_id=eq.${userId}&select=id,name,pps_json`;
+
+  const projects = await select('projects', query, token);
 
   if (projects.length === 0) {
-    console.log(`\n  No cloud project found for "${projectName}".\n  Push first with: phewsh intent --sync\n`);
+    console.log(`\n  No cloud project found for "${projectName}".\n  Push first with: phewsh push\n`);
     return;
   }
 
   const project = projects[0];
+  fs.mkdirSync(INTENT_DIR, { recursive: true });
+
+  const pulled = [];
+
+  // Restore pps.json from cloud if present
+  if (project.pps_json) {
+    const localPPS = readPPS(INTENT_DIR);
+    const merged = { ...project.pps_json };
+    // Keep any local adapter links
+    if (localPPS?.adapters) merged.adapters = { ...project.pps_json.adapters, ...localPPS.adapters };
+    merged.adapters = merged.adapters || {};
+    merged.adapters.phewsh = { cloud_id: project.id, last_synced: new Date().toISOString() };
+    writePPS(INTENT_DIR, merged);
+    pulled.push('pps.json');
+  }
+
   const artifacts = await select(
     'artifacts',
     `project_id=eq.${project.id}&user_id=eq.${userId}&select=kind,content,updated_at`,
     token
   );
 
-  if (artifacts.length === 0) {
-    console.log('\n  No artifacts found in cloud for this project.\n');
-    return;
-  }
-
-  fs.mkdirSync(INTENT_DIR, { recursive: true });
-
-  const pulled = [];
   for (const artifact of artifacts) {
     const file = KIND_TO_FILE[artifact.kind];
     if (!file) continue;
@@ -140,11 +182,43 @@ async function pull(config, token) {
     pulled.push(file);
   }
 
-  console.log(`\n  ✓ Pulled from cloud — ${projectName}`);
+  if (pulled.length === 0) {
+    console.log('\n  No data found in cloud for this project.\n');
+    return;
+  }
+
+  console.log(`\n  ✓ Pulled from cloud — ${project.name} (${project.id})`);
   pulled.forEach(f => console.log(`    ${f}`));
   console.log('');
 }
 
+async function link(config, token, cloudId) {
+  const projectName = getProjectName();
+  const userId = config.supabaseUserId;
+
+  const projects = await select('projects', `id=eq.${cloudId}&user_id=eq.${userId}&select=id,name`, token);
+  if (projects.length === 0) {
+    console.log(`\n  No cloud project found with id: ${cloudId}\n`);
+    process.exit(1);
+  }
+
+  const project = projects[0];
+  let localPPS = readPPS(INTENT_DIR);
+  if (!localPPS) {
+    console.log('\n  No local .intent/pps.json found. Run `phewsh clarify` or `phewsh intent --init` first.\n');
+    process.exit(1);
+  }
+
+  if (!localPPS.adapters) localPPS.adapters = {};
+  if (!localPPS.adapters.phewsh) localPPS.adapters.phewsh = {};
+  localPPS.adapters.phewsh.cloud_id = project.id;
+  localPPS.adapters.phewsh.last_synced = null;
+  writePPS(INTENT_DIR, localPPS);
+
+  console.log(`\n  ✓ Linked .intent/ → cloud project "${project.name}" (${project.id})\n`);
+  console.log('  Run `phewsh push` to sync.\n');
+}
+
 async function main(direction = 'push') {
   const config = loadConfig();
   if (!config?.supabaseUserId) {
@@ -160,9 +234,17 @@ async function main(direction = 'push') {
 
   if (direction === 'pull') {
     await pull(config, token);
+  } else if (direction === 'link') {
+    const args = process.argv.slice(3);
+    const cloudId = args[1];
+    if (!cloudId) {
+      console.log('\n  Usage: phewsh link <cloud-project-id>\n');
+      process.exit(1);
+    }
+    await link(config, token, cloudId);
   } else {
     await push(config, token);
   }
 }
 
-module.exports = { main };
+module.exports = { main, push, pull, link, ensureValidToken, loadConfig };

package/lib/pps.js

@@ -0,0 +1,158 @@
+// PPS — Portable Project Spec
+// pps.json is the source of truth. .md files are generated views.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function genId() {
+  return `p_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+}
+
+function genTaskId(index) {
+  return `t_${String(index + 1).padStart(3, '0')}`;
+}
+
+function readPPS(intentDir) {
+  const p = path.join(intentDir, 'pps.json');
+  if (!fs.existsSync(p)) return null;
+  try { return JSON.parse(fs.readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+function writePPS(intentDir, data) {
+  fs.mkdirSync(intentDir, { recursive: true });
+  const now = new Date().toISOString().split('T')[0];
+  data.updated = now;
+  fs.writeFileSync(path.join(intentDir, 'pps.json'), JSON.stringify(data, null, 2));
+}
+
+function createPPS({ entity, archetype = 'product', raw = '', intent = {} }) {
+  const now = new Date().toISOString().split('T')[0];
+  return {
+    id: genId(),
+    version: '0.1',
+    entity,
+    archetype,
+    created: now,
+    updated: now,
+    intent: {
+      raw,
+      goal: intent.goal || '',
+      success_criteria: intent.success_criteria || [],
+      constraints: intent.constraints || [],
+      inputs: intent.inputs || [],
+      outputs: intent.outputs || [],
+    },
+    tasks: (intent.tasks || []).map((t, i) => ({
+      id: genTaskId(i),
+      text: t.text,
+      status: 'open',
+      type: t.type || 'do',
+      blocked_by: null,
+    })),
+    state: {
+      phase: 'clarify',
+      last_action: now,
+      progress: 0,
+    },
+    assets: [],
+    adapters: {
+      anthropic: { project_id: null, last_synced: null },
+      openai: { project_id: null, last_synced: null },
+    },
+  };
+}
+
+function generateViews(pps) {
+  const { entity, intent, tasks, created, updated, archetype } = pps;
+
+  const vision = `---
+entity: ${entity}
+archetype: ${archetype}
+created: ${created}
+updated: ${updated}
+---
+
+# Vision
+
+## North Star
+${intent.goal || `What is ${entity} and why does it exist?`}
+
+## Outcomes
+${intent.success_criteria.length > 0
+  ? intent.success_criteria.map(c => `- ${c}`).join('\n')
+  : '<!-- What does success look like? 3-5 concrete outcomes. -->'}
+
+## Principles
+${intent.constraints.length > 0
+  ? intent.constraints.map(c => `- ${c}`).join('\n')
+  : '<!-- Non-negotiable values and constraints. -->'}
+
+## Beneficiaries
+<!-- Who benefits from this and how? -->
+`;
+
+  const plan = `---
+entity: ${entity}
+archetype: ${archetype}
+created: ${created}
+updated: ${updated}
+---
+
+# Plan
+
+## Current Strategy
+<!-- One paragraph: the approach and why it's the right one right now. -->
+
+## Systems
+${intent.inputs.length > 0 || intent.outputs.length > 0
+  ? [
+      intent.inputs.length > 0 ? `**Inputs:** ${intent.inputs.join(', ')}` : '',
+      intent.outputs.length > 0 ? `**Outputs:** ${intent.outputs.join(', ')}` : '',
+    ].filter(Boolean).join('\n')
+  : '<!-- Key components, tools, structures. -->'}
+
+## Sequence
+${tasks.length > 0
+  ? tasks.slice(0, 5).map((t, i) => `- Phase ${i + 1}: ${t.text}`).join('\n')
+  : '- Phase 1:\n- Phase 2:\n- Phase 3:'}
+
+## Constraints
+${intent.constraints.length > 0
+  ? intent.constraints.map(c => `- ${c}`).join('\n')
+  : '<!-- What limits this? Budget, time, team, technical. -->'}
+
+## Resources
+<!-- What do you have available? Team, tools, existing assets. -->
+`;
+
+  const next = `---
+entity: ${entity}
+archetype: ${archetype}
+created: ${created}
+updated: ${updated}
+---
+
+# Next
+
+## Current State
+${intent.goal ? `Building: ${intent.goal}` : '<!-- Where things stand right now. -->'}
+
+## Next Actions
+${tasks.length > 0
+  ? tasks.map(t => `- [ ] **${t.text}**`).join('\n')
+  : `- [ ] **Refine the vision** — Open the web compass and complete vision.md
+- [ ] **Define Phase 1** — What is the smallest thing you can ship?
+- [ ] **Identify the first blocker** — What is standing between you and execution?`}
+
+## Blocked
+<!-- What is stuck and why? -->
+
+## Metrics
+<!-- 2-3 numbers that tell you if it's working. -->
+`;
+
+  return { vision, plan, next };
+}
+
+module.exports = { readPPS, writePPS, createPPS, generateViews, genId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"