productkit 1.9.0 → 1.10.0

package/src/commands/list.js

@@ -1,6 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const { getWorkspaceRoot } = require('../utils/fileUtils');
 
 async function list() {
   const root = process.cwd();
@@ -25,6 +26,22 @@ async function list() {
   console.log(chalk.bold('Available slash commands:'));
   console.log();
 
+  // Show workspace landscape command if in a workspace
+  const workspaceRoot = getWorkspaceRoot(root);
+  if (workspaceRoot) {
+    const landscapePath = path.join(workspaceRoot, '.claude', 'commands', 'productkit.landscape.md');
+    if (fs.existsSync(landscapePath)) {
+      const content = fs.readFileSync(landscapePath, 'utf-8');
+      let description = '';
+      const match = content.match(/^---\s*\n[\s\S]*?description:\s*(.+)\n[\s\S]*?---/);
+      if (match) description = match[1].trim();
+
+      console.log(`  ${chalk.cyan('/productkit.landscape')} ${chalk.dim('(workspace)')}`);
+      if (description) console.log(`    ${description}`);
+      console.log();
+    }
+  }
+
   for (const file of files) {
     const name = '/' + file.replace('.md', '');
     const content = fs.readFileSync(path.join(commandsDir, file), 'utf-8');

package/src/commands/reset.js

@@ -2,18 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 const readline = require('readline');
-const { getArtifactDir } = require('../utils/fileUtils');
-
-const ARTIFACTS = [
-  'constitution.md',
-  'users.md',
-  'problem.md',
-  'assumptions.md',
-  'validation.md',
-  'solution.md',
-  'priorities.md',
-  'spec.md',
-];
+const { getArtifactDir, ARTIFACT_FILES: ARTIFACTS } = require('../utils/fileUtils');
 
 function confirm(question) {
   const rl = readline.createInterface({

package/src/commands/status.js

@@ -1,18 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { getArtifactDir } = require('../utils/fileUtils');
-
-const ARTIFACTS = [
-  { file: 'constitution.md', command: '/productkit.constitution', label: 'Constitution' },
-  { file: 'users.md', command: '/productkit.users', label: 'Users' },
-  { file: 'problem.md', command: '/productkit.problem', label: 'Problem' },
-  { file: 'assumptions.md', command: '/productkit.assumptions', label: 'Assumptions' },
-  { file: 'validation.md', command: '/productkit.validate', label: 'Validation' },
-  { file: 'solution.md', command: '/productkit.solution', label: 'Solution' },
-  { file: 'priorities.md', command: '/productkit.prioritize', label: 'Priorities' },
-  { file: 'spec.md', command: '/productkit.spec', label: 'Spec' },
-];
+const { getArtifactDir, getWorkspaceRoot, ARTIFACTS_WITH_COMMANDS: ARTIFACTS } = require('../utils/fileUtils');
 
 async function status() {
   const root = process.cwd();
@@ -25,6 +14,7 @@ async function status() {
   }
 
   const artifactDir = getArtifactDir(root);
+  const workspaceRoot = getWorkspaceRoot(root);
   const done = [];
   const remaining = [];
 
@@ -38,6 +28,19 @@ async function status() {
   }
 
   console.log();
+
+  // Show workspace landscape status if in a workspace
+  if (workspaceRoot) {
+    const landscapeExists = fs.existsSync(path.join(workspaceRoot, 'landscape.md'));
+    console.log(chalk.bold('Workspace:'));
+    if (landscapeExists) {
+      console.log(chalk.green('  done  Landscape (landscape.md)'));
+    } else {
+      console.log(chalk.yellow('  todo  Landscape — run /productkit.landscape from workspace root'));
+    }
+    console.log();
+  }
+
   console.log(chalk.bold(`Progress: ${done.length}/${ARTIFACTS.length} artifacts`));
   console.log();
 

package/src/commands/update.js

@@ -18,11 +18,20 @@ async function update() {
 
   fs.ensureDirSync(targetDir);
 
-  const commandFiles = fs.readdirSync(commandsDir);
+  let commandFiles;
+  try {
+    commandFiles = fs.readdirSync(commandsDir);
+  } catch {
+    console.error(chalk.red('Templates directory missing — Product Kit installation may be corrupted.'));
+    process.exit(1);
+  }
   let updated = 0;
   let added = 0;
 
   for (const file of commandFiles) {
+    // Landscape is workspace-only, skip for projects
+    if (file === 'productkit.landscape.md') continue;
+
     const src = path.join(commandsDir, file);
     const dest = path.join(targetDir, file);
     const existed = fs.existsSync(dest);
@@ -37,10 +46,40 @@ async function update() {
     }
   }
 
-  // Update CLAUDE.md
+  // Update workspace landscape command if in a workspace
+  const { getWorkspaceRoot } = require('../utils/fileUtils');
+  const workspaceRoot = getWorkspaceRoot(root);
+  if (workspaceRoot) {
+    const wsSrc = path.join(commandsDir, 'productkit.landscape.md');
+    const wsDest = path.join(workspaceRoot, '.claude', 'commands', 'productkit.landscape.md');
+    if (fs.existsSync(wsSrc)) {
+      fs.ensureDirSync(path.join(workspaceRoot, '.claude', 'commands'));
+      fs.copyFileSync(wsSrc, wsDest);
+      console.log(chalk.green('  ~ workspace landscape command updated'));
+    }
+  }
+
+  // Update CLAUDE.md — replace the Product Kit section, preserve user customizations
   const claudeSrc = path.join(templatesDir, 'CLAUDE.md');
   const claudeDest = path.join(root, 'CLAUDE.md');
-  fs.copyFileSync(claudeSrc, claudeDest);
+  const templateContent = fs.readFileSync(claudeSrc, 'utf-8');
+
+  if (fs.existsSync(claudeDest)) {
+    const existingContent = fs.readFileSync(claudeDest, 'utf-8');
+    // Check if the file was created by init --existing (appended to user's CLAUDE.md)
+    const marker = '# Product Kit Project';
+    const markerIndex = existingContent.indexOf(marker);
+    if (markerIndex > 0) {
+      // Preserve everything before the Product Kit section
+      const userContent = existingContent.substring(0, markerIndex);
+      fs.writeFileSync(claudeDest, userContent + templateContent);
+    } else {
+      // Standalone CLAUDE.md — safe to replace entirely
+      fs.copyFileSync(claudeSrc, claudeDest);
+    }
+  } else {
+    fs.copyFileSync(claudeSrc, claudeDest);
+  }
 
   console.log();
   console.log(chalk.green.bold('Slash commands updated!'));

package/src/commands/workspace.js

@@ -0,0 +1,63 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+async function workspace(workspaceName) {
+  if (!workspaceName) {
+    console.error(chalk.red('Error: Workspace name is required.'));
+    console.error(chalk.dim('Usage: productkit workspace <name>'));
+    process.exit(1);
+  }
+
+  const workspaceRoot = path.join(process.cwd(), workspaceName);
+
+  if (fs.existsSync(workspaceRoot)) {
+    console.error(chalk.red(`Error: Directory "${workspaceName}" already exists`));
+    process.exit(1);
+  }
+
+  try {
+    const templatesDir = path.join(__dirname, '..', '..', 'templates');
+
+    // Create workspace directory and config
+    fs.ensureDirSync(path.join(workspaceRoot, '.productkit'));
+    const pkgVersion = require('../../package.json').version;
+    fs.writeJsonSync(path.join(workspaceRoot, '.productkit', 'config.json'), {
+      type: 'workspace',
+      version: pkgVersion,
+      created: new Date().toISOString(),
+      knowledge_dir: 'knowledge',
+    }, { spaces: 2 });
+
+    // Copy landscape slash command to workspace level
+    fs.ensureDirSync(path.join(workspaceRoot, '.claude', 'commands'));
+    fs.copyFileSync(
+      path.join(templatesDir, 'commands', 'productkit.landscape.md'),
+      path.join(workspaceRoot, '.claude', 'commands', 'productkit.landscape.md')
+    );
+
+    // Create workspace-level knowledge directory
+    const knowledgeDir = path.join(workspaceRoot, 'knowledge');
+    fs.ensureDirSync(knowledgeDir);
+    fs.copyFileSync(
+      path.join(templatesDir, 'knowledge-README.md'),
+      path.join(knowledgeDir, 'README.md')
+    );
+
+    console.log(chalk.green.bold('Workspace created successfully!'));
+    console.log();
+    console.log(chalk.cyan('Workspace:'), workspaceName);
+    console.log();
+    console.log(chalk.cyan('Next steps:'));
+    console.log(`  1. cd ${workspaceName}`);
+    console.log('  2. productkit init my-app');
+    console.log('  3. claude');
+    console.log(`  4. /productkit.landscape  ${chalk.dim('(writes to workspace root)')}`);
+    console.log();
+  } catch (error) {
+    console.error(chalk.red('Error creating workspace:'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = workspace;

package/src/utils/fileUtils.js

@@ -1,15 +1,12 @@
 const fs = require('fs-extra');
 const path = require('path');
 
-function isProductKitProject() {
-  return fs.existsSync(path.join(process.cwd(), '.productkit'));
-}
-
-function getProjectRoot() {
-  if (isProductKitProject()) {
-    return process.cwd();
+function resolveContainedPath(root, relativePath, fallback) {
+  const resolved = path.resolve(root, relativePath);
+  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
+    return fallback;
   }
-  return null;
+  return resolved;
 }
 
 function getArtifactDir(root) {
@@ -17,14 +14,63 @@ function getArtifactDir(root) {
   try {
     const config = fs.readJsonSync(configPath);
     if (config.artifact_dir) {
-      return path.join(root, config.artifact_dir);
+      return resolveContainedPath(root, config.artifact_dir, root);
     }
   } catch {}
   return root;
 }
 
+function getWorkspaceRoot(projectRoot) {
+  const parentDir = path.dirname(projectRoot);
+  const configPath = path.join(parentDir, '.productkit', 'config.json');
+  try {
+    const config = fs.readJsonSync(configPath);
+    if (config.type === 'workspace') {
+      return parentDir;
+    }
+  } catch {}
+  return null;
+}
+
+const ARTIFACT_FILES = [
+  'landscape.md',
+  'constitution.md',
+  'users.md',
+  'problem.md',
+  'assumptions.md',
+  'validation.md',
+  'solution.md',
+  'priorities.md',
+  'spec.md',
+  'audit.md',
+  'knowledge-index.md',
+  'techreview.md',
+  'stories.md',
+];
+
+const ARTIFACTS_WITH_COMMANDS = [
+  { file: 'landscape.md', command: '/productkit.landscape', label: 'Landscape' },
+  { file: 'constitution.md', command: '/productkit.constitution', label: 'Constitution' },
+  { file: 'users.md', command: '/productkit.users', label: 'Users' },
+  { file: 'problem.md', command: '/productkit.problem', label: 'Problem' },
+  { file: 'assumptions.md', command: '/productkit.assumptions', label: 'Assumptions' },
+  { file: 'validation.md', command: '/productkit.validate', label: 'Validation' },
+  { file: 'solution.md', command: '/productkit.solution', label: 'Solution' },
+  { file: 'priorities.md', command: '/productkit.prioritize', label: 'Priorities' },
+  { file: 'spec.md', command: '/productkit.spec', label: 'Spec' },
+  { file: 'audit.md', command: '/productkit.audit', label: 'Audit' },
+  { file: 'knowledge-index.md', command: '/productkit.learn', label: 'Knowledge Index' },
+  { file: 'techreview.md', command: '/productkit.techreview', label: 'Tech Review' },
+  { file: 'stories.md', command: '/productkit.stories', label: 'Stories' },
+];
+
+// Lighter version without command info (for export/diff)
+const ARTIFACTS = ARTIFACTS_WITH_COMMANDS.map(({ file, label }) => ({ file, label }));
+
 module.exports = {
-  isProductKitProject,
-  getProjectRoot,
   getArtifactDir,
+  getWorkspaceRoot,
+  ARTIFACT_FILES,
+  ARTIFACTS,
+  ARTIFACTS_WITH_COMMANDS,
 };

package/templates/CLAUDE.md

@@ -6,6 +6,7 @@ This project uses Product Kit for structured product thinking.
 
 Use these commands in order to build your product foundation:
 
+0. `/productkit.landscape` — Capture company, team, and domain context (run once, before everything else)
 1. `/productkit.constitution` — Define your product principles
 2. `/productkit.users` — Define target user personas
 3. `/productkit.problem` — Frame the problem statement
@@ -17,11 +18,19 @@ Use these commands in order to build your product foundation:
 9. `/productkit.clarify` — Resolve ambiguities across artifacts
 10. `/productkit.analyze` — Run a completeness/consistency check
 11. `/productkit.bootstrap` — Auto-draft all artifacts from an existing codebase
-12. `/productkit.audit` — Compare spec against codebase and surface gaps
+12. `/productkit.audit` — Compare spec against codebase and surface gaps (post-build — what was actually implemented vs spec)
+13. `/productkit.learn` — Index knowledge directory into a summary for faster commands
+14. `/productkit.techreview` — Review spec against codebase and flag what needs engineering input (pre-build — feasibility before implementation)
+15. `/productkit.stories` — Break spec into user stories with acceptance criteria
+
+## Mode
+
+Check `.productkit/config.json` for a `mode` field — either `"solo"` (building alone) or `"team"` (working with engineers/designers). Commands should adapt their output based on mode: solo mode can skip team-oriented sections (e.g., handoff notes, engineering specs), while team mode should include collaboration artifacts and detailed technical specs.
 
 ## Artifacts
 
 Product artifacts are written as markdown files. Check `.productkit/config.json` for an `artifact_dir` field — if set, artifacts live in that directory instead of the project root. Default artifact locations:
+- `landscape.md` — Company, team, and domain landscape
 - `constitution.md` — Product principles and values
 - `users.md` — Target user personas
 - `problem.md` — Problem statement
@@ -30,9 +39,27 @@ Product artifacts are written as markdown files. Check `.productkit/config.json`
 - `solution.md` — Chosen solution with alternatives considered
 - `priorities.md` — Scored and ranked feature list
 - `spec.md` — Complete product spec ready for engineering
+- `audit.md` — Spec vs codebase audit with gap analysis
+- `knowledge-index.md` — Summary index of research files in `knowledge/`
+- `techreview.md` — Technical feasibility review with effort estimates
+- `stories.md` — User stories grouped by epic with acceptance criteria
 
 ## Workflow
 
-Start with `/productkit.constitution` or `/productkit.users`, then work through the commands in order. Each command reads previous artifacts to maintain consistency.
+Start with `/productkit.landscape` to front-load company knowledge, then `/productkit.constitution` or `/productkit.users`, and work through the commands in order. Each command reads previous artifacts to maintain consistency.
 
 For existing projects, use `/productkit.bootstrap` to auto-draft all artifacts from your codebase in one session.
+
+## Workspaces
+
+If this project lives inside a workspace (created with `productkit workspace`), it shares a workspace directory. The workspace holds:
+- `landscape.md` at the workspace root — shared company/domain context across all projects
+- `knowledge/` at the workspace root — shared research files
+
+All slash commands automatically detect workspace membership by checking `../.productkit/config.json` for `"type": "workspace"`. Workspace-level `landscape.md` and `knowledge/` supplement project-level files.
+
+## Knowledge Directory
+
+The `knowledge/` directory is for raw research files — interview transcripts, survey results, analytics exports, PDFs, and other evidence. Run `/productkit.learn` to index these files into `knowledge-index.md` — a compact summary that all other slash commands read instead of scanning raw files directly. Check `.productkit/config.json` for a `knowledge_dir` field (default: `knowledge`).
+
+If the project is inside a workspace, `/productkit.learn` also indexes the workspace-level `knowledge/` directory.

package/templates/README.md

@@ -10,6 +10,7 @@ claude
 
 Then use the slash commands to build your product foundation:
 
+0. `/productkit.landscape` — Capture company, team, and domain context
 1. `/productkit.constitution` — Define your product principles
 2. `/productkit.users` — Define target user personas
 3. `/productkit.problem` — Frame the problem statement
@@ -22,6 +23,9 @@ Then use the slash commands to build your product foundation:
 10. `/productkit.analyze` — Check consistency and completeness
 11. `/productkit.bootstrap` — Auto-draft all artifacts from existing codebase
 12. `/productkit.audit` — Compare spec against actual implementation
+13. `/productkit.learn` — Index knowledge directory for faster commands
+14. `/productkit.techreview` — Review spec against codebase, flag engineering questions
+15. `/productkit.stories` — Break spec into user stories with acceptance criteria
 
 ## Artifacts
 
@@ -29,6 +33,7 @@ Artifacts are written to the project root by default. If `artifact_dir` is set i
 
 | File | Description |
 |------|-------------|
+| `landscape.md` | Company, team, and domain landscape |
 | `constitution.md` | Product principles and values |
 | `users.md` | Target user personas |
 | `problem.md` | Problem statement |
@@ -37,3 +42,15 @@ Artifacts are written to the project root by default. If `artifact_dir` is set i
 | `solution.md` | Chosen solution with alternatives considered |
 | `priorities.md` | Scored and ranked feature list |
 | `spec.md` | Complete product spec ready for engineering |
+| `audit.md` | Spec vs codebase audit with gap analysis |
+| `knowledge-index.md` | Summary index of research files in `knowledge/` |
+| `techreview.md` | Technical feasibility review with effort estimates |
+| `stories.md` | User stories grouped by epic with acceptance criteria |
+
+## Workspaces
+
+If this project lives inside a workspace (created with `productkit workspace <name>`), the workspace root contains shared `landscape.md` and `knowledge/` that all projects inherit automatically.
+
+## Knowledge Directory
+
+Drop raw research files into the `knowledge/` directory — interview transcripts, survey results, analytics exports, PDFs, etc. Run `/productkit.learn` to index these files into `knowledge-index.md` — all other slash commands read this index instead of scanning raw files directly. If inside a workspace, `/productkit.learn` also indexes the workspace-level `knowledge/` directory.

package/templates/commands/productkit.analyze.md

@@ -13,11 +13,20 @@ Evaluate the overall quality, consistency, and completeness of the product think
 Check `.productkit/config.json` for an `artifact_dir` field. If set, read artifacts there instead of the project root. If not set, default to the project root.
 
 Read all existing artifacts:
+- `landscape.md`
 - `constitution.md`
 - `users.md`
 - `problem.md`
 - `assumptions.md`
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Check whether artifacts adequately reference available evidence. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 Work with whatever exists.
 
 ## Analysis Dimensions

package/templates/commands/productkit.assumptions.md

@@ -17,8 +17,17 @@ Read these files first (required):
 If either file is missing, tell the user which commands to run first.
 
 Also read if they exist:
+- `landscape.md` — company and domain landscape
 - `constitution.md` — product principles
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when identifying assumptions that need validation. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 ## Process
 
 1. **Extract assumptions** — Read through each artifact and identify every assumption (stated and unstated)

package/templates/commands/productkit.audit.md

@@ -17,10 +17,17 @@ Read these artifacts (required):
 - `priorities.md` — feature priorities and v1 scope (required)
 
 Also read if they exist:
+- `landscape.md` — company and domain landscape
 - `solution.md` — chosen solution
 - `validation.md` — assumption validation results
 - `assumptions.md` — known risks
 
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 At minimum, `spec.md` must exist. If it's missing, tell the user to run `/productkit.spec` first.
 
 ### Scan the codebase

package/templates/commands/productkit.bootstrap.md

@@ -10,7 +10,14 @@ Analyze the existing project — code, docs, README, config files, comments —
 
 ## Before You Start
 
-1. Read the project's README, CLAUDE.md, package.json (or equivalent), and scan the directory structure to understand what this project does.
+1. Read the project's README, CLAUDE.md, package.json (or equivalent), and scan the directory structure to understand what this project does. Also read `landscape.md` if it exists — use it for company and domain context. Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence when drafting artifacts. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 2. Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
 3. Check which artifacts already exist (constitution.md, users.md, problem.md, assumptions.md, solution.md, priorities.md, spec.md) in the artifact directory. **Skip any that already exist** — tell the user you're skipping them.
 4. Check `.productkit/config.json` — if `minimal: true`, skip `constitution.md`.

package/templates/commands/productkit.clarify.md

@@ -13,11 +13,20 @@ Cross-reference all existing artifacts, find inconsistencies, and guide the user
 Check `.productkit/config.json` for an `artifact_dir` field. If set, read and write artifacts there instead of the project root. If not set, default to the project root.
 
 Read all existing artifacts:
+- `landscape.md`
 - `constitution.md`
 - `users.md`
 - `problem.md`
 - `assumptions.md`
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when checking for contradictions between research evidence and artifact claims. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 Work with whatever exists — this command can run at any stage.
 
 ## Process

package/templates/commands/productkit.constitution.md

@@ -8,13 +8,28 @@ You are a product management coach helping establish a product constitution —
 
 Act as a seasoned PM mentor. Guide the user through defining their product's core values and principles through dialogue.
 
+## Before You Start
+
+Check `.productkit/config.json` for an `artifact_dir` field. If set, write artifacts there instead of the project root. If not set, default to the project root.
+
+Read `landscape.md` if it exists — use company, domain, and team context to ask more relevant questions and ground the constitution in real constraints.
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence when drafting principles. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 ## Process
 
 1. **Ask about the product vision** — What change do they want to see in the world?
 2. **Explore values** — What matters most? Speed vs quality? Privacy vs convenience? Ask them to make hard tradeoffs.
 3. **Identify non-negotiables** — What will this product NEVER do?
 4. **Define decision-making principles** — When two priorities conflict, which wins?
-5. **Draft the constitution** — Synthesize into a clear, concise document.
+5. **Capture prior research & decisions** — What user research has been done for this project? Are there existing product documents (PRDs, strategy docs, OKRs)? What decisions are already locked in? What's been tried before that didn't work?
+6. **Draft the constitution** — Synthesize into a clear, concise document.
 
 ## Conversation Style
 
@@ -45,4 +60,10 @@ Write the final constitution to `constitution.md` with this format:
 
 ## Decision Framework
 When [X] conflicts with [Y], we choose [X] because [reason].
+
+## Prior Research & Decisions
+- **Research Done:** [Summary of existing user research for this project]
+- **Existing Docs:** [PRDs, strategy docs, OKRs, etc.]
+- **Decisions Made:** [Key decisions already locked in]
+- **Failed Approaches:** [What's been tried and didn't work]
 ```