productkit 1.9.0 → 1.10.0

package/README.md

@@ -43,7 +43,7 @@ productkit init my-project
 cd my-project
 ```
 
-This scaffolds a project with slash commands, a `CLAUDE.md` context file, and a `.productkit/` config directory.
+This scaffolds a project with slash commands, a `CLAUDE.md` context file, a `knowledge/` directory for research files, and a `.productkit/` config directory.
 
 For existing projects:
 
@@ -58,6 +58,17 @@ To keep artifacts out of the project root (recommended for busy codebases):
 productkit init --existing --artifact-dir docs/product
 ```
 
+To create a shared workspace for multi-project orgs:
+
+```bash
+productkit workspace my-company
+cd my-company
+productkit init my-app
+productkit init admin-dashboard
+```
+
+The workspace holds shared `landscape.md` and `knowledge/` that all projects inside it inherit automatically. `init` auto-detects when it's run inside a workspace.
+
 ### 2. Open Claude Code
 
 ```bash
@@ -70,6 +81,7 @@ Each command starts a guided conversation. Claude asks questions, pushes back on
 
 | Step | Command | What it does | Output |
 |------|---------|-------------|--------|
+| 0 | `/productkit.landscape` | Capture company, team, and domain landscape | `landscape.md` |
 | 1 | `/productkit.constitution` | Define product principles and values | `constitution.md` |
 | 2 | `/productkit.users` | Define target user personas through dialogue | `users.md` |
 | 3 | `/productkit.problem` | Frame the problem statement grounded in user research | `problem.md` |
@@ -82,8 +94,11 @@ Each command starts a guided conversation. Claude asks questions, pushes back on
 | — | `/productkit.analyze` | Run a consistency and completeness check | Analysis in chat |
 | — | `/productkit.bootstrap` | Auto-draft all artifacts from existing codebase | All missing artifacts |
 | — | `/productkit.audit` | Compare spec against codebase, surface gaps | `audit.md` |
+| — | `/productkit.learn` | Index knowledge directory into a compact summary | `knowledge-index.md` |
+| — | `/productkit.techreview` | Review spec against codebase, flag engineering questions | `techreview.md` |
+| — | `/productkit.stories` | Break spec into user stories with acceptance criteria | `stories.md` |
 
-Commands build on each other — `/productkit.problem` reads your `users.md`, `/productkit.solution` reads your problem and users, and `/productkit.spec` synthesizes everything into a single document. You can run `/productkit.clarify` and `/productkit.analyze` at any stage to check your work.
+Commands build on each other — every command reads `landscape.md` and `knowledge-index.md` for evidence, `/productkit.problem` reads your `users.md`, `/productkit.solution` reads your problem and users, and `/productkit.spec` synthesizes everything into a single document. You can run `/productkit.clarify` and `/productkit.analyze` at any stage to check your work.
 
 ### 4. Review your artifacts
 
@@ -91,6 +106,7 @@ After running the commands, your project contains:
 
 ```
 my-project/
+├── landscape.md             # Company & domain landscape
 ├── constitution.md        # Product principles
 ├── users.md               # User personas
 ├── problem.md             # Problem statement
@@ -100,6 +116,10 @@ my-project/
 ├── priorities.md          # Ranked feature list
 ├── spec.md                # Complete product spec
 ├── audit.md               # Spec vs codebase audit (on demand)
+├── knowledge-index.md     # Summary index of knowledge/ files
+├── knowledge/             # Raw research files (interviews, surveys, etc.)
+├── techreview.md          # Technical feasibility review (on demand)
+├── stories.md             # User stories by epic (on demand)
 ├── .productkit/config.json
 ├── .claude/commands/      # Slash command prompts
 ├── CLAUDE.md
@@ -118,10 +138,13 @@ These markdown files are your product foundation — share them with your team,
 | `productkit init <name>` | Scaffold a new project |
 | `productkit init --existing` | Add Product Kit to the current directory |
 | `productkit init --minimal` | Skip constitution, start with users/problem |
+| `productkit init --mode <solo\|team>` | Set building mode (solo builder vs team with engineers) |
 | `productkit init --artifact-dir <dir>` | Store artifacts in a custom directory |
+| `productkit workspace <name>` | Create a shared workspace for multi-project orgs |
 | `productkit status` | Show progress — which artifacts exist and what's next |
 | `productkit export` | Export all artifacts as a single combined markdown file |
 | `productkit export --output <file>` | Export to a custom filename |
+| `productkit export --stories-csv` | Export stories as CSV for Jira/Linear/Shortcut import |
 | `productkit diff` | Show what changed in artifacts since last commit |
 | `productkit diff --staged` | Show staged artifact changes |
 | `productkit doctor` | Check project health (missing files, outdated commands) |

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "productkit",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "Slash-command-driven product thinking toolkit for Claude Code",
   "main": "src/cli.js",
   "bin": {
-    "productkit": "./src/cli.js"
+    "productkit": "src/cli.js"
   },
   "scripts": {
     "test": "node --test test/*.test.js"
@@ -22,12 +22,15 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/iamquechua/product-kit.git"
+    "url": "git+https://github.com/iamquechua/product-kit.git"
   },
   "homepage": "https://github.com/iamquechua/product-kit#readme",
   "bugs": {
     "url": "https://github.com/iamquechua/product-kit/issues"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "author": "Douno",
   "license": "MIT",
   "dependencies": {

package/src/cli.js

@@ -12,13 +12,15 @@ const completionCommand = require('./commands/completion');
 const exportCommand = require('./commands/export');
 const diffCommand = require('./commands/diff');
 const doctorCommand = require('./commands/doctor');
+const workspaceCommand = require('./commands/workspace');
 
+const { version } = require('../package.json');
 const program = new Command();
 
 program
   .name('productkit')
   .description(chalk.cyan.bold('Product thinking toolkit for Claude Code'))
-  .version('1.9.0');
+  .version(version);
 
 program
   .command('init [projectName]')
@@ -26,6 +28,7 @@ program
   .option('--existing', 'Add Product Kit to the current directory')
   .option('--minimal', 'Skip constitution, start with users/problem')
   .option('--artifact-dir <dir>', 'Directory for artifacts (default: project root)')
+  .option('--mode <mode>', 'Building mode: solo or team')
   .action(initCommand);
 
 program
@@ -64,6 +67,7 @@ program
   .command('export')
   .description('Export all artifacts as a single combined markdown file')
   .option('--output <file>', 'Output filename', 'export.md')
+  .option('--stories-csv', 'Export stories as CSV for Jira/Linear import')
   .action(exportCommand);
 
 program
@@ -77,6 +81,11 @@ program
   .description('Check project health (missing files, outdated commands, etc.)')
   .action(doctorCommand);
 
+program
+  .command('workspace <name>')
+  .description('Create a shared workspace for multi-project orgs')
+  .action(workspaceCommand);
+
 program.parse(process.argv);
 
 if (process.argv.length === 2) {

package/src/commands/check.js

@@ -1,9 +1,9 @@
 const chalk = require('chalk');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 async function check() {
   try {
-    execSync('claude --version', { stdio: 'ignore' });
+    execFileSync('claude', ['--version'], { stdio: 'ignore' });
     console.log(chalk.green('Claude Code is installed and available.'));
   } catch {
     console.log(chalk.red('Claude Code is not installed or not in PATH.'));

package/src/commands/completion.js

@@ -8,10 +8,14 @@ _productkit() {
     'init:Initialize a new product research project'
     'check:Verify Claude Code is installed and available'
     'status:Show which artifacts exist and what steps remain'
+    'export:Export all artifacts as a single combined markdown file'
+    'diff:Show what changed in artifacts since last commit'
+    'doctor:Check project health'
     'update:Refresh slash commands to the latest version'
     'reset:Remove all artifacts and start over'
     'list:Show available slash commands with descriptions'
     'completion:Output shell completion script'
+    'workspace:Create a shared workspace for multi-project orgs'
   )
 
   _arguments -C \\
@@ -27,8 +31,20 @@ _productkit() {
         init)
           _arguments \\
             '--existing[Add Product Kit to the current directory]' \\
+            '--minimal[Skip constitution]' \\
+            '--mode[Building mode (solo or team)]:mode:(solo team)' \\
+            '--artifact-dir[Store artifacts in a custom directory]:dir:_files -/' \\
             '1:project name:_files -/'
           ;;
+        export)
+          _arguments \\
+            '--output[Output filename]:file:_files' \\
+            '--stories-csv[Export stories as CSV for Jira/Linear import]'
+          ;;
+        diff)
+          _arguments \\
+            '--staged[Show staged changes instead of unstaged]'
+          ;;
         reset)
           _arguments \\
             '--force[Skip confirmation prompt]'
@@ -45,7 +61,7 @@ const BASH_COMPLETION = `_productkit() {
   COMPREPLY=()
   cur="\${COMP_WORDS[COMP_CWORD]}"
   prev="\${COMP_WORDS[COMP_CWORD-1]}"
-  commands="init check status update reset list completion"
+  commands="init check status export diff doctor update reset list completion workspace"
 
   case "\${prev}" in
     productkit)
@@ -53,7 +69,15 @@ const BASH_COMPLETION = `_productkit() {
       return 0
       ;;
     init)
-      COMPREPLY=( $(compgen -W "--existing" -- "\${cur}") )
+      COMPREPLY=( $(compgen -W "--existing --minimal --mode --artifact-dir" -- "\${cur}") )
+      return 0
+      ;;
+    export)
+      COMPREPLY=( $(compgen -W "--output --stories-csv" -- "\${cur}") )
+      return 0
+      ;;
+    diff)
+      COMPREPLY=( $(compgen -W "--staged" -- "\${cur}") )
       return 0
       ;;
     reset)

package/src/commands/diff.js

@@ -1,19 +1,8 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { execSync } = require('child_process');
-const { getArtifactDir } = require('../utils/fileUtils');
-
-const ARTIFACT_FILES = [
-  'constitution.md',
-  'users.md',
-  'problem.md',
-  'assumptions.md',
-  'validation.md',
-  'solution.md',
-  'priorities.md',
-  'spec.md',
-];
+const { execFileSync } = require('child_process');
+const { getArtifactDir, ARTIFACT_FILES } = require('../utils/fileUtils');
 
 async function diff(options) {
   const root = process.cwd();
@@ -27,7 +16,7 @@ async function diff(options) {
 
   // Check if git is available
   try {
-    execSync('git rev-parse --git-dir', { cwd: root, stdio: 'ignore' });
+    execFileSync('git', ['rev-parse', '--git-dir'], { cwd: root, stdio: 'ignore' });
   } catch {
     console.error(chalk.red('Not a git repository. The diff command requires git.'));
     process.exit(1);
@@ -45,11 +34,10 @@ async function diff(options) {
   }
 
   const gitArgs = options.staged ? ['diff', '--cached'] : ['diff'];
-  const cmd = ['git', ...gitArgs, '--', ...existing].join(' ');
 
   let output;
   try {
-    output = execSync(cmd, { cwd: root, encoding: 'utf-8' });
+    output = execFileSync('git', [...gitArgs, '--', ...existing], { cwd: root, encoding: 'utf-8' });
   } catch (err) {
     // git diff returns exit code 1 when there are differences in some configs
     output = err.stdout || '';

package/src/commands/doctor.js

@@ -1,7 +1,7 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { execSync } = require('child_process');
+const { execFileSync } = require('child_process');
 
 async function doctor() {
   const root = process.cwd();
@@ -45,12 +45,20 @@ async function doctor() {
 
   // 3. Check for expected command templates
   const templatesDir = path.join(__dirname, '..', '..', 'templates', 'commands');
-  const expectedCommands = fs.readdirSync(templatesDir);
+  let expectedCommands;
+  try {
+    expectedCommands = fs.readdirSync(templatesDir);
+  } catch {
+    fail('Templates directory missing — Product Kit installation may be corrupted');
+    expectedCommands = [];
+  }
 
   // Account for minimal mode
   let config = {};
   try { config = fs.readJsonSync(configPath); } catch {}
-  const skippable = config.minimal ? ['productkit.constitution.md'] : [];
+  // Landscape is workspace-only; constitution is skipped in minimal mode
+  const skippable = ['productkit.landscape.md'];
+  if (config.minimal) skippable.push('productkit.constitution.md');
 
   const missing = [];
   for (const cmd of expectedCommands) {
@@ -92,7 +100,7 @@ async function doctor() {
 
   // 5. Git initialized
   try {
-    execSync('git rev-parse --git-dir', { cwd: root, stdio: 'ignore' });
+    execFileSync('git', ['rev-parse', '--git-dir'], { cwd: root, stdio: 'ignore' });
     pass('Git repository initialized');
   } catch {
     warn('No git repository — consider running git init');

package/src/commands/export.js

@@ -1,18 +1,148 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
-const { getArtifactDir } = require('../utils/fileUtils');
-
-const ARTIFACTS = [
-  { file: 'constitution.md', label: 'Constitution' },
-  { file: 'users.md', label: 'Users' },
-  { file: 'problem.md', label: 'Problem' },
-  { file: 'assumptions.md', label: 'Assumptions' },
-  { file: 'validation.md', label: 'Validation' },
-  { file: 'solution.md', label: 'Solution' },
-  { file: 'priorities.md', label: 'Priorities' },
-  { file: 'spec.md', label: 'Spec' },
-];
+const { getArtifactDir, getWorkspaceRoot, ARTIFACTS } = require('../utils/fileUtils');
+
+function escapeCsvField(field) {
+  if (field == null) return '';
+  const str = String(field);
+  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+    return '"' + str.replace(/"/g, '""') + '"';
+  }
+  return str;
+}
+
+function parseStoriesCsv(content) {
+  const lines = content.split('\n');
+  // Detect mode from document headers produced by /productkit.stories
+  const isTeamMode = lines.some(l => l.trim() === '# User Stories');
+
+  if (isTeamMode) {
+    return parseTeamMode(lines);
+  }
+  return parseSoloMode(lines);
+}
+
+function parseTeamMode(lines) {
+  const headers = ['ID', 'Title', 'Epic', 'Priority', 'Estimate', 'Depends On', 'Acceptance Criteria', 'Definition of Done', 'Notes'];
+  const rows = [];
+  let currentEpic = '';
+  let currentRow = null;
+  let collectingAC = false;
+
+  for (const line of lines) {
+    const epicMatch = line.match(/^## Epic \d+:\s*(.+)/);
+    if (epicMatch) {
+      if (currentRow) rows.push(currentRow);
+      currentEpic = epicMatch[1].trim();
+      currentRow = null;
+      collectingAC = false;
+      continue;
+    }
+
+    const storyMatch = line.match(/^### (E\d+-S\d+):\s*(.*)/);
+    if (storyMatch) {
+      if (currentRow) rows.push(currentRow);
+      collectingAC = false;
+      currentRow = { ID: storyMatch[1], Title: storyMatch[2].trim(), Epic: currentEpic, Priority: '', Estimate: '', 'Depends On': '', 'Acceptance Criteria': [], 'Definition of Done': '', Notes: '' };
+      continue;
+    }
+
+    if (!currentRow) continue;
+
+    if (collectingAC) {
+      const checkMatch = line.match(/^\s*- \[[ x]\]\s*(.+)/);
+      if (checkMatch) {
+        currentRow['Acceptance Criteria'].push(checkMatch[1].trim());
+        continue;
+      }
+      collectingAC = false;
+    }
+
+    const titleMatch = line.match(/^- \*\*Title:\*\*\s*(.+)/);
+    if (titleMatch) { currentRow.Title = titleMatch[1].trim(); continue; }
+
+    const prioMatch = line.match(/^- \*\*Priority:\*\*\s*(.+)/);
+    if (prioMatch) { currentRow.Priority = prioMatch[1].trim(); continue; }
+
+    const estMatch = line.match(/^- \*\*Estimate:\*\*\s*(.+)/);
+    if (estMatch) { currentRow.Estimate = estMatch[1].trim(); continue; }
+
+    const depMatch = line.match(/^- \*\*Depends on:\*\*\s*(.+)/);
+    if (depMatch) { currentRow['Depends On'] = depMatch[1].trim(); continue; }
+
+    if (line.match(/^- \*\*Acceptance Criteria:\*\*/)) {
+      collectingAC = true;
+      continue;
+    }
+
+    const dodMatch = line.match(/^- \*\*Definition of Done:\*\*\s*(.+)/);
+    if (dodMatch) { currentRow['Definition of Done'] = dodMatch[1].trim(); continue; }
+
+    const notesMatch = line.match(/^- \*\*Notes:\*\*\s*(.+)/);
+    if (notesMatch) { currentRow.Notes = notesMatch[1].trim(); continue; }
+  }
+
+  if (currentRow) rows.push(currentRow);
+
+  const csvRows = rows.map(r => {
+    const ac = Array.isArray(r['Acceptance Criteria']) ? r['Acceptance Criteria'].join('; ') : r['Acceptance Criteria'];
+    return headers.map(h => escapeCsvField(h === 'Acceptance Criteria' ? ac : r[h])).join(',');
+  });
+
+  return [headers.join(','), ...csvRows].join('\n') + '\n';
+}
+
+function parseSoloMode(lines) {
+  const headers = ['ID', 'Task', 'Effort', 'Depends On', 'Done When', 'Watch Out For'];
+  const rows = [];
+  let currentRow = null;
+  let collectingDone = false;
+
+  for (const line of lines) {
+    const taskMatch = line.match(/^### (T\d+):\s*(.*)/);
+    if (taskMatch) {
+      if (currentRow) rows.push(currentRow);
+      collectingDone = false;
+      currentRow = { ID: taskMatch[1], Task: taskMatch[2].trim(), Effort: '', 'Depends On': '', 'Done When': [], 'Watch Out For': '' };
+      continue;
+    }
+
+    if (!currentRow) continue;
+
+    if (collectingDone) {
+      const checkMatch = line.match(/^\s*- \[[ x]\]\s*(.+)/);
+      if (checkMatch) {
+        currentRow['Done When'].push(checkMatch[1].trim());
+        continue;
+      }
+      collectingDone = false;
+    }
+
+    const effortMatch = line.match(/^- \*\*Effort:\*\*\s*(.+)/);
+    if (effortMatch) { currentRow.Effort = effortMatch[1].trim(); continue; }
+
+    const depMatch = line.match(/^- \*\*Depends on:\*\*\s*(.+)/);
+    if (depMatch) { currentRow['Depends On'] = depMatch[1].trim(); continue; }
+
+    if (line.match(/^- \*\*Done when:\*\*/)) {
+      collectingDone = true;
+      continue;
+    }
+
+    const watchMatch = line.match(/^- \*\*Watch out for:\*\*\s*(.+)/);
+    if (watchMatch) { currentRow['Watch Out For'] = watchMatch[1].trim(); continue; }
+  }
+
+  if (currentRow) rows.push(currentRow);
+
+  const csvRows = rows.map(r => {
+    const dw = Array.isArray(r['Done When']) ? r['Done When'].join('; ') : r['Done When'];
+    return headers.map(h => escapeCsvField(h === 'Done When' ? dw : r[h])).join(',');
+  });
+
+  return [headers.join(','), ...csvRows].join('\n') + '\n';
+}
 
 async function exportCommand(options) {
   const root = process.cwd();
@@ -25,14 +155,38 @@ async function exportCommand(options) {
   }
 
   const artifactDir = getArtifactDir(root);
+
+  if (options.storiesCsv) {
+    const storiesPath = path.join(artifactDir, 'stories.md');
+    if (!fs.existsSync(storiesPath)) {
+      console.error(chalk.red('No stories.md found. Run /productkit.stories first.'));
+      process.exit(1);
+    }
+    const content = fs.readFileSync(storiesPath, 'utf-8');
+    const csv = parseStoriesCsv(content);
+    const outputFile = options.output === 'export.md' ? 'stories.csv' : options.output;
+    fs.writeFileSync(path.join(root, outputFile), csv);
+    console.log(chalk.green.bold(`Exported stories to ${outputFile}`));
+    return;
+  }
+
   const existing = ARTIFACTS.filter(a => fs.existsSync(path.join(artifactDir, a.file)));
 
-  if (existing.length === 0) {
+  // Check for workspace landscape
+  const workspaceRoot = getWorkspaceRoot(root);
+  const hasLandscape = workspaceRoot && fs.existsSync(path.join(workspaceRoot, 'landscape.md'));
+
+  if (existing.length === 0 && !hasLandscape) {
     console.error(chalk.red('No artifacts found. Run some slash commands first.'));
     process.exit(1);
   }
 
   const sections = [];
+
+  if (hasLandscape) {
+    sections.push(fs.readFileSync(path.join(workspaceRoot, 'landscape.md'), 'utf-8'));
+  }
+
   for (const artifact of existing) {
     const content = fs.readFileSync(path.join(artifactDir, artifact.file), 'utf-8');
     sections.push(content);
@@ -45,7 +199,8 @@ async function exportCommand(options) {
   const outputFile = options.output || 'export.md';
   fs.writeFileSync(path.join(root, outputFile), combined);
 
-  console.log(chalk.green.bold(`Exported ${existing.length} artifact(s) to ${outputFile}`));
+  const totalCount = existing.length + (hasLandscape ? 1 : 0);
+  console.log(chalk.green.bold(`Exported ${totalCount} artifact(s) to ${outputFile}`));
 }
 
 module.exports = exportCommand;

package/src/commands/init.js

@@ -1,9 +1,29 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const readline = require('readline');
+
+function promptMode() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise((resolve) => {
+    console.log();
+    console.log(chalk.cyan('How are you building this product?'));
+    console.log('  1. Solo — I\'m building it myself');
+    console.log('  2. Team — I\'m working with engineers/designers');
+    console.log();
+    rl.question('Choose (1 or 2): ', (answer) => {
+      rl.close();
+      resolve(answer.trim() === '2' ? 'team' : 'solo');
+    });
+  });
+}
 
-function scaffold(projectRoot, projectName, minimal, artifactDir) {
+function scaffold(projectRoot, projectName, minimal, artifactDir, mode) {
   const templatesDir = path.join(__dirname, '..', '..', 'templates');
+  const pkgVersion = require('../../package.json').version;
 
   // Create directories
   fs.ensureDirSync(path.join(projectRoot, '.productkit'));
@@ -11,9 +31,21 @@ function scaffold(projectRoot, projectName, minimal, artifactDir) {
 
   // Write config
   const config = {
-    version: '1.0.0',
+    version: pkgVersion,
     created: new Date().toISOString(),
   };
+
+  // Detect workspace: check if parent has workspace config
+  const parentDir = path.dirname(projectRoot);
+  const parentConfigPath = path.join(parentDir, '.productkit', 'config.json');
+  try {
+    const parentConfig = fs.readJsonSync(parentConfigPath);
+    if (parentConfig.type === 'workspace') {
+      config.type = 'project';
+      config.workspace = '..';
+    }
+  } catch {}
+
   if (minimal) {
     config.minimal = true;
   }
@@ -21,6 +53,10 @@ function scaffold(projectRoot, projectName, minimal, artifactDir) {
     config.artifact_dir = artifactDir;
     fs.ensureDirSync(path.join(projectRoot, artifactDir));
   }
+  if (mode) {
+    config.mode = mode;
+  }
+  config.knowledge_dir = 'knowledge';
   fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), config, { spaces: 2 });
 
   // Copy slash command templates
@@ -28,6 +64,8 @@ function scaffold(projectRoot, projectName, minimal, artifactDir) {
   const commandFiles = fs.readdirSync(commandsDir);
   for (const file of commandFiles) {
     if (minimal && file === 'productkit.constitution.md') continue;
+    // Landscape lives at workspace level, not project level
+    if (file === 'productkit.landscape.md') continue;
     fs.copyFileSync(
       path.join(commandsDir, file),
       path.join(projectRoot, '.claude', 'commands', file)
@@ -51,6 +89,14 @@ function scaffold(projectRoot, projectName, minimal, artifactDir) {
     fs.writeFileSync(path.join(projectRoot, 'README.md'), readme);
   }
 
+  // Create knowledge directory with README
+  const knowledgeDir = path.join(projectRoot, 'knowledge');
+  fs.ensureDirSync(knowledgeDir);
+  fs.copyFileSync(
+    path.join(templatesDir, 'knowledge-README.md'),
+    path.join(knowledgeDir, 'README.md')
+  );
+
   // Copy .gitignore (only for new projects)
   if (!fs.existsSync(path.join(projectRoot, '.gitignore'))) {
     fs.copyFileSync(
@@ -61,6 +107,20 @@ function scaffold(projectRoot, projectName, minimal, artifactDir) {
 }
 
 async function init(projectName, options) {
+  // Validate and resolve mode
+  let mode = options.mode;
+  if (mode && mode !== 'solo' && mode !== 'team') {
+    console.error(chalk.red('Error: --mode must be "solo" or "team"'));
+    process.exit(1);
+  }
+  if (!mode) {
+    if (process.stdin.isTTY) {
+      mode = await promptMode();
+    } else {
+      mode = 'solo';
+    }
+  }
+
   if (options.existing) {
     const projectRoot = process.cwd();
 
@@ -70,7 +130,7 @@ async function init(projectName, options) {
     }
 
     try {
-      scaffold(projectRoot, path.basename(projectRoot), options.minimal, options.artifactDir);
+      scaffold(projectRoot, path.basename(projectRoot), options.minimal, options.artifactDir, mode);
 
       console.log(chalk.green.bold('Product Kit added to existing project!'));
       console.log();
@@ -98,12 +158,12 @@ async function init(projectName, options) {
   }
 
   try {
-    scaffold(projectRoot, projectName, options.minimal, options.artifactDir);
+    scaffold(projectRoot, projectName, options.minimal, options.artifactDir, mode);
 
     // Init git repo
-    const { execSync } = require('child_process');
+    const { execFileSync } = require('child_process');
     try {
-      execSync('git init', { cwd: projectRoot, stdio: 'ignore' });
+      execFileSync('git', ['init'], { cwd: projectRoot, stdio: 'ignore' });
     } catch {
       // Git not available, skip
     }