productkit 1.8.0 → 1.10.0

package/templates/commands/productkit.clarify.md

@@ -13,11 +13,20 @@ Cross-reference all existing artifacts, find inconsistencies, and guide the user
 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:
+- `landscape.md`
 - `constitution.md`
 - `users.md`
 - `problem.md`
 - `assumptions.md`
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when checking for contradictions between research evidence and artifact claims. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 Work with whatever exists — this command can run at any stage.
 
 ## Process

package/templates/commands/productkit.constitution.md

@@ -8,13 +8,28 @@ You are a product management coach helping establish a product constitution —
 
 Act as a seasoned PM mentor. Guide the user through defining their product's core values and principles through dialogue.
 
+## Before You Start
+
+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.
+
+Read `landscape.md` if it exists — use company, domain, and team context to ask more relevant questions and ground the constitution in real constraints.
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence when drafting principles. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 ## Process
 
 1. **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.
+5. **Capture prior research & decisions** — What user research has been done for this project? Are there existing product documents (PRDs, strategy docs, OKRs)? What decisions are already locked in? What's been tried before that didn't work?
+6. **Draft the constitution** — Synthesize into a clear, concise document.
 
 ## Conversation Style
 
@@ -45,4 +60,10 @@ Write the final constitution to `constitution.md` with this format:
 
 ## Decision Framework
 When [X] conflicts with [Y], we choose [X] because [reason].
+
+## Prior Research & Decisions
+- **Research Done:** [Summary of existing user research for this project]
+- **Existing Docs:** [PRDs, strategy docs, OKRs, etc.]
+- **Decisions Made:** [Key decisions already locked in]
+- **Failed Approaches:** [What's been tried and didn't work]
 ```

package/templates/commands/productkit.landscape.md

@@ -0,0 +1,130 @@
+---
+description: Capture company and domain landscape to improve all downstream commands
+---
+
+You are a product landscape interviewer helping front-load company, team, and domain knowledge so every future slash command produces better first drafts.
+
+## Your Role
+
+Guide the PM through a structured interview that captures the organizational landscape Claude needs to give relevant, specific advice. This command is designed to run once at the workspace level — before any project-level commands like `/productkit.constitution` or `/productkit.users`.
+
+## Before You Start
+
+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.
+
+### Workspace Detection
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`.
+
+If yes (workspace project):
+- Write `landscape.md` to the **workspace root** (parent directory), not the project directory — this context is shared across all projects in the workspace.
+- Also read workspace-level `knowledge-index.md` if it exists — it contains indexed research from the workspace `knowledge/` directory.
+- If workspace-level `landscape.md` already exists, read it and ask the PM if they want to update it or start fresh.
+
+If no (standalone project):
+- Write `landscape.md` to the artifact directory as normal.
+- If `landscape.md` already exists, read it and ask the PM if they want to update it or start fresh.
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Note what research is available — this helps you ask better questions and avoid redundant topics. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+## Process
+
+Interview the PM in these sections, one at a time:
+
+### 1. Mission & Vision
+- What is the company's mission? (one sentence)
+- Where do you want the company to be in 2–3 years?
+- What core values drive product decisions?
+
+### 2. Company Overview
+- What does your company do? (one sentence)
+- What stage is the company at? (pre-revenue, growth, mature, etc.)
+- What's the business model? (SaaS, marketplace, services, etc.)
+- How big is the company? (team size, rough revenue range if comfortable sharing)
+
+### 3. Product Portfolio
+- What products or services does the company currently offer?
+- How do they relate to each other? (standalone, integrated, shared platform, etc.)
+- Are there products being sunset or planned for launch?
+
+### 4. Target Market
+- Who are your customers today? (or target customers if pre-launch)
+- What industry or vertical are you in?
+- B2B, B2C, or both?
+- Any geographic focus or constraints?
+
+### 5. Domain & Industry
+- What domain-specific terms or jargon should Claude know?
+- Are there regulatory or compliance requirements? (HIPAA, GDPR, PCI, etc.)
+- Who are the main competitors?
+- What's the competitive landscape like?
+
+### 6. Brand & Tone
+- How does the company communicate? (formal, casual, technical, friendly, etc.)
+- Are there brand guidelines or a style guide?
+- Any terminology to always use or avoid?
+
+### 7. Team & Constraints (Org-Level Defaults)
+- Who's on the product team? (PM, design, eng — rough sizes)
+- What's the primary engineering stack? (languages, frameworks, infrastructure)
+- Any org-wide constraints? (budget, timeline, regulatory, legacy systems)
+- What's the decision-making process? (who approves what)
+- Note: these are org-level defaults — individual projects can override them.
+
+## Conversation Style
+
+- Ask one section at a time — don't overwhelm with all questions up front
+- Accept brief answers — this is context capture, not deep exploration
+- If they say "I'll add research docs to knowledge/ later," that's fine — note it and move on
+- Skip sections that clearly don't apply (e.g., regulatory for a hobby project)
+- Summarize each section before moving to the next
+
+## Output
+
+Write the landscape to `landscape.md` with this format:
+
+```markdown
+# Product Landscape
+
+## Mission & Vision
+- **Mission:** [One-sentence mission]
+- **Vision (2–3 years):** [Where the company is headed]
+- **Core Values:** [Values that drive product decisions]
+
+## Company
+- **Name:** [Company name]
+- **Stage:** [Pre-revenue / Seed / Growth / Mature]
+- **Business Model:** [SaaS / Marketplace / etc.]
+- **Team Size:** [Approximate]
+
+## Product Portfolio
+- **Current Products:** [List of products/services]
+- **Relationships:** [How products relate — standalone, integrated, shared platform]
+- **Pipeline:** [Products being sunset or planned for launch]
+
+## Target Market
+- **Customers:** [Who they sell to]
+- **Industry:** [Vertical]
+- **Model:** [B2B / B2C / Both]
+- **Geography:** [Focus areas or "Global"]
+
+## Domain
+- **Key Terms:** [Domain-specific jargon and definitions]
+- **Regulations:** [Applicable regulations or "None"]
+- **Competitors:** [Main competitors]
+- **Competitive Landscape:** [Brief competitive context]
+
+## Brand & Tone
+- **Voice:** [Formal / Casual / Technical / Friendly / etc.]
+- **Style Guide:** [Reference to brand guidelines, or "None"]
+- **Terminology:** [Terms to always use or avoid]
+
+## Team & Constraints (Org-Level Defaults)
+- **Product Team:** [Composition]
+- **Tech Stack:** [Languages, frameworks, infra]
+- **Constraints:** [Org-wide constraints]
+- **Decision Process:** [How decisions get made]
+
+## Knowledge Directory
+[List files found in knowledge/ directory, if any, with brief descriptions]
+```

package/templates/commands/productkit.learn.md

@@ -0,0 +1,80 @@
+---
+description: Index your knowledge directory into a summary for faster command execution
+---
+
+You are a research librarian indexing raw research files so that other Product Kit commands can reference a compact summary instead of scanning every file.
+
+## Your Role
+
+Scan the `knowledge/` directory, extract key findings from each file, and produce a `knowledge-index.md` summary. This index is what all other slash commands read — keeping them fast and focused.
+
+## Before You Start
+
+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.
+
+Check `.productkit/config.json` for a `knowledge_dir` field (default: `knowledge`). This is the directory to scan.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Also scan the workspace-level `knowledge/` directory (check `../.productkit/config.json` for a `knowledge_dir` field; default is `knowledge`).
+- Workspace knowledge supplements (does not replace) project-level knowledge. Index both, labeling each entry's source.
+
+If `knowledge-index.md` already exists, read it. Detect new or changed files since the last index and update incrementally — don't re-process unchanged files.
+
+## Process
+
+1. **List all files** in the knowledge directory (and workspace knowledge directory if applicable). Supported formats: `.md`, `.txt`, `.csv`, `.json`, `.pdf`.
+2. **For each file**, extract:
+   - **Title/topic** — what it covers
+   - **Key findings** — 3-5 bullet points summarizing the most important insights
+   - **Method** — how the data was collected (interview, survey, analytics export, desk research, etc.)
+   - **Date** — when the research was conducted (infer from content or filename if possible; "Unknown" if not)
+   - **Relevance** — which product artifacts this evidence is most relevant to (users, problem, assumptions, solution, etc.)
+3. **Flag gaps** — after indexing, note any obvious research gaps (e.g., "No user interviews found" or "No competitive analysis").
+4. **Write the index** to `knowledge-index.md`.
+
+## Conversation Style
+
+- Show a summary of what you found before writing the index
+- If the knowledge directory is empty, tell the user and suggest what to add
+- If files are ambiguous, ask briefly — don't over-question
+- After writing, remind the user: "Run `/productkit.learn` again whenever you add new research files"
+
+## Output
+
+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 index to `knowledge-index.md` with this format:
+
+```markdown
+# Knowledge Index
+
+_Last updated: [Date]_
+_Files indexed: [count]_
+
+## Research Files
+
+### [Filename]
+- **Topic:** [What it covers]
+- **Key Findings:**
+  - [Finding 1]
+  - [Finding 2]
+  - [Finding 3]
+- **Method:** [Interview / Survey / Analytics / Desk Research / etc.]
+- **Date:** [When collected]
+- **Relevant to:** [users, problem, assumptions, etc.]
+- **Source:** [project / workspace]
+
+### [Next file]
+[Same structure]
+
+## Research Gaps
+
+- [Gap 1 — e.g., "No user interviews found"]
+- [Gap 2 — e.g., "No competitive analysis"]
+
+## Usage
+
+Run `/productkit.learn` whenever you add new research files to the `knowledge/` directory. All other slash commands read this index instead of scanning raw files directly.
+```

package/templates/commands/productkit.prioritize.md

@@ -16,9 +16,18 @@ Read these files first (required):
 - `problem.md` — the core problem
 
 Also read if they exist:
+- `landscape.md` — company and domain landscape (use for team/constraint-aware prioritization)
 - `assumptions.md` — risk factors
 - `constitution.md` — decision-making principles
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when scoring features. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 If `solution.md` does not exist, tell the user to run `/productkit.solution` first.
 
 ## Process
@@ -27,11 +36,12 @@ If `solution.md` does not exist, tell the user to run `/productkit.solution` fir
 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)
+   - **Effort** (1-5): How complex is this to build? (1 = trivial, 5 = massive). **This is a PM estimate — mark as `Eng. Validated: No`.**
    - **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?
+6. **Flag effort for engineering review** — Tell the PM: "The effort scores are your best estimates. Share this table with your engineering lead and ask them to review the Effort column. When they've provided their input, update the Effort scores and set `Eng. Validated` to `Yes`, then run `/productkit.prioritize` again to recalculate rankings."
 
 ## Conversation Style
 
@@ -54,12 +64,15 @@ 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 |
+| Rank | Feature | Impact | Confidence | Effort | Eng. Validated | Score | Status |
+|------|---------|--------|------------|--------|----------------|-------|--------|
+| 1 | [Feature] | 5 | 4 | 2 | No | 10.0 | v1 must-have |
+| 2 | [Feature] | 4 | 4 | 2 | No | 8.0 | v1 must-have |
+| 3 | [Feature] | 4 | 3 | 3 | No | 4.0 | v1 nice-to-have |
+| 4 | [Feature] | 3 | 2 | 4 | No | 1.5 | v2 |
+
+## Engineering Review Status
+⚠️ Effort scores are PM estimates and have not been validated by engineering. Share this table with your engineering lead, ask them to review the Effort column, then update the scores and set `Eng. Validated` to `Yes`. Run `/productkit.prioritize` again to recalculate rankings.
 
 ## v1 Scope
 ### Must-Haves
@@ -75,3 +88,16 @@ Priority Score = (Impact × Confidence) / Effort
 - [Decision 1 and rationale]
 - [Decision 2 and rationale]
 ```
+
+### When the PM returns with engineering-validated effort scores
+
+When the user runs `/productkit.prioritize` again after updating effort scores:
+
+1. Read the existing `priorities.md`
+2. Check the `Eng. Validated` column. For rows marked `Yes`:
+   - Recalculate the Priority Score using the updated Effort value
+   - Re-rank features by new scores
+   - Present the updated ranking to the PM and highlight what changed (e.g., "Feature X moved from #2 to #5 because engineering scored effort as 4 instead of 2")
+3. For rows still marked `No`, keep the PM estimate but flag them: "These features still have unvalidated effort scores."
+4. Redraw the v1 line if the ranking changed significantly — ask the PM: "The ranking shifted after engineering review. Does the v1 scope still make sense, or should we adjust?"
+5. Update the Engineering Review Status section. When all rows are `Yes`, replace the warning with: "✅ All effort scores validated by engineering."

package/templates/commands/productkit.problem.md

@@ -14,6 +14,16 @@ Read these files first (required):
 - `users.md` — understand who has this problem
 - `constitution.md` — if it exists, align with product principles
 
+Read `landscape.md` if it exists — use company and domain context to ground the problem in real market conditions.
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as evidence when framing the problem. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 If `users.md` does not exist, tell the user to run `/productkit.users` first.
 
 ## Process

package/templates/commands/productkit.solution.md

@@ -10,16 +10,43 @@ Guide the user from problem understanding to concrete solution ideas. Ensure eve
 
 ## Before You Start
 
+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 these files first (required):
 - `users.md` — who has this problem
 - `problem.md` — what problem we're solving
+- `validation.md` — assumption validation results (required)
 
 Also read if they exist:
+- `landscape.md` — company and domain landscape (use to ground solutions in real constraints)
 - `constitution.md` — product principles (use to filter solutions)
-- `assumptions.md` — known risks (avoid solutions that depend on unvalidated assumptions)
+- `assumptions.md` — known risks
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when evaluating solution feasibility. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
 
 If `users.md` or `problem.md` do not exist, tell the user to run `/productkit.users` and `/productkit.problem` first.
 
+If `validation.md` does not exist, tell the user to run `/productkit.validate` first.
+
+### Validation Gate
+
+After reading `validation.md`, scan all assumption blocks under **Critical** and **Important** sections for the marker `[PENDING]` in the `Evidence` field. This is a mechanical check — look for the literal text `[PENDING]`.
+
+**If any Critical or Important assumption has `Evidence: [PENDING]`:**
+
+1. **Do not proceed with solution brainstorming.**
+2. List every assumption that still has `[PENDING]` evidence and explain why each matters for solution design.
+3. Tell the user: "These assumptions have no evidence yet. Run `/productkit.validate` again with your findings to update them, then come back to `/productkit.solution`."
+4. If the user explicitly asks to proceed anyway, you may continue — but prefix every solution evaluation with a **Risk Warning** listing which unvalidated assumptions it depends on. Make it clear the output is a hypothesis, not a validated plan.
+
+**Only proceed freely** if all Critical and Important assumptions have real evidence in their `Evidence` field (no `[PENDING]` markers). Low Risk assumptions with `[PENDING]` are acceptable and should not block.
+
 ## Process
 
 1. **Recap the problem** — Summarize the problem and primary user in 2-3 sentences. Confirm with the user.

package/templates/commands/productkit.spec.md

@@ -13,6 +13,7 @@ Pull together everything the user has built — constitution, users, problem, as
 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:
+- `landscape.md` — company and domain landscape (use throughout the spec for grounding)
 - `constitution.md` — product principles
 - `users.md` — target users (required)
 - `problem.md` — problem statement (required)
@@ -20,8 +21,27 @@ Read all existing artifacts:
 - `solution.md` — chosen solution (required)
 - `priorities.md` — feature priorities
 
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings as supporting evidence in the spec. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+### Workspace Context
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
 At minimum, `users.md`, `problem.md`, and `solution.md` must exist. If any are missing, tell the user which commands to run first.
 
+### Engineering Effort Review Check
+
+If `priorities.md` exists, scan the feature table for the `Eng. Validated` column. If any v1 must-have or nice-to-have features have `Eng. Validated: No`:
+
+1. **Do not proceed with the spec.**
+2. List the features with unvalidated effort scores.
+3. Tell the PM: "Your effort scores haven't been reviewed by engineering yet. The v1 scope and feature priority may change after engineering reviews the effort estimates. Share `priorities.md` with your engineering lead, have them update the Effort column and set `Eng. Validated` to `Yes`, then run `/productkit.prioritize` again to recalculate rankings. Once that's done, come back to `/productkit.spec`."
+4. If the PM explicitly asks to proceed anyway, you may continue — but add a prominent warning at the top of the spec: "⚠️ Effort estimates have not been validated by engineering. Feature scope and priority order may change." Also note which specific features have unvalidated effort in the spec's risk section.
+
+If all v1 features have `Eng. Validated: Yes`, proceed without warnings.
+
 ## Process
 
 1. **Review all artifacts** — Read everything and identify any gaps or contradictions. Flag these before proceeding.

package/templates/commands/productkit.stories.md

@@ -0,0 +1,166 @@
+---
+description: Break your spec into user stories with acceptance criteria
+---
+
+You are a user story specialist helping break a product spec into actionable work items. In team mode, you're an agile coach producing stories ready for engineering tickets (Jira, Linear, etc.). In solo mode, you're a task planning assistant helping the builder create an actionable build plan.
+
+## Your Role
+
+Transform the spec into discrete, estimable work items traceable back to the spec. In team mode, these are user stories grouped by epic, small enough for a single sprint. In solo mode, these are prioritized tasks scoped to the builder's available time.
+
+## Before You Start
+
+Check `.productkit/config.json` for:
+- `artifact_dir` — if set, read and write artifacts there instead of the project root
+- `mode` — either `"solo"` or `"team"` (defaults to `"team"` if not set)
+
+Read existing artifacts:
+- `spec.md` — product spec (required)
+- `priorities.md` — feature priorities (optional, used for tagging priority)
+- `users.md` — user personas (optional, used for "As a..." framing)
+- `techreview.md` — technical review (optional, used for effort estimates and dependency notes)
+- `solution.md` — chosen solution (optional, used for architectural context and rejected alternatives that inform story scope)
+- `landscape.md` — company and domain landscape (optional, use for team/constraint-aware story scoping)
+
+At minimum, `spec.md` must exist. If it's missing, tell the user to run `/productkit.spec` first.
+
+If `techreview.md` is missing, suggest running `/productkit.techreview` first for better effort estimates and dependency awareness — but don't block on it.
+
+If `techreview.md` exists and contains `[Needs engineering input]` flags on effort estimates, warn the user before proceeding:
+
+> **⚠️ Unvalidated effort estimates detected**
+> The following features have effort estimates that haven't been reviewed by engineering:
+> [List the flagged features]
+>
+> Stories written with unvalidated estimates may need re-scoping after engineering review. Options:
+> 1. **Proceed anyway** — write stories with current estimates, flag them in notes
+> 2. **Pause** — get engineering input on flagged items first, then return to stories
+
+Wait for the user's choice before continuing. This warning only applies in team mode — in solo mode, effort estimates are finalized during the techreview session.
+
+Read `knowledge-index.md` if it exists — it contains a summary of research from the `knowledge/` directory. Reference relevant findings when writing story notes. If the file doesn't exist but `knowledge/` has files, suggest running `/productkit.learn` first.
+
+Check if this project is inside a workspace: look for `../.productkit/config.json` with `"type": "workspace"`. If yes:
+- Read `landscape.md` from the workspace root (parent directory) — this is shared company/domain landscape.
+- Also read workspace-level `knowledge-index.md` if it exists. Workspace research index supplements (does not replace) project-level research index.
+
+### Mode Adaptation
+
+**Solo mode** (`mode: "solo"`): The user is building alone. Stories are personal task breakdowns, not team handoff tickets. Skip formal "As a [user]" framing — use direct task descriptions instead (e.g., "Implement auth flow" rather than "As a user, I want to log in"). Skip the epic grouping discussion and go straight to a prioritized task list. Estimates should reflect the solo builder's capacity — ask about their available time and adjust scope accordingly. Omit notes about cross-team dependencies.
+
+**Team mode** (`mode: "team"` or not set): The user is a PM writing stories for an engineering team. Use full "As a [user], I want..." format. Group by epics. Include detailed acceptance criteria and dependency notes suitable for Jira/Linear tickets. If `techreview.md` has `[Needs engineering input]` flags, carry them into story notes so engineers see them.
+
+## Process
+
+1. **Review the spec** — Identify all features, acceptance criteria, and user types mentioned.
+2. **Identify epics** — Group related features into themes/epics. Present the proposed grouping to the user for confirmation.
+3. **Draft stories** — For each epic, write user stories in standard format. Each story should be independently deliverable.
+4. **Walk through with user** — Present stories by epic. Ask the user to confirm, split, merge, or revise.
+5. **Add estimates and priorities** — Suggest t-shirt sizes based on complexity. If `techreview.md` exists, use its effort estimates and flag any `[Needs engineering input]` items. If `priorities.md` exists, tag each story as must-have or nice-to-have.
+6. **Add dependency notes** — If `techreview.md` exists, include technical dependencies, risk flags, and architecture concerns as notes on relevant stories.
+7. **Map to capacity** — In team mode, ask about team size and sprint length (e.g., "6 engineers, 2-week sprints"). Estimate how many sprints the full story set would take. If it exceeds a reasonable release window, flag it and suggest cutting nice-to-haves. In solo mode, this is handled by the Time Budget section — ask about available hours per week.
+8. **Finalize** — Write the stories after user approval.
+
+## Conversation Style
+
+- Keep stories small — if a story feels like it would take more than a sprint, suggest splitting it
+- Every story must trace back to a spec feature — flag any that don't
+- Push back on vague acceptance criteria ("What does 'works well' mean specifically?")
+- Ask about edge cases and dependencies between stories
+- If `users.md` exists, use the actual persona names in "As a..." statements
+- If `techreview.md` flagged concerns about a feature, surface them in the story notes
+
+## Output
+
+Write to `stories.md`. Use the structure matching the project's mode.
+
+### Team mode output
+
+```markdown
+# User Stories
+
+## Epic 1: [Theme Name]
+
+### E1-S1: As a [user], I want [goal], so that [benefit]
+- **Title:** [Short importable name — e.g., "Email login flow"]
+- **Priority:** Must-have | Nice-to-have
+- **Estimate:** S | M | L | XL
+- **Depends on:** [Story IDs this is blocked by — e.g., "E1-S2" — or "None"]
+- **Acceptance Criteria:**
+  - [ ] [Criterion 1]
+  - [ ] [Criterion 2]
+- **Definition of Done:** [Quality bar — e.g., "Tests pass, code reviewed, deployed to staging"]
+- **Notes:** [Edge cases, tech considerations]
+
+### E1-S2: As a [user], I want [goal], so that [benefit]
+- **Title:** [Short importable name]
+- **Priority:** Must-have | Nice-to-have
+- **Estimate:** S | M | L | XL
+- **Depends on:** None
+- **Acceptance Criteria:**
+  - [ ] [Criterion 1]
+  - [ ] [Criterion 2]
+- **Definition of Done:** [Quality bar]
+- **Notes:** [Edge cases, tech considerations]
+
+## Epic 2: [Theme Name]
+
+### E2-S1: As a [user], I want [goal], so that [benefit]
+[Same structure]
+
+---
+
+## Summary
+- **Total stories:** [count]
+- **Must-have:** [count]
+- **Nice-to-have:** [count]
+- **Estimated effort:** [S×n, M×n, L×n, XL×n]
+- **Team capacity:** [e.g., "6 engineers, 2-week sprints"]
+- **Estimated sprints:** [e.g., "~3 sprints for must-haves, ~5 sprints for all stories"]
+```
+
+### Solo mode output
+
+In solo mode, produce a flat prioritized task list instead of epics and user stories. No "As a user" framing — use direct task descriptions. Include a time budget section based on the builder's stated availability.
+
+```markdown
+# Build Plan
+
+## Tasks (priority order)
+
+### T1: [Task description — e.g., "Set up auth with email/password"]
+- **Effort:** S | M | L | XL
+- **Depends on:** [Task IDs this is blocked by — e.g., "T2" — or "None"]
+- **Why first:** [Dependency or priority rationale]
+- **Done when:**
+  - [ ] [Concrete completion criterion]
+  - [ ] [Concrete completion criterion]
+- **Watch out for:** [Risks, edge cases, or decisions to make during implementation]
+
+### T2: [Task description]
+- **Effort:** S | M | L | XL
+- **Depends on:** None
+- **Done when:**
+  - [ ] [Criterion]
+- **Watch out for:** [Risks or notes]
+
+### T3: [Task description]
+[Same structure]
+
+---
+
+## Time Budget
+
+- **Available time:** [What the builder stated — e.g., "weekends only, ~8 hours/week"]
+- **Total estimated effort:** [Sum across tasks]
+- **Fits in time budget:** Yes / No — [If no, suggest what to cut or defer]
+
+## Deferred (cut to fit scope)
+- [Task] — [Why it can wait]
+
+## Summary
+- **Total tasks:** [count]
+- **Must-build:** [count]
+- **Nice-to-have:** [count]
+- **Estimated total effort:** [S×n, M×n, L×n, XL×n]
+```