productkit 1.7.0 → 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,8 @@ Slash-command-driven product thinking toolkit for [Claude Code](https://claude.c
 
 Product Kit gives PMs a structured workflow for validating product ideas — user personas, problem statements, assumptions mapping — all through guided AI conversations.
 
+**[Read the full guide →](https://iamquechua.github.io/product-kit/)**
+
 ## Prerequisites
 
 - **Node.js** 18 or later
@@ -43,6 +45,19 @@ cd my-project
 
 This scaffolds a project with slash commands, a `CLAUDE.md` context file, and a `.productkit/` config directory.
 
+For existing projects:
+
+```bash
+cd my-existing-project
+productkit init --existing
+```
+
+To keep artifacts out of the project root (recommended for busy codebases):
+
+```bash
+productkit init --existing --artifact-dir docs/product
+```
+
 ### 2. Open Claude Code
 
 ```bash
@@ -64,12 +79,13 @@ Each command starts a guided conversation. Claude asks questions, pushes back on
 | 7 | `/productkit.spec` | Generate a complete product spec | `spec.md` |
 | — | `/productkit.clarify` | Resolve ambiguities and contradictions across artifacts | Updates existing files |
 | — | `/productkit.analyze` | Run a consistency and completeness check | Analysis in chat |
+| — | `/productkit.bootstrap` | Auto-draft all artifacts from existing codebase | All missing artifacts |
 
 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.
 
 ### 4. Review your artifacts
 
-After running the commands, your project root contains:
+After running the commands, your project contains:
 
 ```
 my-project/
@@ -87,6 +103,8 @@ my-project/
 └── .gitignore
 ```
 
+If you used `--artifact-dir docs/product`, artifacts live in `docs/product/` instead of the project root.
+
 These markdown files are your product foundation — share them with your team, commit them to git, or hand `spec.md` to engineering.
 
 ## CLI Commands
@@ -95,13 +113,30 @@ 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 --artifact-dir <dir>` | Store artifacts in a custom directory |
 | `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 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) |
 | `productkit update` | Refresh slash commands to the latest version |
 | `productkit reset` | Remove all artifacts and start over |
 | `productkit list` | Show available slash commands with descriptions |
 | `productkit completion` | Output shell completion script (bash/zsh) |
 | `productkit check` | Verify Claude Code is installed |
 
+## Cowork Plugin (No CLI Required)
+
+If you prefer Claude Cowork over the command line, Product Kit is also available as a Cowork plugin. Same guided workflows, no terminal needed.
+
+1. Download [`product-kit-plugin.zip`](https://github.com/iamquechua/product-kit/releases/download/latest-plugin/product-kit-plugin.zip) from [GitHub Releases](https://github.com/iamquechua/product-kit/releases/tag/latest-plugin)
+2. In Cowork, go to **Plugins → + → Upload plugin**
+3. Select the zip file
+
+Once installed, type `/product-kit:users`, `/product-kit:problem`, etc. in Cowork's chat. See [plugin/README.md](plugin/README.md) for details.
+
 ## How It Works
 
 Product Kit is a thin scaffolding tool. The real work happens in slash commands — markdown prompt files that live in `.claude/commands/`. When you type `/productkit.users` in Claude Code, it reads the prompt file and starts a guided conversation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "productkit",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Slash-command-driven product thinking toolkit for Claude Code",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -9,18 +9,23 @@ const updateCommand = require('./commands/update');
 const resetCommand = require('./commands/reset');
 const listCommand = require('./commands/list');
 const completionCommand = require('./commands/completion');
+const exportCommand = require('./commands/export');
+const diffCommand = require('./commands/diff');
+const doctorCommand = require('./commands/doctor');
 
 const program = new Command();
 
 program
   .name('productkit')
   .description(chalk.cyan.bold('Product thinking toolkit for Claude Code'))
-  .version('1.7.0');
+  .version('1.8.0');
 
 program
   .command('init [projectName]')
   .description('Initialize a new product research project')
   .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)')
   .action(initCommand);
 
 program
@@ -55,6 +60,23 @@ program
   .option('--shell <shell>', 'Shell type (bash or zsh)')
   .action(completionCommand);
 
+program
+  .command('export')
+  .description('Export all artifacts as a single combined markdown file')
+  .option('--output <file>', 'Output filename', 'export.md')
+  .action(exportCommand);
+
+program
+  .command('diff')
+  .description('Show what changed since last commit across artifacts')
+  .option('--staged', 'Show staged changes instead of unstaged')
+  .action(diffCommand);
+
+program
+  .command('doctor')
+  .description('Check project health (missing files, outdated commands, etc.)')
+  .action(doctorCommand);
+
 program.parse(process.argv);
 
 if (process.argv.length === 2) {

package/src/commands/diff.js

@@ -0,0 +1,68 @@
+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',
+  'solution.md',
+  'priorities.md',
+  'spec.md',
+];
+
+async function diff(options) {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  // Check if git is available
+  try {
+    execSync('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);
+  }
+
+  const artifactDir = getArtifactDir(root);
+  const relDir = path.relative(root, artifactDir);
+  const existing = ARTIFACT_FILES
+    .map(f => relDir && relDir !== '.' ? path.join(relDir, f) : f)
+    .filter(f => fs.existsSync(path.join(root, f)));
+
+  if (existing.length === 0) {
+    console.error(chalk.red('No artifacts found. Run some slash commands first.'));
+    process.exit(1);
+  }
+
+  const gitArgs = options.staged ? ['diff', '--cached'] : ['diff'];
+  const cmd = ['git', ...gitArgs, '--', ...existing].join(' ');
+
+  let output;
+  try {
+    output = execSync(cmd, { cwd: root, encoding: 'utf-8' });
+  } catch (err) {
+    // git diff returns exit code 1 when there are differences in some configs
+    output = err.stdout || '';
+  }
+
+  if (!output) {
+    console.log(chalk.yellow('No changes to artifacts since last commit.'));
+    if (!options.staged) {
+      console.log(chalk.dim('Tip: use --staged to see staged changes.'));
+    }
+    return;
+  }
+
+  console.log(output);
+}
+
+module.exports = diff;

package/src/commands/doctor.js

@@ -0,0 +1,115 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+async function doctor() {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  const results = { pass: 0, warn: 0, fail: 0 };
+
+  function pass(msg) { results.pass++; console.log(chalk.green(`  pass  ${msg}`)); }
+  function warn(msg) { results.warn++; console.log(chalk.yellow(`  warn  ${msg}`)); }
+  function fail(msg) { results.fail++; console.log(chalk.red(`  fail  ${msg}`)); }
+
+  console.log();
+  console.log(chalk.bold('Project health check'));
+  console.log();
+
+  // 1. Config file
+  try {
+    const config = fs.readJsonSync(configPath);
+    if (config.version) {
+      pass('Config file is valid');
+    } else {
+      warn('Config file missing version field');
+    }
+  } catch {
+    fail('Config file is not valid JSON');
+  }
+
+  // 2. Commands directory
+  const commandsDir = path.join(root, '.claude', 'commands');
+  if (fs.existsSync(commandsDir)) {
+    pass('Commands directory exists');
+  } else {
+    fail('Commands directory missing (.claude/commands/)');
+  }
+
+  // 3. Check for expected command templates
+  const templatesDir = path.join(__dirname, '..', '..', 'templates', 'commands');
+  const expectedCommands = fs.readdirSync(templatesDir);
+
+  // Account for minimal mode
+  let config = {};
+  try { config = fs.readJsonSync(configPath); } catch {}
+  const skippable = config.minimal ? ['productkit.constitution.md'] : [];
+
+  const missing = [];
+  for (const cmd of expectedCommands) {
+    if (skippable.includes(cmd)) continue;
+    if (!fs.existsSync(path.join(commandsDir, cmd))) {
+      missing.push(cmd);
+    }
+  }
+
+  if (missing.length === 0) {
+    pass('All expected command templates present');
+  } else {
+    for (const m of missing) {
+      fail(`Missing command template: ${m}`);
+    }
+  }
+
+  // 4. Check for outdated commands
+  const outdated = [];
+  for (const cmd of expectedCommands) {
+    if (skippable.includes(cmd)) continue;
+    const installedPath = path.join(commandsDir, cmd);
+    if (!fs.existsSync(installedPath)) continue;
+
+    const installed = fs.readFileSync(installedPath, 'utf-8');
+    const bundled = fs.readFileSync(path.join(templatesDir, cmd), 'utf-8');
+    if (installed !== bundled) {
+      outdated.push(cmd);
+    }
+  }
+
+  if (outdated.length === 0) {
+    pass('All command templates up to date');
+  } else {
+    for (const o of outdated) {
+      warn(`Outdated command: ${o} — run productkit update`);
+    }
+  }
+
+  // 5. Git initialized
+  try {
+    execSync('git rev-parse --git-dir', { cwd: root, stdio: 'ignore' });
+    pass('Git repository initialized');
+  } catch {
+    warn('No git repository — consider running git init');
+  }
+
+  // Summary
+  console.log();
+  const parts = [];
+  if (results.pass > 0) parts.push(chalk.green(`${results.pass} passed`));
+  if (results.warn > 0) parts.push(chalk.yellow(`${results.warn} warning(s)`));
+  if (results.fail > 0) parts.push(chalk.red(`${results.fail} failed`));
+  console.log(chalk.bold('Result: ') + parts.join(', '));
+  console.log();
+
+  if (results.fail > 0) {
+    process.exit(1);
+  }
+}
+
+module.exports = doctor;

package/src/commands/export.js

@@ -0,0 +1,50 @@
+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: 'solution.md', label: 'Solution' },
+  { file: 'priorities.md', label: 'Priorities' },
+  { file: 'spec.md', label: 'Spec' },
+];
+
+async function exportCommand(options) {
+  const root = process.cwd();
+  const configPath = path.join(root, '.productkit', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.error(chalk.red('Not a Product Kit project.'));
+    console.log('Run: productkit init <name>');
+    process.exit(1);
+  }
+
+  const artifactDir = getArtifactDir(root);
+  const existing = ARTIFACTS.filter(a => fs.existsSync(path.join(artifactDir, a.file)));
+
+  if (existing.length === 0) {
+    console.error(chalk.red('No artifacts found. Run some slash commands first.'));
+    process.exit(1);
+  }
+
+  const sections = [];
+  for (const artifact of existing) {
+    const content = fs.readFileSync(path.join(artifactDir, artifact.file), 'utf-8');
+    sections.push(content);
+  }
+
+  const projectName = path.basename(root);
+  const header = `# ${projectName} — Product Kit Export\n\n_Exported: ${new Date().toISOString().split('T')[0]}_\n\n---\n`;
+  const combined = header + sections.join('\n\n---\n\n') + '\n';
+
+  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}`));
+}
+
+module.exports = exportCommand;

package/src/commands/init.js

@@ -2,7 +2,7 @@ const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
 
-function scaffold(projectRoot, projectName) {
+function scaffold(projectRoot, projectName, minimal, artifactDir) {
   const templatesDir = path.join(__dirname, '..', '..', 'templates');
 
   // Create directories
@@ -10,15 +10,24 @@ function scaffold(projectRoot, projectName) {
   fs.ensureDirSync(path.join(projectRoot, '.claude', 'commands'));
 
   // Write config
-  fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), {
+  const config = {
     version: '1.0.0',
     created: new Date().toISOString(),
-  }, { spaces: 2 });
+  };
+  if (minimal) {
+    config.minimal = true;
+  }
+  if (artifactDir) {
+    config.artifact_dir = artifactDir;
+    fs.ensureDirSync(path.join(projectRoot, artifactDir));
+  }
+  fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), config, { spaces: 2 });
 
   // Copy slash command templates
   const commandsDir = path.join(templatesDir, 'commands');
   const commandFiles = fs.readdirSync(commandsDir);
   for (const file of commandFiles) {
+    if (minimal && file === 'productkit.constitution.md') continue;
     fs.copyFileSync(
       path.join(commandsDir, file),
       path.join(projectRoot, '.claude', 'commands', file)
@@ -61,13 +70,13 @@ async function init(projectName, options) {
     }
 
     try {
-      scaffold(projectRoot, path.basename(projectRoot));
+      scaffold(projectRoot, path.basename(projectRoot), options.minimal, options.artifactDir);
 
       console.log(chalk.green.bold('Product Kit added to existing project!'));
       console.log();
       console.log(chalk.cyan('Next steps:'));
       console.log('  1. claude');
-      console.log('  2. /productkit.constitution');
+      console.log(`  2. /productkit.${options.minimal ? 'users' : 'constitution'}`);
       console.log();
     } catch (error) {
       console.error(chalk.red('Error initializing:'), error.message);
@@ -89,7 +98,7 @@ async function init(projectName, options) {
   }
 
   try {
-    scaffold(projectRoot, projectName);
+    scaffold(projectRoot, projectName, options.minimal, options.artifactDir);
 
     // Init git repo
     const { execSync } = require('child_process');
@@ -104,7 +113,7 @@ async function init(projectName, options) {
     console.log(chalk.cyan('Next steps:'));
     console.log(`  1. cd ${projectName}`);
     console.log('  2. claude');
-    console.log('  3. /productkit.constitution');
+    console.log(`  3. /productkit.${options.minimal ? 'users' : 'constitution'}`);
     console.log();
   } catch (error) {
     console.error(chalk.red('Error initializing project:'), error.message);

package/src/commands/reset.js

@@ -2,6 +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',
@@ -36,9 +37,11 @@ async function reset(options) {
     process.exit(1);
   }
 
+  const artifactDir = getArtifactDir(root);
+
   // Find existing artifacts
   const existing = ARTIFACTS.filter(file =>
-    fs.existsSync(path.join(root, file))
+    fs.existsSync(path.join(artifactDir, file))
   );
 
   if (existing.length === 0) {
@@ -67,7 +70,7 @@ async function reset(options) {
   }
 
   for (const file of existing) {
-    fs.removeSync(path.join(root, file));
+    fs.removeSync(path.join(artifactDir, file));
     console.log(chalk.yellow(`  removed ${file}`));
   }
 

package/src/commands/status.js

@@ -1,6 +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' },
@@ -22,11 +23,12 @@ async function status() {
     process.exit(1);
   }
 
+  const artifactDir = getArtifactDir(root);
   const done = [];
   const remaining = [];
 
   for (const artifact of ARTIFACTS) {
-    const exists = fs.existsSync(path.join(root, artifact.file));
+    const exists = fs.existsSync(path.join(artifactDir, artifact.file));
     if (exists) {
       done.push(artifact);
     } else {

package/src/utils/fileUtils.js

@@ -12,7 +12,19 @@ function getProjectRoot() {
   return null;
 }
 
+function getArtifactDir(root) {
+  const configPath = path.join(root, '.productkit', 'config.json');
+  try {
+    const config = fs.readJsonSync(configPath);
+    if (config.artifact_dir) {
+      return path.join(root, config.artifact_dir);
+    }
+  } catch {}
+  return root;
+}
+
 module.exports = {
   isProductKitProject,
   getProjectRoot,
+  getArtifactDir,
 };

package/templates/CLAUDE.md

@@ -15,10 +15,11 @@ Use these commands in order to build your product foundation:
 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
 
 ## Artifacts
 
-Product artifacts are written to the project root as markdown files:
+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:
 - `constitution.md` — Product principles and values
 - `users.md` — Target user personas
 - `problem.md` — Problem statement
@@ -30,3 +31,5 @@ Product artifacts are written to the project root as markdown files:
 ## Workflow
 
 Start with `/productkit.constitution` or `/productkit.users`, then 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.

package/templates/README.md

@@ -1,6 +1,6 @@
 # {{PROJECT_NAME}}
 
-A product research project powered by [Product Kit](https://github.com/douno/product-kit).
+A product research project powered by [Product Kit](https://github.com/iamquechua/product-kit). See the [full guide](https://iamquechua.github.io/product-kit/) for a walkthrough.
 
 ## Getting Started
 
@@ -19,9 +19,12 @@ Then use the slash commands to build your product foundation:
 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
 
 ## Artifacts
 
+Artifacts are written to the project root by default. If `artifact_dir` is set in `.productkit/config.json`, they are written there instead.
+
 | File | Description |
 |------|-------------|
 | `constitution.md` | Product principles and values |

package/templates/commands/productkit.analyze.md

@@ -10,7 +10,9 @@ Evaluate the overall quality, consistency, and completeness of the product think
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+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:
 - `constitution.md`
 - `users.md`
 - `problem.md`

package/templates/commands/productkit.assumptions.md

@@ -41,7 +41,9 @@ Also read if they exist:
 
 ## Output
 
-Write to `assumptions.md` in the project root:
+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.
+
+Write to `assumptions.md`:
 
 ```markdown
 # Assumptions

package/templates/commands/productkit.bootstrap.md

@@ -0,0 +1,81 @@
+---
+description: Auto-draft all product artifacts from an existing codebase
+---
+
+You are a product analyst bootstrapping Product Kit artifacts for an existing project. Your job is to read the codebase and draft each artifact so the user gets a fast start instead of building from scratch.
+
+## Your Role
+
+Analyze the existing project — code, docs, README, config files, comments — and draft product artifacts in workflow order. Present each draft for user approval before writing it.
+
+## 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.
+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`.
+
+## Process
+
+Work through each missing artifact in this order:
+
+### 1. Constitution (`constitution.md`)
+Draft based on: README vision/mission, CLAUDE.md principles, project conventions.
+- Product vision — infer from what the project does
+- Core principles — infer from code patterns, docs, and design choices
+- Non-negotiables — infer from what the project explicitly avoids
+
+### 2. Users (`users.md`)
+Draft based on: README audience, docs, issue tracker themes, CLI help text, UI copy.
+- Identify 2-4 user types from project context
+- Describe each with specifics inferred from the codebase
+
+### 3. Problem (`problem.md`)
+Draft based on: README "why", issue patterns, gaps the project fills.
+- Frame the core problem the project solves
+- Ground it in the users you just defined
+
+### 4. Assumptions (`assumptions.md`)
+Draft based on: implicit bets in the architecture, undocumented dependencies, target audience guesses.
+- Surface 5-10 assumptions from code and docs
+- Categorize by risk (high/medium/low)
+
+### 5. Solution (`solution.md`)
+Draft based on: the actual implementation, architecture choices, alternatives mentioned in docs/comments.
+- Describe the chosen approach and why
+- Note alternatives that were likely considered
+
+### 6. Priorities (`priorities.md`)
+Draft based on: feature completeness, TODO comments, open issues, roadmap docs.
+- List features/capabilities by apparent priority
+- Flag gaps between what exists and what's needed
+
+### 7. Spec (`spec.md`)
+Draft based on: all previous artifacts plus technical implementation details.
+- Synthesize everything into a product spec
+
+## For Each Artifact
+
+1. **Show your draft** — present the full markdown content
+2. **Explain your reasoning** — briefly note what codebase signals you used
+3. **Ask for approval** — "Should I write this to `[filename]`? Or would you like to adjust anything?"
+4. **On approval** — write the file to the artifact directory
+5. **On feedback** — revise and re-present
+
+## Conversation Style
+
+- Be direct — present drafts quickly, don't over-ask before showing something
+- Flag low-confidence sections with "[Needs input]" where the codebase doesn't give enough signal
+- If the codebase has very little documentation, acknowledge gaps honestly and ask the user to fill in
+- After each artifact, move to the next without prompting — keep momentum
+
+## Output
+
+Each artifact follows the same format as its corresponding slash command would produce. Refer to the individual command templates for the expected structure.
+
+## When Done
+
+After all artifacts are written (or skipped), summarize:
+- Which artifacts were drafted and written
+- Which were skipped (already existed)
+- Suggest running `/productkit.clarify` to resolve any cross-artifact inconsistencies

package/templates/commands/productkit.clarify.md

@@ -10,7 +10,9 @@ Cross-reference all existing artifacts, find inconsistencies, and guide the user
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+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:
 - `constitution.md`
 - `users.md`
 - `problem.md`

package/templates/commands/productkit.constitution.md

@@ -25,7 +25,9 @@ Act as a seasoned PM mentor. Guide the user through defining their product's cor
 
 ## Output
 
-Write the final constitution to `constitution.md` in the project root with this format:
+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.
+
+Write the final constitution to `constitution.md` with this format:
 
 ```markdown
 # Product Constitution

package/templates/commands/productkit.prioritize.md

@@ -42,7 +42,9 @@ If `solution.md` does not exist, tell the user to run `/productkit.solution` fir
 
 ## Output
 
-Write to `priorities.md` in the project root:
+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.
+
+Write to `priorities.md`:
 
 ```markdown
 # Feature Priorities

package/templates/commands/productkit.problem.md

@@ -34,7 +34,9 @@ If `users.md` does not exist, tell the user to run `/productkit.users` first.
 
 ## Output
 
-Write the problem statement to `problem.md` in the project root:
+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.
+
+Write the problem statement to `problem.md`:
 
 ```markdown
 # Problem Statement

package/templates/commands/productkit.solution.md

@@ -44,7 +44,9 @@ If `users.md` or `problem.md` do not exist, tell the user to run `/productkit.us
 
 ## Output
 
-Write to `solution.md` in the project root:
+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.
+
+Write to `solution.md`:
 
 ```markdown
 # Solution

package/templates/commands/productkit.spec.md

@@ -10,7 +10,9 @@ Pull together everything the user has built — constitution, users, problem, as
 
 ## Before You Start
 
-Read all existing artifacts in the project root:
+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:
 - `constitution.md` — product principles
 - `users.md` — target users (required)
 - `problem.md` — problem statement (required)
@@ -37,7 +39,7 @@ At minimum, `users.md`, `problem.md`, and `solution.md` must exist. If any are m
 
 ## Output
 
-Write to `spec.md` in the project root:
+Write to `spec.md`:
 
 ```markdown
 # Product Spec: [Product Name]

package/templates/commands/productkit.users.md

@@ -33,7 +33,9 @@ Read `constitution.md` if it exists — use the product vision to inform user di
 
 ## Output
 
-Write the final personas to `users.md` in the project root with this format:
+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.
+
+Write the final personas to `users.md` with this format:
 
 ```markdown
 # Target Users