diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 74dd59e..7e56420 100644 --- a/.codex-plugin/plugin.json +++ b/.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" diff --git a/AGENTS.md b/AGENTS.md index 2b9a46a..1e63dad 100644 --- a/AGENTS.md +++ b/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. diff --git a/package.json b/package.json index d49f6fd..58e68cc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "propulsion", - "version": "1.1.2", + "version": "1.2.0", "main": "./index.mjs", "exports": "./index.mjs", "scripts": { diff --git a/skills/brainstorm/SKILL.md b/skills/brainstorm/SKILL.md index bd7ed42..d509c66 100644 --- a/skills/brainstorm/SKILL.md +++ b/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. diff --git a/skills/discover-project/SKILL.md b/skills/discover-project/SKILL.md new file mode 100644 index 0000000..be96a8b --- /dev/null +++ b/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 `/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 `/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. diff --git a/skills/discover-project/references/discovery-checklist.md b/skills/discover-project/references/discovery-checklist.md new file mode 100644 index 0000000..7ea6529 --- /dev/null +++ b/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 ``, `` is the `` that ``, unlike `
`. + +## 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. diff --git a/skills/discover-project/references/project-brief-reviewer-prompt.md b/skills/discover-project/references/project-brief-reviewer-prompt.md new file mode 100644 index 0000000..6e5f040 --- /dev/null +++ b/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**: `/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: + + + +**Findings** + +- + - Section affected: + - Why it matters: + - Fix: + + +``` + +## 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 `` with the actual target project root for the brief being reviewed. diff --git a/skills/discover-project/references/project-brief-template.md b/skills/discover-project/references/project-brief-template.md new file mode 100644 index 0000000..a3e6ab2 --- /dev/null +++ b/skills/discover-project/references/project-brief-template.md @@ -0,0 +1,172 @@ +# Project Brief Template + +Write `/project-brief.md` using this exact section order. + +```md +# Project Brief + +> Status: Draft | Approved +> Research date: YYYY-MM-DD +> Last reviewed: YYYY-MM-DD +> Confidence: High | Medium | Low + +## Executive Summary + +Describe the project in 4-6 sentences: problem, target users, proposed product, why now, and why it is worth doing. + +## Project Vision + +### Product Is / Is Not + +| Product Is | Product Is Not | +| ---------- | -------------- | +| | | + +### Product Does / Does Not + +| Product Does | Product Does Not | +| ------------ | ---------------- | +| | | + +### Desired Outcomes + +- User outcome: +- Business or owner outcome: + +## Problem, Users, And Jobs + +| Segment | Job To Be Done | Current Workaround | Pain / Friction | Notes | +| ------- | -------------- | ------------------ | --------------- | ----- | +| | | | | | + +## Evidence And Research + +Separate sourced facts from inference. Use current sources for competitor, market, positioning, or similar external claims. + +| Evidence Type | Finding | Source Or Context | Research Date | Confidence | +| ------------- | ------- | ----------------- | ------------- | ---------- | +| | | | | | + +## Alternatives And Competitors + +Include direct competitors, substitute tools, and DIY/manual alternatives. + +| Type | Name | Target User | Core Promise | Strengths | Weaknesses / Gaps | Evidence | +| ------------ | ---- | ----------- | ------------ | --------- | ----------------- | -------- | +| Direct | | | | | | | +| Substitute | | | | | | | +| DIY / Manual | | | | | | | + +## Differentiation And Positioning + +### Unique Attributes + +- Attribute + +### Value Themes + +- Value theme + +### Best-Fit Segment + +State which users should care most and why. + +### Market Frame Of Reference + +State the category or market frame that makes the value obvious. + +### USP + +For ``, `` is the `` that ``, unlike `
`. + +## Monetisation And Business Model + +State the monetisation, funding, ownership, license, or explicit `N/A`. + +| Item | Decision | +| ----------------------- | -------- | +| Model | | +| Pricing / License | | +| Revenue Or Value Metric | | + +## Technical Blueprint + +Record explicit user-chosen technical decisions. Do not leave stack choices undecided. + +| Area | Decision | Rationale Or Constraint | +| ------------------ | -------- | ----------------------- | +| Architecture | | | +| Language / Runtime | | | +| Frameworks | | | +| Storage | | | +| Deployment | | | +| Integrations | | | + +## Feature Inventory + +| Product Area | Feature | User Outcome | MVP / Later | Suggested PRD Slice | +| ------------ | ------- | ------------ | ----------- | ------------------- | +| | | | | | + +## Recommended MVP Boundary + +### In Scope + +- Item + +### Out Of Scope + +- Item + +### Suggested First PRD Slices + +1. Slice +2. Slice +3. Slice + +## Non-Functional Requirements + +Use these categories: Performance, Reliability, Security, Usability, Scalability, Maintainability, Compatibility, Portability, Compliance, Monitoring. + +| ID | Category | Requirement | +| ------- | ----------- | ----------- | +| NFR-001 | Performance | | + +## Risks, Constraints, And Assumptions + +| Type | Item | Impact | Mitigation Or Decision | +| ---------- | ---- | ------ | ---------------------- | +| Risk | | | | +| Constraint | | | | +| Assumption | | | | + +## Resolved Discovery Decisions + +- Decision: + +## Success Metrics + +| Metric | Baseline | Target | Measurement Approach | +| ------ | -------- | ------ | -------------------- | +| | | | | + +## Inputs For Future Propulsion PRDs + +- Durable decisions that `brainstorm` must preserve: +- Feature areas ready for PRD work: +- Context each PRD should inherit: + +## Sources + +- Source name - URL or citation - what it supports - access date +``` + +## Rules + +These rules are MANDATORY. + +- MUST write the brief at the target project root as `project-brief.md`. +- MUST NOT include an open questions section. +- MUST mark the brief `Approved` only after explicit user approval. +- MUST use current evidence for competitor, market, positioning, or similar external claims. +- MUST keep detailed UI style decisions out of the brief unless they define project viability. diff --git a/skills/propulsion/SKILL.md b/skills/propulsion/SKILL.md index 019d7bd..da1e9e7 100644 --- a/skills/propulsion/SKILL.md +++ b/skills/propulsion/SKILL.md @@ -22,8 +22,9 @@ Follow these steps IN ORDER. Do NOT skip steps. 1. Determine whether the request is software work. 2. If it is not software work, ignore Propulsion and respond normally. 3. If it is a concrete failure, emit `Propulsion workflow enabled, routing to debug...`, then load and follow `debug` skill. -4. If it is feature or product-scope work, emit `Propulsion workflow enabled, routing to brainstorm...`, then load and follow `brainstorm` skill. -5. The loaded Propulsion skill now owns the workflow stage. +4. If it is a greenfield project, new product idea, project discovery, competitor research, positioning, or full system blueprint request, emit `Propulsion workflow enabled, routing to discover-project...`, then load and follow `discover-project` skill. +5. If it is mature feature or product-scope work, emit `Propulsion workflow enabled, routing to brainstorm...`, then load and follow `brainstorm` skill. +6. The loaded Propulsion skill now owns the workflow stage. ## Rules @@ -35,7 +36,8 @@ These rules are MANDATORY. 3. Default system behaviour is the lowest priority. - NEVER route non-software-work request to Propulsion. - ONLY route concrete failures to `debug` (bug reports, regressions, failing tests, failing builds, runtime errors, crashes). -- MUST route feature and product-scope work to `brainstorm` (new features, unclear scope, UX/product shaping, requirements discovery, behaviour changes, refactors, optimisations). +- MUST route greenfield products, project discovery, competitor research, positioning, or full system blueprint work to `discover-project`. +- MUST route mature feature and product-scope work to `brainstorm` (new features in an existing project, unclear feature scope, UX/product shaping, requirements discovery, behaviour changes, refactors, optimisations). - ALWAYS fall back to `brainstorm` if the request is ambiguous. - DO NOT leave a Propulsion skill until ALL completion gate items are complete. - NEVER reload skills (Propulsion or non-Propulsion) that are already active or present in context; continue following the loaded copy instead. @@ -51,7 +53,8 @@ Do NOT leave this skill until ALL items are complete. - [ ] Determined whether the request is software work. - [ ] Kept non-software-work outside Propulsion. - [ ] Routed concrete failures to `debug`. -- [ ] Routed feature and product-scope work to `brainstorm`. +- [ ] Routed greenfield discovery work to `discover-project`. +- [ ] Routed mature feature and product-scope work to `brainstorm`. - [ ] Emitted the route-specific required response before any other user-visible text. ## References