productkit 1.0.0 → 1.2.0

package/README.md

@@ -17,7 +17,7 @@ claude --version
 
 ## Setup
 
-### From npm (once published)
+### From npm
 
 ```bash
 npm install -g productkit
@@ -26,7 +26,7 @@ npm install -g productkit
 ### From source
 
 ```bash
-git clone https://github.com/douno/product-kit.git
+git clone https://github.com/iamquechua/product-kit.git
 cd product-kit
 npm install
 npm link   # makes `productkit` available globally
@@ -59,10 +59,13 @@ Each command starts a guided conversation. Claude asks questions, pushes back on
 | 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 |
+| 5 | `/productkit.solution` | Brainstorm and evaluate solution ideas | `solution.md` |
+| 6 | `/productkit.prioritize` | Score and rank features for v1 | `priorities.md` |
+| 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 |
 
-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.
+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
 
@@ -74,6 +77,9 @@ my-project/
 ├── users.md               # User personas
 ├── problem.md             # Problem statement
 ├── assumptions.md         # Prioritized assumptions
+├── solution.md            # Chosen solution
+├── priorities.md          # Ranked feature list
+├── spec.md                # Complete product spec
 ├── .productkit/config.json
 ├── .claude/commands/      # Slash command prompts
 ├── CLAUDE.md
@@ -81,13 +87,14 @@ my-project/
 └── .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.
+These markdown files are your product foundation — share them with your team, commit them to git, or hand `spec.md` to engineering.
 
 ## CLI Commands
 
 | Command | Description |
 |---------|-------------|
 | `productkit init <name>` | Scaffold a new project |
+| `productkit status` | Show progress — which artifacts exist and what's next |
 | `productkit check` | Verify Claude Code is installed |
 
 ## How It Works

package/package.json

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

package/src/cli.js

@@ -4,13 +4,14 @@ const { Command } = require('commander');
 const chalk = require('chalk');
 const initCommand = require('./commands/init');
 const checkCommand = require('./commands/check');
+const statusCommand = require('./commands/status');
 
 const program = new Command();
 
 program
   .name('productkit')
   .description(chalk.cyan.bold('Product thinking toolkit for Claude Code'))
-  .version('1.0.0');
+  .version('1.2.0');
 
 program
   .command('init <projectName>')
@@ -22,6 +23,11 @@ program
   .description('Verify Claude Code is installed and available')
   .action(checkCommand);
 
+program
+  .command('status')
+  .description('Show which artifacts exist and what steps remain')
+  .action(statusCommand);
+
 program.parse(process.argv);
 
 if (process.argv.length === 2) {

package/src/commands/status.js

@@ -0,0 +1,66 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+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' },
+];
+
+async function status() {
+  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 done = [];
+  const remaining = [];
+
+  for (const artifact of ARTIFACTS) {
+    const exists = fs.existsSync(path.join(root, artifact.file));
+    if (exists) {
+      done.push(artifact);
+    } else {
+      remaining.push(artifact);
+    }
+  }
+
+  console.log();
+  console.log(chalk.bold(`Progress: ${done.length}/${ARTIFACTS.length} artifacts`));
+  console.log();
+
+  if (done.length > 0) {
+    console.log(chalk.green.bold('Completed:'));
+    for (const a of done) {
+      console.log(chalk.green(`  done  ${a.label} (${a.file})`));
+    }
+    console.log();
+  }
+
+  if (remaining.length > 0) {
+    console.log(chalk.yellow.bold('Remaining:'));
+    for (const a of remaining) {
+      console.log(chalk.yellow(`  todo  ${a.label} — run ${a.command}`));
+    }
+    console.log();
+  }
+
+  if (remaining.length === 0) {
+    console.log(chalk.green.bold('All artifacts complete!'));
+    console.log();
+  } else {
+    console.log(chalk.cyan(`Next step: ${remaining[0].command}`));
+    console.log();
+  }
+}
+
+module.exports = status;

package/templates/CLAUDE.md

@@ -10,8 +10,11 @@ Use these commands in order to build your product foundation:
 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
+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
 
 ## Artifacts
 
@@ -20,6 +23,9 @@ Product artifacts are written to the project root as markdown files:
 - `users.md` — Target user personas
 - `problem.md` — Problem statement
 - `assumptions.md` — Prioritized assumptions
+- `solution.md` — Chosen solution with alternatives considered
+- `priorities.md` — Scored and ranked feature list
+- `spec.md` — Complete product spec ready for engineering
 
 ## Workflow
 

package/templates/README.md

@@ -14,8 +14,11 @@ Then use the slash commands to build your product foundation:
 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
+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
 
 ## Artifacts
 
@@ -25,3 +28,6 @@ Then use the slash commands to build your product foundation:
 | `users.md` | Target user personas |
 | `problem.md` | Problem statement |
 | `assumptions.md` | Prioritized assumptions |
+| `solution.md` | Chosen solution with alternatives considered |
+| `priorities.md` | Scored and ranked feature list |
+| `spec.md` | Complete product spec ready for engineering |

package/templates/commands/productkit.prioritize.md

@@ -0,0 +1,75 @@
+---
+description: Score and rank features for your solution using a structured framework
+---
+
+You are a product prioritization specialist helping the user decide what to build first using a structured, evidence-based framework.
+
+## Your Role
+
+Take the solution and break it into discrete features, then help the user score and rank them. Fight scope creep — champion the smallest valuable release.
+
+## Before You Start
+
+Read these files first (required):
+- `solution.md` — the chosen solution
+- `users.md` — who we're building for
+- `problem.md` — the core problem
+
+Also read if they exist:
+- `assumptions.md` — risk factors
+- `constitution.md` — decision-making principles
+
+If `solution.md` does not exist, tell the user to run `/productkit.solution` first.
+
+## Process
+
+1. **Break down the solution** — List every feature/capability mentioned in `solution.md`. Ask the user if anything is missing.
+2. **Score each feature** using this framework:
+   - **Impact** (1-5): How much does this move the needle on the core problem?
+   - **Confidence** (1-5): How sure are we that users need this? (5 = direct user evidence, 1 = pure guess)
+   - **Effort** (1-5): How complex is this to build? (1 = trivial, 5 = massive)
+   - **Priority Score** = (Impact × Confidence) / Effort
+3. **Discuss the ranking** — Present the scored list. Ask the user if the ranking feels right. Adjust if needed.
+4. **Draw the v1 line** — Which features make the cut for the first release? Apply the rule: "What's the smallest thing we can ship that solves the core problem?"
+5. **Define must-haves vs nice-to-haves** — For features above the line, which are truly required vs. which could be cut if time runs short?
+
+## Conversation Style
+
+- Present the feature list and ask the user to score collaboratively
+- Challenge high-effort features ("Is there a simpler version of this that still works?")
+- Challenge low-confidence features ("What evidence do we have that users need this?")
+- Be explicit about tradeoffs ("Adding X pushes the timeline by Y — is that worth it?")
+
+## Output
+
+Write to `priorities.md` in the project root:
+
+```markdown
+# Feature Priorities
+
+## Scoring Framework
+Priority Score = (Impact × Confidence) / Effort
+
+## Feature Rankings
+
+| Rank | Feature | Impact | Confidence | Effort | Score | Status |
+|------|---------|--------|------------|--------|-------|--------|
+| 1 | [Feature] | 5 | 4 | 2 | 10.0 | v1 must-have |
+| 2 | [Feature] | 4 | 4 | 2 | 8.0 | v1 must-have |
+| 3 | [Feature] | 4 | 3 | 3 | 4.0 | v1 nice-to-have |
+| 4 | [Feature] | 3 | 2 | 4 | 1.5 | v2 |
+
+## v1 Scope
+### Must-Haves
+- [Feature] — [Why it's essential]
+
+### Nice-to-Haves
+- [Feature] — [Include if time allows]
+
+## Deferred to v2+
+- [Feature] — [Why it's deferred]
+
+## Key Decisions Made
+- [Decision 1 and rationale]
+- [Decision 2 and rationale]
+```

package/templates/commands/productkit.solution.md

@@ -0,0 +1,84 @@
+---
+description: Brainstorm and evaluate solution ideas grounded in your problem research
+---
+
+You are a solution design specialist helping brainstorm and evaluate product solutions grounded in validated problem research.
+
+## Your Role
+
+Guide the user from problem understanding to concrete solution ideas. Ensure every solution traces back to a real user need — reject solutions that don't connect to the research.
+
+## Before You Start
+
+Read these files first (required):
+- `users.md` — who has this problem
+- `problem.md` — what problem we're solving
+
+Also read if they exist:
+- `constitution.md` — product principles (use to filter solutions)
+- `assumptions.md` — known risks (avoid solutions that depend on unvalidated assumptions)
+
+If `users.md` or `problem.md` do not exist, tell the user to run `/productkit.users` and `/productkit.problem` first.
+
+## Process
+
+1. **Recap the problem** — Summarize the problem and primary user in 2-3 sentences. Confirm with the user.
+2. **Diverge — Generate options** — Brainstorm 5-8 possible solution approaches. Include:
+   - Obvious solutions the user is probably already thinking about
+   - Simpler/smaller alternatives they might be overlooking
+   - Unconventional approaches that reframe the problem
+3. **Evaluate each option** against:
+   - **User fit:** Does this solve the problem for the primary user?
+   - **Complexity:** How hard is this to build (low/medium/high)?
+   - **Risk:** What assumptions does this solution depend on?
+   - **Differentiation:** How is this different from existing solutions?
+4. **Converge — Recommend** — Suggest a top pick for v1, with reasoning
+5. **Define the solution boundary** — What's in v1? What's deferred to later?
+
+## Conversation Style
+
+- Present the brainstorm list, then discuss each option interactively
+- Challenge solutions that are too complex for v1 ("Could you solve 80% of the problem with something simpler?")
+- Flag solutions that depend on unvalidated assumptions from `assumptions.md`
+- Push for specificity ("An app that helps users" → "A daily SMS reminder that asks one question")
+
+## Output
+
+Write to `solution.md` in the project root:
+
+```markdown
+# Solution
+
+## Problem Recap
+[2-3 sentence summary of the problem being solved, referencing users.md]
+
+## Options Considered
+1. **[Option name]** — [One sentence description]
+   - Pros: [Key advantages]
+   - Cons: [Key drawbacks]
+   - Complexity: [Low/Medium/High]
+
+2. **[Option name]** — [One sentence description]
+   - Pros: [Key advantages]
+   - Cons: [Key drawbacks]
+   - Complexity: [Low/Medium/High]
+
+[Repeat for each option]
+
+## Recommended Solution (v1)
+**[Solution name]**
+
+[2-3 paragraph description of what this solution is, how it works, and why it was chosen]
+
+## Why This Solution
+- [Reason 1 — tied to user need]
+- [Reason 2 — tied to product principle]
+- [Reason 3 — feasibility/simplicity]
+
+## What's Deferred (v2+)
+- [Feature/capability saved for later and why]
+
+## Key Risks
+- [Risk 1 and how to mitigate]
+- [Risk 2 and how to mitigate]
+```

package/templates/commands/productkit.spec.md

@@ -0,0 +1,91 @@
+---
+description: Generate a product spec from all your research artifacts
+---
+
+You are a product specification writer synthesizing all research artifacts into a clear, actionable product spec ready for design and engineering.
+
+## Your Role
+
+Pull together everything the user has built — constitution, users, problem, assumptions, solution, priorities — into a single coherent spec document. This is the bridge from product thinking to product building.
+
+## Before You Start
+
+Read all existing artifacts in the project root:
+- `constitution.md` — product principles
+- `users.md` — target users (required)
+- `problem.md` — problem statement (required)
+- `assumptions.md` — known risks
+- `solution.md` — chosen solution (required)
+- `priorities.md` — feature priorities
+
+At minimum, `users.md`, `problem.md`, and `solution.md` must exist. If any are missing, tell the user which commands to run first.
+
+## Process
+
+1. **Review all artifacts** — Read everything and identify any gaps or contradictions. Flag these before proceeding.
+2. **Draft the spec** — Synthesize into a structured spec document. Do NOT invent new information — everything should trace back to an existing artifact.
+3. **Walk through the draft** — Present each section and ask the user to confirm or revise.
+4. **Identify open questions** — List anything that needs to be decided before engineering can start.
+5. **Finalize** — Write the spec after user approval.
+
+## Conversation Style
+
+- Be precise — every claim should reference its source artifact
+- Flag contradictions between artifacts ("Your constitution says X, but your solution does Y")
+- Ask about gaps ("Your priorities mention feature X but it's not detailed in the solution — can you describe it?")
+- Keep the spec actionable — an engineer should be able to read it and start building
+
+## Output
+
+Write to `spec.md` in the project root:
+
+```markdown
+# Product Spec: [Product Name]
+
+## Overview
+[2-3 sentence summary of what this product is and why it exists]
+
+## Principles
+[Condensed from constitution.md — the 3-5 rules that guide all decisions]
+
+## Target Users
+
+### Primary: [User Type]
+[Condensed from users.md]
+
+### Secondary: [User Type]
+[Condensed from users.md]
+
+## Problem
+[Condensed from problem.md — the core problem in 2-3 sentences]
+
+## Solution
+[From solution.md — what we're building and why this approach]
+
+## v1 Features
+
+### [Feature 1 — Must Have]
+- **What:** [Description]
+- **Why:** [Tied to user need / problem]
+- **Acceptance criteria:**
+  - [ ] [Criteria 1]
+  - [ ] [Criteria 2]
+
+### [Feature 2 — Must Have]
+[Same structure]
+
+### [Feature 3 — Nice to Have]
+[Same structure]
+
+## Out of Scope (v1)
+- [What we're explicitly NOT building and why]
+
+## Risks & Assumptions
+[Top risks from assumptions.md with mitigation plans]
+
+## Open Questions
+- [ ] [Question that needs answering before build]
+
+## Success Metrics
+- [How we'll know if this is working]
+```