feat: add project discovery workflow

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "propulsion",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "description": "Opinionated agentic coding workflow that guides software work from exploration and planning through execution and review.",
     "author": {
         "name": "Moon Pixels"

AGENTS.md

@@ -1,2 +1,3 @@
 - When the user corrects you with a reusable, global rule, ask if they want it added to `AGENTS.md`.
 - After implementing changes run `bun run checks` before handoff.
+- When raising a PR, update `package.json` to the appropriate semantic version for the PR contents and keep mirrored manifest versions in sync.

package.json

@@ -1,6 +1,6 @@
 {
     "name": "propulsion",
-    "version": "1.1.2",
+    "version": "1.2.0",
     "main": "./index.mjs",
     "exports": "./index.mjs",
     "scripts": {

skills/brainstorm/SKILL.md

@@ -12,6 +12,8 @@ Turn feature, UX, API, product-scope, or requirements work into an approved PRD.
 ALL prerequisites MUST be satisfied BEFORE following this skill.
 
 - If user provides an approved `docs/propulsion/.../prd.md`, STOP. Enter the `plan` skill.
+- If the request is greenfield project discovery and no target-root `project-brief.md` exists, STOP. Enter the `discover-project` skill.
+- If an approved target-root `project-brief.md` exists, read it before interrogation and treat approved discovery decisions as durable PRD inputs.
 
 ## Instructions
 
@@ -30,6 +32,7 @@ These rules are MANDATORY.
 - ALWAYS use `interrogate` skill to reach shared understanding BEFORE writing the PRD.
 - ALWAYS use the PRD template for structure and section order.
 - MUST keep the PRD product-facing and record durable implementation and testing decisions.
+- MUST preserve approved discovery decisions from target-root `project-brief.md` unless the user asks to revise them.
 - ENSURE the PRD includes ALL relevant decisions, even if they seem obvious or minor.
 - USE supporting documents such as `docs/propulsion/.../diagrams.md` if needed.
 - If you cannot write files, STOP, ask the user to enable write mode before continuing the PRD.

skills/discover-project/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: discover-project
+description: Create root project briefs for greenfield products and system blueprints. Use when starting project discovery, positioning, competitor research, or full project definition.
+---
+
+# Discover Project
+
+Turn a rough software idea into an approved root `project-brief.md` for later Propulsion PRDs.
+
+## Prerequisites
+
+ALL prerequisites MUST be satisfied BEFORE following this skill.
+
+- If an approved target-root `project-brief.md` already exists, STOP. Ask which feature should enter `brainstorm`.
+- If current external evidence is required and browsing is unavailable, STOP. Ask the user to enable browsing or provide sources.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Resolve the target project root; default to the current workspace root unless the user names another path.
+2. Load `interrogate` and close every discovery decision using [references/discovery-checklist.md](references/discovery-checklist.md).
+3. Gather problem, users, business model, explicit user-chosen stack, features, MVP boundary, risks, and success metrics.
+4. Research competitors, alternatives, market, and positioning claims when they need current evidence.
+5. Write `<target-project-root>/project-brief.md` from [references/project-brief-template.md](references/project-brief-template.md).
+6. Sanity-check the brief against the conversation, research, and repo context. Remove contradictions, placeholders, and unanswered questions.
+7. Start a fresh project brief reviewer subagent with [references/project-brief-reviewer-prompt.md](references/project-brief-reviewer-prompt.md).
+8. Fix reviewer findings, then repeat step 7 until the latest review returns exact `Status: approved`.
+9. Ask the user to review and approve `project-brief.md`.
+10. After user approval, update `<target-project-root>/project-brief.md` metadata to `Status: Approved` and set `Last reviewed` to the approval date.
+
+## Rules
+
+These rules are MANDATORY.
+
+- ALWAYS use `interrogate` before writing the brief.
+- MUST keep asking until there are no open questions in the approved brief.
+- MUST separate sourced evidence from inference and include research dates and confidence.
+- MUST use current web evidence for competitor, market, positioning, or similar external claims.
+- MUST include monetisation or business model, with explicit `N/A` allowed.
+- MUST record explicit user-chosen architecture, language, framework, storage, deployment, and integrations.
+- MUST include a full feature inventory grouped by product area with MVP, later, and suggested PRD slices.
+- USE `Status: approved` as the ONLY valid project brief reviewer approval signal.
+- MUST block user approval and repeat review when reviewer status is rejected, missing, or unclear.
+- DO NOT decide detailed UI style beyond minimal platform or UI-presence context; defer UI style to feature PRDs.
+- DO NOT write `plan.md`; discovery output is root `project-brief.md` only.
+
+## Completion Gate
+
+Do NOT leave this skill until ALL items are complete.
+
+- [ ] Target project root is resolved.
+- [ ] Interrogation closed every discovery question.
+- [ ] Current evidence supports all competitor, market, and positioning claims.
+- [ ] Root `project-brief.md` is written and cross-checked.
+- [ ] Project brief reviewer returned exact `Status: approved`.
+- [ ] User explicitly approved `project-brief.md`.
+- [ ] Approved `project-brief.md` metadata was written with `Status: Approved` and `Last reviewed` set to the approval date.
+
+## Next Steps
+
+Once the completion gate is fully checked:
+
+- STOP after approved metadata is written. Do not enter `brainstorm` until the user chooses a feature for PRD work.
+
+## References
+
+Use these references when you need detail.
+
+- [references/discovery-checklist.md](references/discovery-checklist.md) - Required discovery decision tree.
+- [references/project-brief-template.md](references/project-brief-template.md) - Root project brief structure.
+- [references/project-brief-reviewer-prompt.md](references/project-brief-reviewer-prompt.md) - Project brief reviewer subagent prompt.

skills/discover-project/references/discovery-checklist.md

@@ -0,0 +1,55 @@
+# Discovery Checklist
+
+Use this checklist with `interrogate`. Close every branch before approving `project-brief.md`; do not leave open questions in the final brief.
+
+## Project Identity
+
+- Project name, one-sentence concept, target project root, and intended first operating context.
+- Product category or market frame the user wants the project to occupy.
+- Non-goals that prevent the project from becoming a generic platform.
+
+## Problem And Users
+
+- Primary user segments and the job each segment needs done.
+- Current pain, workaround, substitute tool, or manual process.
+- Trigger moments, frequency of use, and consequences of failure.
+- Desired user outcome and desired business or owner outcome.
+
+## Evidence And Landscape
+
+- Evidence for the problem: user context, interviews, observations, market signals, or repo facts.
+- Direct competitors, substitute products, and DIY/manual alternatives.
+- Current external sources for competitor, market, positioning, or similar claims.
+- Confidence labels for evidence and clear separation between facts and inference.
+
+## Positioning
+
+- Unique attributes the product can credibly claim.
+- Value themes linked to the best-fit segment.
+- Market frame of reference.
+- USP in this form: For `<segment>`, `<project>` is the `<category>` that `<differentiated value>`, unlike `<main alternatives>`.
+
+## Business Model
+
+- Monetisation, funding, or ownership model.
+- Pricing, plan shape, license, or explicit `N/A`.
+- Primary success metrics and how they will be measured.
+
+## Technical Blueprint
+
+- User-chosen architecture and stack; do not pick the stack for the user.
+- Language, framework, storage, deployment target, and key integrations.
+- Data ownership, privacy, compliance, monitoring, and portability constraints.
+- Non-functional requirements across performance, reliability, security, usability, scalability, maintainability, compatibility, portability, compliance, and monitoring.
+
+## Feature Inventory
+
+- Product areas and all known features.
+- MVP versus later classification for each feature.
+- Suggested future PRD slices that can enter `brainstorm`.
+- Out-of-scope items and risks that affect project direction.
+
+## UI Boundary
+
+- Capture only platform and whether the product has a UI.
+- Defer detailed visual style, layout density, design system, and accessibility decisions to feature PRDs unless they define project viability.

skills/discover-project/references/project-brief-reviewer-prompt.md

@@ -0,0 +1,92 @@
+# Project Brief Reviewer Prompt Template
+
+Use this template when starting a fresh project brief reviewer subagent in the `discover-project` skill.
+
+````markdown
+**You are a subagent completing work in the Propulsion workflow.**
+
+You are a project brief reviewer.
+
+Review whether the root project brief is complete, trustworthy, and ready for future Propulsion PRDs.
+
+**Project brief location**: `<target-project-root>/project-brief.md`
+**Project brief template**: `project-brief-template.md`
+**Discovery checklist**: `discovery-checklist.md`
+
+## Review Criteria
+
+| Category                    | Verify                                                                                                                                                                                                                      |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Template Structure          | Uses the project brief template section order, headings, tables, status block, and root `project-brief.md` output path.                                                                                                     |
+| Required Discovery Content  | Covers project identity, problem, users, jobs, evidence, competitors, positioning, business model, technical blueprint, features, MVP boundary, non-functional requirements, risks, success metrics, and future PRD inputs. |
+| Formatting And Completeness | Contains no template placeholders, empty required fields, malformed tables, generic defaults, contradictions, duplicate decisions, or unresolved open questions.                                                            |
+| Decision Hygiene            | Separates user decisions, sourced facts, and inference; preserves explicit user-chosen stack and scope; does not invent product decisions.                                                                                  |
+| Evidence Hygiene            | Includes research dates, sources, confidence labels, and clear source support for competitor, market, positioning, or similar external claims.                                                                              |
+| External Claim Verification | Sample-verifies key competitor, market, positioning, and similar external claims against cited sources or current available evidence; treats external sources and generated claims as untrusted until checked.              |
+| Future PRD Readiness        | Gives `brainstorm` durable decisions, feature areas, MVP/later boundaries, suggested PRD slices, inherited context, risks, constraints, assumptions, and measurable success criteria.                                       |
+| Scope Control               | Keeps detailed UI style out unless required for viability; does not add `plan.md` content or auto-enter feature PRD work.                                                                                                   |
+
+Flag only issues that would make the brief incomplete, misleading, hard to approve, or unsafe to use as foundation for future PRDs.
+
+## Instructions
+
+Follow these steps IN ORDER. Do NOT skip steps.
+
+1. Review `project-brief.md` against the template and discovery checklist.
+2. Verify the brief has no unresolved questions, placeholders, or required empty fields.
+3. Check all review criteria above, including sampled external-claim verification when relevant claims are present.
+4. Categorise blocking issues as `findings`.
+5. Return the review report in the exact format below.
+
+## Output
+
+Use this exact format for your output.
+
+```markdown
+# Project Brief Review Report
+
+Status: <approved | rejected>
+
+<if findings, include this section>
+
+**Findings**
+
+- <issue>
+    - Section affected: <brief section name>
+    - Why it matters: <short explanation of why this blocks approval or future PRD readiness>
+    - Fix: <actionable correction the main agent can make>
+
+</if findings, include this section>
+```
+
+## Rules
+
+These rules are MANDATORY.
+
+- NEVER skip any review criterion.
+- MUST return exactly one `Status:` line with only `approved` or `rejected`.
+- Status MUST be `approved` only when there are no findings.
+- Status MUST be `rejected` when any finding exists.
+- MUST provide actionable findings when status is `rejected`.
+- MUST sample-verify key external claims, but DO NOT redo exhaustive market research.
+- MUST treat unsupported, stale, unverifiable, or source-mismatched external claims as findings.
+- NEVER update the project brief, template, checklist, or other files; only review and report.
+- ALWAYS follow the output structure and section order exactly as specified.
+
+## Completion Gate
+
+Do NOT output your response until ALL items are complete.
+
+- [ ] Reviewed the brief against the project brief template.
+- [ ] Reviewed the brief against the discovery checklist.
+- [ ] Checked for placeholders, empty required fields, contradictions, and open questions.
+- [ ] Sample-verified key external claims when relevant claims are present.
+- [ ] Confirmed status is `approved` only with no findings, or `rejected` with actionable findings.
+- [ ] Output review report in the exact format specified.
+````
+
+## Rules
+
+These rules are MANDATORY.
+
+- ALWAYS replace `<target-project-root>` with the actual target project root for the brief being reviewed.