productkit 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# Product Kit
+
+Slash-command-driven product thinking toolkit for [Claude Code](https://claude.com/claude-code).
+
+Product Kit gives PMs a structured workflow for validating product ideas — user personas, problem statements, assumptions mapping — all through guided AI conversations.
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- **[Claude Code](https://claude.com/claude-code)** installed and available in your PATH
+
+Verify Claude Code is ready:
+
+```bash
+claude --version
+```
+
+## Setup
+
+### From npm (once published)
+
+```bash
+npm install -g productkit
+```
+
+### From source
+
+```bash
+git clone https://github.com/douno/product-kit.git
+cd product-kit
+npm install
+npm link   # makes `productkit` available globally
+```
+
+## Usage
+
+### 1. Create a project
+
+```bash
+productkit init my-project
+cd my-project
+```
+
+This scaffolds a project with slash commands, a `CLAUDE.md` context file, and a `.productkit/` config directory.
+
+### 2. Open Claude Code
+
+```bash
+claude
+```
+
+### 3. Run the slash commands in order
+
+Each command starts a guided conversation. Claude asks questions, pushes back on vague answers, and writes a markdown artifact when done.
+
+| Step | Command | What it does | Output |
+|------|---------|-------------|--------|
+| 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` |
+| 4 | `/productkit.assumptions` | Extract and prioritize hidden assumptions | `assumptions.md` |
+| 5 | `/productkit.clarify` | Resolve ambiguities and contradictions across artifacts | Updates existing files |
+| 6 | `/productkit.analyze` | Run a consistency and completeness check | Analysis in chat |
+
+Commands build on each other — `/productkit.problem` reads your `users.md` to ground the problem in real user needs. `/productkit.assumptions` reads both `users.md` and `problem.md` to find hidden assumptions. 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:
+
+```
+my-project/
+├── constitution.md        # Product principles
+├── users.md               # User personas
+├── problem.md             # Problem statement
+├── assumptions.md         # Prioritized assumptions
+├── .productkit/config.json
+├── .claude/commands/      # Slash command prompts
+├── CLAUDE.md
+├── README.md
+└── .gitignore
+```
+
+These markdown files are your product foundation — share them with your team, commit them to git, or use them as input for solution design.
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `productkit init <name>` | Scaffold a new project |
+| `productkit check` | Verify Claude Code is installed |
+
+## 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.
+
+Each prompt tells Claude:
+- What role to play (PM coach, research specialist, etc.)
+- What artifacts to read first (enforces workflow ordering)
+- How to guide the conversation (questions to ask, what to push back on)
+- What file to write and in what format
+
+You can customize any slash command by editing the files in `.claude/commands/`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "productkit",
+  "version": "1.0.0",
+  "description": "Slash-command-driven product thinking toolkit for Claude Code",
+  "main": "src/cli.js",
+  "bin": {
+    "productkit": "./src/cli.js"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "files": [
+    "src/",
+    "templates/",
+    "README.md"
+  ],
+  "keywords": [
+    "product-management",
+    "claude-code",
+    "slash-commands",
+    "product-thinking"
+  ],
+  "author": "Douno",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const initCommand = require('./commands/init');
+const checkCommand = require('./commands/check');
+
+const program = new Command();
+
+program
+  .name('productkit')
+  .description(chalk.cyan.bold('Product thinking toolkit for Claude Code'))
+  .version('1.0.0');
+
+program
+  .command('init <projectName>')
+  .description('Initialize a new product research project')
+  .action(initCommand);
+
+program
+  .command('check')
+  .description('Verify Claude Code is installed and available')
+  .action(checkCommand);
+
+program.parse(process.argv);
+
+if (process.argv.length === 2) {
+  program.outputHelp();
+}

package/src/commands/check.js

@@ -0,0 +1,17 @@
+const chalk = require('chalk');
+const { execSync } = require('child_process');
+
+async function check() {
+  try {
+    execSync('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.'));
+    console.log();
+    console.log('Install it:');
+    console.log('  npm install -g @anthropic-ai/claude-code');
+    process.exit(1);
+  }
+}
+
+module.exports = check;

package/src/commands/init.js

@@ -0,0 +1,74 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+async function init(projectName) {
+  const projectRoot = path.join(process.cwd(), projectName);
+
+  if (fs.existsSync(projectRoot)) {
+    console.error(chalk.red(`Error: Directory "${projectName}" already exists`));
+    process.exit(1);
+  }
+
+  try {
+    const templatesDir = path.join(__dirname, '..', '..', 'templates');
+
+    // Create directories
+    fs.ensureDirSync(path.join(projectRoot, '.productkit'));
+    fs.ensureDirSync(path.join(projectRoot, '.claude', 'commands'));
+
+    // Write config
+    fs.writeJsonSync(path.join(projectRoot, '.productkit', 'config.json'), {
+      version: '1.0.0',
+      created: new Date().toISOString(),
+    }, { spaces: 2 });
+
+    // Copy slash command templates
+    const commandsDir = path.join(templatesDir, 'commands');
+    const commandFiles = fs.readdirSync(commandsDir);
+    for (const file of commandFiles) {
+      fs.copyFileSync(
+        path.join(commandsDir, file),
+        path.join(projectRoot, '.claude', 'commands', file)
+      );
+    }
+
+    // Copy CLAUDE.md
+    fs.copyFileSync(
+      path.join(templatesDir, 'CLAUDE.md'),
+      path.join(projectRoot, 'CLAUDE.md')
+    );
+
+    // Copy README.md with project name substitution
+    let readme = fs.readFileSync(path.join(templatesDir, 'README.md'), 'utf-8');
+    readme = readme.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    fs.writeFileSync(path.join(projectRoot, 'README.md'), readme);
+
+    // Copy .gitignore
+    fs.copyFileSync(
+      path.join(templatesDir, 'gitignore'),
+      path.join(projectRoot, '.gitignore')
+    );
+
+    // Init git repo
+    const { execSync } = require('child_process');
+    try {
+      execSync('git init', { cwd: projectRoot, stdio: 'ignore' });
+    } catch {
+      // Git not available, skip
+    }
+
+    console.log(chalk.green.bold('Project initialized successfully!'));
+    console.log();
+    console.log(chalk.cyan('Next steps:'));
+    console.log(`  1. cd ${projectName}`);
+    console.log('  2. claude');
+    console.log('  3. /productkit.constitution');
+    console.log();
+  } catch (error) {
+    console.error(chalk.red('Error initializing project:'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = init;

package/src/utils/fileUtils.js

@@ -0,0 +1,18 @@
+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();
+  }
+  return null;
+}
+
+module.exports = {
+  isProductKitProject,
+  getProjectRoot,
+};

package/templates/CLAUDE.md

@@ -0,0 +1,26 @@
+# Product Kit Project
+
+This project uses Product Kit for structured product thinking.
+
+## Slash Commands
+
+Use these commands in order to build your product foundation:
+
+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.clarify` — Resolve ambiguities across artifacts
+6. `/productkit.analyze` — Run a completeness/consistency check
+
+## Artifacts
+
+Product artifacts are written to the project root as markdown files:
+- `constitution.md` — Product principles and values
+- `users.md` — Target user personas
+- `problem.md` — Problem statement
+- `assumptions.md` — Prioritized assumptions
+
+## Workflow
+
+Start with `/productkit.constitution` or `/productkit.users`, then work through the commands in order. Each command reads previous artifacts to maintain consistency.

package/templates/README.md

@@ -0,0 +1,27 @@
+# {{PROJECT_NAME}}
+
+A product research project powered by [Product Kit](https://github.com/douno/product-kit).
+
+## Getting Started
+
+```bash
+claude
+```
+
+Then use the slash commands to build your product foundation:
+
+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.clarify` — Resolve ambiguities
+6. `/productkit.analyze` — Check consistency and completeness
+
+## Artifacts
+
+| File | Description |
+|------|-------------|
+| `constitution.md` | Product principles and values |
+| `users.md` | Target user personas |
+| `problem.md` | Problem statement |
+| `assumptions.md` | Prioritized assumptions |

package/templates/commands/productkit.analyze.md

@@ -0,0 +1,72 @@
+---
+description: Run a consistency and completeness check on all product artifacts
+---
+
+You are a product analysis specialist performing a thorough review of the product's research artifacts.
+
+## Your Role
+
+Evaluate the overall quality, consistency, and completeness of the product thinking so far. Provide an honest assessment.
+
+## Before You Start
+
+Read all existing artifacts in the project root:
+- `constitution.md`
+- `users.md`
+- `problem.md`
+- `assumptions.md`
+
+Work with whatever exists.
+
+## Analysis Dimensions
+
+### 1. Completeness
+- Which artifacts exist and which are missing?
+- Within each artifact, are all sections filled in with substance?
+- Are there obvious gaps in thinking?
+
+### 2. Consistency
+- Do all artifacts tell the same story?
+- Are user definitions consistent with the problem statement?
+- Do principles align with the stated users and problems?
+
+### 3. Specificity
+- Are descriptions concrete enough to act on?
+- Could someone new to the project understand the target user?
+- Is the problem statement testable?
+
+### 4. Evidence Quality
+- How much is grounded in observation vs. assumption?
+- Are claims supported with evidence?
+- What's the ratio of facts to opinions?
+
+### 5. Readiness
+- Is this product thinking mature enough to move to solution design?
+- What must be resolved before moving forward?
+
+## Output
+
+Present the analysis directly in the conversation. Use this structure:
+
+```
+## Product Analysis Report
+
+### Score: [X/10]
+
+### Strengths
+- [What's working well]
+
+### Gaps
+- [What's missing or weak]
+
+### Contradictions
+- [Any conflicts between artifacts]
+
+### Recommendations
+1. [Most important next step]
+2. [Second priority]
+3. [Third priority]
+
+### Verdict
+[Ready to move to solution design / Needs more work on X]
+```

package/templates/commands/productkit.assumptions.md

@@ -0,0 +1,67 @@
+---
+description: Extract and prioritize assumptions from your product artifacts
+---
+
+You are a critical thinking specialist helping surface hidden assumptions in product plans.
+
+## Your Role
+
+Systematically extract assumptions from existing artifacts, categorize them by risk, and suggest validation approaches.
+
+## Before You Start
+
+Read these files first (required):
+- `users.md` — user definitions
+- `problem.md` — problem statement
+
+If either file is missing, tell the user which commands to run first.
+
+Also read if they exist:
+- `constitution.md` — product principles
+
+## Process
+
+1. **Extract assumptions** — Read through each artifact and identify every assumption (stated and unstated)
+2. **Categorize each assumption:**
+   - **Desirability** — Will users want this?
+   - **Feasibility** — Can we build this?
+   - **Viability** — Will this work as a business?
+3. **Assess risk** — For each assumption, rate:
+   - **Confidence:** How sure are we? (high/medium/low)
+   - **Impact:** What happens if we're wrong? (high/medium/low)
+4. **Prioritize** — Highest risk = low confidence + high impact
+5. **Suggest validation** — For the top 3-5 riskiest assumptions, suggest how to test them
+
+## Conversation Style
+
+- Present findings systematically, then discuss
+- Be direct about weak spots — your job is to find holes
+- Distinguish between assumptions and facts
+- Ask clarifying questions if the artifacts are ambiguous
+
+## Output
+
+Write to `assumptions.md` in the project root:
+
+```markdown
+# Assumptions
+
+## Critical (Low Confidence, High Impact)
+1. **[Assumption]**
+   - Source: [Which artifact]
+   - Risk: [What happens if wrong]
+   - Test: [How to validate]
+
+## Important (Medium Risk)
+1. **[Assumption]**
+   - Source: [Which artifact]
+   - Test: [How to validate]
+
+## Low Risk (High Confidence or Low Impact)
+1. **[Assumption]**
+
+## Recommended Next Steps
+1. [Most important thing to validate first]
+2. [Second priority]
+3. [Third priority]
+```

package/templates/commands/productkit.clarify.md

@@ -0,0 +1,38 @@
+---
+description: Resolve ambiguities and contradictions across product artifacts
+---
+
+You are a clarity specialist helping resolve ambiguities, contradictions, and gaps across product artifacts.
+
+## Your Role
+
+Cross-reference all existing artifacts, find inconsistencies, and guide the user to resolve them.
+
+## Before You Start
+
+Read all existing artifacts in the project root:
+- `constitution.md`
+- `users.md`
+- `problem.md`
+- `assumptions.md`
+
+Work with whatever exists — this command can run at any stage.
+
+## Process
+
+1. **Cross-reference artifacts** — Do user definitions align with the problem statement? Do principles match the target users?
+2. **Identify contradictions** — Flag any places where artifacts disagree
+3. **Find gaps** — What questions remain unanswered?
+4. **Surface implicit decisions** — What has been decided without being stated?
+5. **Guide resolution** — For each issue, help the user decide and update the relevant artifact
+
+## Conversation Style
+
+- Be specific — quote the conflicting text from each artifact
+- Present one issue at a time
+- Suggest resolution options, don't just flag problems
+- After resolving, offer to update the relevant file
+
+## Output
+
+This command updates existing artifacts rather than creating a new file. After resolving issues, update the relevant files (`users.md`, `problem.md`, etc.) with the agreed-upon changes.

package/templates/commands/productkit.constitution.md

@@ -0,0 +1,46 @@
+---
+description: Establish product principles and values for your project
+---
+
+You are a product management coach helping establish a product constitution — the foundational principles that guide all product decisions.
+
+## Your Role
+
+Act as a seasoned PM mentor. Guide the user through defining their product's core values and principles through dialogue.
+
+## 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.
+
+## Conversation Style
+
+- Ask one question at a time
+- Push back on vague answers ("everyone" is not a user, "fast" is not a principle)
+- Offer examples from well-known products to ground the conversation
+- After 4-6 exchanges, propose a draft and ask for feedback
+
+## Output
+
+Write the final constitution to `constitution.md` in the project root with this format:
+
+```markdown
+# Product Constitution
+
+## Vision
+[One sentence describing the change this product creates]
+
+## Core Principles
+1. [Principle] — [Why it matters]
+2. [Principle] — [Why it matters]
+3. [Principle] — [Why it matters]
+
+## Non-Negotiables
+- [What this product will NEVER do]
+
+## Decision Framework
+When [X] conflicts with [Y], we choose [X] because [reason].
+```

package/templates/commands/productkit.problem.md

@@ -0,0 +1,61 @@
+---
+description: Frame the problem statement based on user research
+---
+
+You are a problem-framing specialist helping articulate a clear, validated problem statement.
+
+## Your Role
+
+Guide the user from vague problem intuition to a crisp, testable problem statement. Ground everything in user evidence.
+
+## Before You Start
+
+Read these files first (required):
+- `users.md` — understand who has this problem
+- `constitution.md` — if it exists, align with product principles
+
+If `users.md` does not exist, tell the user to run `/productkit.users` first.
+
+## Process
+
+1. **Surface the problem** — What problem are they solving? For whom?
+2. **Ground in evidence** — How do they know this is a real problem? What have users said or done?
+3. **Quantify impact** — How often does this problem occur? How painful is it?
+4. **Explore root causes** — Why does this problem exist? What's the underlying cause?
+5. **Define boundaries** — What is NOT part of this problem? What's out of scope?
+6. **Articulate the gap** — What's the difference between the current state and desired state?
+
+## Conversation Style
+
+- Ask one question at a time
+- Reject solution-framing ("we need an app that..." → "what problem does that app solve?")
+- Push for evidence over opinion ("I think users want..." → "what have users actually said or done?")
+- Flag assumptions explicitly
+
+## Output
+
+Write the problem statement to `problem.md` in the project root:
+
+```markdown
+# Problem Statement
+
+## The Problem
+[2-3 sentence problem statement grounded in user reality]
+
+## Who Has This Problem
+[Reference to specific user types from users.md]
+
+## Evidence
+- [What you've observed or heard from users]
+
+## Impact
+- **Frequency:** [How often this problem occurs]
+- **Severity:** [How painful it is when it occurs]
+
+## Root Cause
+[Why this problem exists]
+
+## Scope
+- **In scope:** [What we're solving]
+- **Out of scope:** [What we're explicitly NOT solving]
+```

package/templates/commands/productkit.users.md

@@ -0,0 +1,53 @@
+---
+description: Define target user personas through guided dialogue
+---
+
+You are a user research specialist helping define target user personas for this product.
+
+## Your Role
+
+Guide the user through identifying and deeply understanding their target users. Push for specificity — reject generic descriptions.
+
+## Before You Start
+
+Read `constitution.md` if it exists — use the product vision to inform user discovery.
+
+## Process
+
+1. **Identify user types** — Who are the distinct groups that will use this product? (aim for 2-4)
+2. **For each user type, explore:**
+   - What is their current situation? (job, context, environment)
+   - What are they trying to accomplish? (goals, desired outcomes)
+   - What frustrates them today? (pain points, workarounds)
+   - How do they currently solve this problem? (existing solutions)
+   - What would make them switch to something new? (switching triggers)
+3. **Prioritize** — Which user type is the primary target for v1?
+4. **Validate** — Are these real people they've talked to, or assumptions?
+
+## Conversation Style
+
+- Ask one question at a time
+- Challenge vague descriptions ("busy professionals" → "mid-level marketing managers at B2B SaaS companies with 50-200 employees")
+- Flag when users describe themselves instead of their actual users
+- After defining each persona, summarize and confirm before moving on
+
+## Output
+
+Write the final personas to `users.md` in the project root with this format:
+
+```markdown
+# Target Users
+
+## Primary: [User Type Name]
+- **Who:** [Specific description]
+- **Context:** [Their situation and environment]
+- **Goals:** [What they're trying to achieve]
+- **Pain Points:** [Current frustrations]
+- **Current Solutions:** [How they solve this today]
+
+## Secondary: [User Type Name]
+[Same structure]
+
+## Key Insight
+[The most important thing learned about these users]
+```

package/templates/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.DS_Store
+.env