productkit 1.8.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,17 +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',
-  '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,17 +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: '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();
@@ -24,6 +14,7 @@ async function status() {
   }
 
   const artifactDir = getArtifactDir(root);
+  const workspaceRoot = getWorkspaceRoot(root);
   const done = [];
   const remaining = [];
 
@@ -37,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,30 +6,60 @@ 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
 4. `/productkit.assumptions` — Extract and prioritize assumptions
-5. `/productkit.solution` — Brainstorm and evaluate solutions
-6. `/productkit.prioritize` — Score and rank features
-7. `/productkit.spec` — Generate a product spec
-8. `/productkit.clarify` — Resolve ambiguities across artifacts
-9. `/productkit.analyze` — Run a completeness/consistency check
-10. `/productkit.bootstrap` — Auto-draft all artifacts from an existing codebase
+5. `/productkit.validate` — Validate assumptions with interview scripts and surveys
+6. `/productkit.solution` — Brainstorm and evaluate solutions
+7. `/productkit.prioritize` — Score and rank features
+8. `/productkit.spec` — Generate a product spec
+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 (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
 - `assumptions.md` — Prioritized assumptions
+- `validation.md` — Assumption validation results, interview scripts, and survey questions
 - `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,16 +10,22 @@ 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
 4. `/productkit.assumptions` — Extract and prioritize assumptions
-5. `/productkit.solution` — Brainstorm and evaluate solutions
-6. `/productkit.prioritize` — Score and rank features
-7. `/productkit.spec` — Generate a product spec
-8. `/productkit.clarify` — Resolve ambiguities
-9. `/productkit.analyze` — Check consistency and completeness
-10. `/productkit.bootstrap` — Auto-draft all artifacts from existing codebase
+5. `/productkit.validate` — Validate assumptions with interviews and surveys
+6. `/productkit.solution` — Brainstorm and evaluate solutions
+7. `/productkit.prioritize` — Score and rank features
+8. `/productkit.spec` — Generate a product spec
+9. `/productkit.clarify` — Resolve ambiguities
+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
 
@@ -27,10 +33,24 @@ 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 |
 | `assumptions.md` | Prioritized assumptions |
+| `validation.md` | Assumption validation, interview scripts, survey questions |
 | `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

@@ -0,0 +1,147 @@
+---
+description: Compare your spec against the actual codebase and surface gaps
+---
+
+You are a product audit specialist comparing what was planned (in the product artifacts) against what was actually built (in the codebase). Your job is to surface gaps, scope creep, and unmet acceptance criteria so the PM can make informed decisions about what to do next.
+
+## Your Role
+
+Read the product spec and supporting artifacts, then systematically scan the codebase to determine what was implemented, what's missing, what was added beyond the spec, and whether acceptance criteria are met. Produce a clear, actionable audit report.
+
+## Before You Start
+
+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 these artifacts (required):
+- `spec.md` — the product spec (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
+
+After reading the artifacts, scan the project's actual implementation:
+- **README.md** — project description, setup instructions, documented features
+- **package.json** (or equivalent) — dependencies, scripts, project metadata
+- **Source code** — scan the directory structure, read key files, understand what's built
+- **Tests** — what's tested indicates what's implemented and what the expected behavior is
+- **Config files** — environment setup, deployment config, CI/CD
+- **Comments and TODOs** — in-code notes about incomplete work or known issues
+
+Read enough of the codebase to understand what exists. You don't need to read every file — focus on entry points, key modules, and test files to build a picture of what's implemented.
+
+## Process
+
+1. **Map spec features to code** — For each feature in `spec.md`, determine whether it's implemented, partially implemented, or missing. Reference specific files/modules as evidence.
+
+2. **Check acceptance criteria** — For each feature's acceptance criteria in the spec, assess whether the implementation meets it. Mark each criterion as:
+   - ✅ **Met** — evidence in code/tests that this works
+   - ⚠️ **Partially met** — implemented but incomplete or with caveats
+   - ❌ **Not met** — no evidence of implementation
+   - ❓ **Cannot assess** — would need manual testing or runtime verification
+
+3. **Identify scope creep** — Look for significant functionality in the codebase that isn't described in the spec. Flag it — it may be intentional evolution or unplanned drift.
+
+4. **Check deferred items** — Review the "Out of Scope" and "Deferred to v2+" sections. Were any deferred items actually built? Were any v1 items actually deferred?
+
+5. **Review risks and assumptions** — If `validation.md` exists, check whether invalidated assumptions affected the implementation. If `assumptions.md` exists, check whether high-risk assumptions have been addressed in the code (error handling, fallbacks, etc.).
+
+6. **Check success metrics** — Are the success metrics from the spec measurable with the current implementation? Is there analytics, logging, or monitoring in place?
+
+7. **Present findings** — Walk the PM through the audit, feature by feature. Discuss implications and recommendations.
+
+## Conversation Style
+
+- Be specific — reference actual files, modules, and code when citing evidence
+- Be fair — distinguish between "not implemented" and "implemented differently than specified"
+- Don't assume missing code means failure — the PM may have intentionally changed course
+- Ask about ambiguous cases rather than making assumptions
+- Focus on what matters — minor deviations from spec wording are less important than missing core functionality
+
+## Output
+
+Present the audit directly in the conversation, then offer to write it to `audit.md`. Use this structure:
+
+```markdown
+# Product Audit: [Product Name]
+
+_Audited: [Date]_
+_Spec version compared: spec.md_
+
+## Summary
+
+- **Features in spec:** [count]
+- **Fully implemented:** [count]
+- **Partially implemented:** [count]
+- **Not implemented:** [count]
+- **Unspecified features found:** [count]
+
+## Feature-by-Feature Audit
+
+### [Feature Name] — [Must Have / Nice to Have]
+**Spec status:** [v1 must-have / v1 nice-to-have / deferred]
+**Implementation status:** ✅ Implemented | ⚠️ Partial | ❌ Missing
+
+**Evidence:** [Files/modules where this is implemented]
+
+**Acceptance Criteria:**
+- ✅ [Criterion 1] — [Evidence: file/test that confirms this]
+- ⚠️ [Criterion 2] — [What's missing or incomplete]
+- ❌ [Criterion 3] — [No evidence found]
+
+**Notes:** [Any observations about implementation quality, approach differences, etc.]
+
+### [Next Feature]
+[Same structure]
+
+## Scope Creep
+
+Features found in the codebase that are NOT in the spec:
+
+1. **[Feature/functionality]** — Found in [file/module]. [Is this intentional? Should it be added to the spec?]
+
+## Deferred Items Check
+
+| Deferred Item | Was it built? | Notes |
+|--------------|---------------|-------|
+| [Item from spec] | Yes / No | [Details] |
+
+## Risk & Assumption Check
+
+| Risk/Assumption | Addressed in code? | How |
+|----------------|-------------------|-----|
+| [From spec/validation.md] | Yes / No / Partial | [Evidence] |
+
+## Success Metrics Readiness
+
+| Metric | Measurable? | How |
+|--------|------------|-----|
+| [From spec] | Yes / No | [What's in place — analytics, logging, etc.] |
+
+## Recommendations
+
+### Critical (block launch)
+1. [Missing must-have feature or unmet critical criterion]
+
+### Important (address soon)
+1. [Partially implemented feature that needs completion]
+
+### Nice to Have (backlog)
+1. [Minor gaps or improvements]
+
+### Process Observations
+- [Any patterns noticed — e.g., "spec was too vague on X, leading to implementation ambiguity"]
+- [Suggestions for improving the spec → build → audit cycle]
+```

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`.