@pareto4/pp-core 1.7.1 → 1.8.1

package/pareto-skills/pp-project-setup/SKILL.md

@@ -0,0 +1,1364 @@
+---
+name: pp-project-setup
+description: >
+  Use this skill whenever a user wants to start a new project, set up a new client engagement,
+  or create a new repo with discovery framework. Trigger on phrases like
+  "new project", "start a project", "create a repo", "set up a client project",
+  "new engagement", or "initialise a project". This skill runs a wizard
+  that collects project and client context, then automates: GitHub repo creation (via gh CLI),
+  Discovery Sprint framework (13 interactive session templates + methodology guide),
+  Obsidian vault configuration, requirements templates, GitHub project board setup,
+  and an initial commit pushed to GitHub — leaving the team ready to start Discovery immediately.
+  Trigger even for vague requests like "let's start a new project" or "new client, new repo".
+---
+
+# Pareto Project Setup Skill
+## From Zero to Discovery — Fully Automated
+
+This skill bootstraps a new Pareto project with a complete Discovery Sprint framework.
+
+**What it delivers:**
+- GitHub repository created and configured
+- Discovery Sprint framework (13 interactive session templates + methodology guide)
+- Prototype folder structure (interactive HTML prototype, created during Discovery after Session 4)
+- Obsidian vault configured for project documentation
+- Requirements templates (functional requirements, user stories, test cases)
+- Project Definition template
+- GitHub project board with labels, milestone, and custom fields
+- Initial commit pushed to GitHub
+- Team ready to start Discovery Sprint immediately
+
+**What it does NOT do:**
+- Application scaffolding (backend/frontend code) — do this after Discovery, when the stack is confirmed
+- CI/CD pipeline setup — use `pareto-cicd-setup` after the application is scaffolded
+- Deployment setup — use `pareto-deploy-setup` when ready for staging/production
+
+**Mantra: Discover first, then build.**
+
+---
+
+## Prerequisites
+
+Verify these are available before starting. If any are missing, tell the user
+and provide the install command before proceeding:
+
+```bash
+# Check all prerequisites
+gh --version          # GitHub CLI — brew install gh / winget install GitHub.cli
+git --version         # Git
+```
+
+Also verify GitHub CLI is authenticated:
+```bash
+gh auth status
+```
+
+If not authenticated: `gh auth login` — walk the user through this before continuing.
+
+---
+
+## Wizard Flow
+
+Run **one step at a time**. Acknowledge each answer before moving on.
+Generate and execute all commands together at the end of the wizard.
+
+---
+
+### STEP 1 — Project Identity
+
+Ask:
+> "Let's set up your new Pareto project. A few quick questions first.
+>
+> What's the **project name**? This will become the GitHub repo name and folder name.
+> Use lowercase with hyphens (e.g. `jumbo-asset-portal`, `nxp-supplier-hub`)"
+
+Then ask:
+> "Who is the **client**?"
+
+Then ask:
+> "One sentence describing what this application does — for the README and repo description."
+
+Store as:
+- `PROJECT_NAME` — slugified, lowercase, hyphens (e.g. `jumbo-asset-portal`)
+- `CLIENT_NAME` — display name (e.g. `Jumbo`)
+- `PROJECT_DESCRIPTION` — one sentence
+
+---
+
+### STEP 2 — GitHub Organisation
+
+Ask:
+> "Where should the repo live on GitHub?"
+
+Options:
+- **Pareto organisation** (`github.com/pareto000/[project-name]`) ← default
+- **Client organisation** → ask for org name
+- **Personal account** → confirm username
+
+Store as `GITHUB_ORG`. Default is `pareto000`.
+
+Ask:
+> "Should the repo be **private**?"
+
+Default: **Yes — always private for client work.**
+Only allow public if user explicitly confirms client has agreed.
+
+Store as `REPO_VISIBILITY`. Default is `private`.
+
+---
+
+### STEP 3 — Confirmation Before Execution
+
+Summarise everything before running any commands:
+
+> "Here's what I'm about to create:
+>
+> 📁 **Project**: `[PROJECT_NAME]`
+> 👤 **Client**: `[CLIENT_NAME]`
+> 📝 **Description**: `[PROJECT_DESCRIPTION]`
+> 🐙 **GitHub**: `github.com/[GITHUB_ORG]/[PROJECT_NAME]` (private)
+>
+> I'll:
+> 1. Create the GitHub repo
+> 2. Scaffold the project structure (Discovery + requirements + docs)
+> 3. Set up Discovery Sprint framework (13 session templates + methodology guide)
+> 4. Configure Obsidian vault for project documentation
+> 5. Set up requirements templates
+> 6. Configure GitHub project board, labels, and milestone
+> 7. Push the initial commit to GitHub
+>
+> Ready to go?"
+
+Only proceed after explicit confirmation.
+
+---
+
+### STEP 4 — Execute
+
+Run all commands in sequence. Show each command before running it.
+If any step fails, stop and report the error clearly with a fix suggestion.
+
+#### 4a. Create GitHub Repository
+
+```bash
+gh repo create [GITHUB_ORG]/[PROJECT_NAME] \
+  --description "[PROJECT_DESCRIPTION]" \
+  --private \
+  --clone
+cd [PROJECT_NAME]
+```
+
+#### 4b. Scaffold Folder Structure
+
+```bash
+mkdir -p \
+  Discovery \
+  prototype/src/components \
+  prototype/src/pages \
+  prototype/src/styles \
+  prototype/src/assets \
+  requirements \
+  Inputs/docs \
+  docs/architecture \
+  docs/decisions \
+  .obsidian
+```
+
+#### 4c. Scaffold Discovery Framework
+
+Generate all discovery, requirements, and project definition files. These are **interactive facilitation templates** — by working through all 13 sessions via guided Q&A, the team produces a comprehensive project definition, prioritized backlog, architecture decisions, and go/no-go assessment.
+
+**Generation order:** Guide first → tracking files → session files → Project Definition → requirements.
+
+##### 4c.1 Discovery Sessions Guide
+
+Generate `[PROJECT_NAME]-Discovery-Sessions-Guide.md` in the project root.
+
+This is the **complete Discovery Sprint methodology guide** containing all 13 session definitions. Generate the full guide with this structure:
+
+- **Title:** `# [PROJECT_NAME] Discovery Sprint Sessions Guide`
+- **Version:** 1.0, **Date:** current month and year
+- **Overview:** What is the Discovery Sprint, what it focuses on, expected outcome
+- **Session Schedule:** Overview table (all 13 sessions) + example 2-week schedule
+- **4 Parts with full session definitions:**
+
+| Part | Sessions | Category |
+|------|----------|----------|
+| Part 1: Introduction & Closure | 1, 13 | Kick-off and Wrap-up |
+| Part 2: Business Functional | 2, 3, 4 | As-Is, To-Be, UX |
+| Part 3: Technical | 5, 6, 7, 8, 9, 10 | Architecture, Security, Identity, Integration, QA, Infrastructure |
+| Part 4: Governance & Costs | 11, 12 | Roadmap, Team & Delivery |
+
+Each session section **must** include:
+1. **Goal** — what this session achieves
+2. **What We Cover** — numbered topic list with guiding questions (these drive the Q&A dialog)
+3. **Pre-requisites** — checklist of what's needed before starting
+4. **Outcomes / Deliverables** — checklist of what the session produces
+5. **Agenda Template** — time-boxed topic table
+6. **Notes Template** — structured tables for capturing session outputs (these are the key interactive elements — each table becomes a worksheet to fill in)
+
+End with:
+- **Deliverables Checklist** (Project Definition Document + Supporting Artifacts + Prioritized Product Backlog)
+- **How to Use This Guide** section
+
+**Reference the complete session definitions from the Pareto Discovery Sprint methodology (see 21Assets Discovery Sessions Guide for the canonical structure).**
+
+##### 4c.2 Cross-Session Context File
+
+Generate `Discovery/_context.md`:
+
+```markdown
+# Cross-Session Context — [PROJECT_NAME]
+
+This file accumulates key outputs from each completed session to provide context for subsequent sessions. It is automatically maintained as sessions are completed.
+
+---
+
+## Session 1: Kick-off Outputs
+_Populated after Session 1 completion_
+
+### Project Context
+<!-- Notes about the rationale and context -->
+
+### Business Vision
+<!-- Business vision summary, KPIs -->
+
+### Stakeholders
+<!-- Key stakeholder list with roles -->
+
+### Discovery Sprint Scope
+**In Scope:**
+-
+
+**Out of Scope:**
+-
+
+---
+
+## Session 2: As-Is Outputs
+_Populated after Session 2 completion_
+
+### Core Processes
+<!-- Current business processes -->
+
+### Pain Points
+<!-- Prioritized pain points -->
+
+### User Personas
+<!-- Key personas and their journeys -->
+
+### Current Systems
+<!-- Systems landscape -->
+
+### Data Flows
+<!-- How information moves today -->
+
+---
+
+## Session 3: To-Be Outputs
+_Populated after Session 3 completion_
+
+### Business Objectives
+<!-- Measurable outcomes and KPIs -->
+
+### MVP Scope
+<!-- What's in/out for MVP -->
+
+### EPICs Summary
+<!-- EPIC registry table -->
+
+### User Stories Summary
+<!-- Story count and distribution -->
+
+### Requirements Summary
+<!-- FR, NFR, BR counts -->
+
+---
+
+## Session 4: UX Design Outputs
+_Populated after Session 4 completion_
+
+### Design Principles
+<!-- Numbered design principles -->
+
+### UX Standards
+<!-- Platform, navigation, language, accessibility -->
+
+### Key Personas (Refined)
+<!-- Persona categories and interaction patterns -->
+
+### Key Screen Decisions
+<!-- Screen layout decisions -->
+
+---
+
+## Session 5: Architecture Outputs
+_Populated after Session 5 completion_
+
+### Target Architecture
+<!-- Platform, architecture style, ownership -->
+
+### Technology Stack
+<!-- Full stack listing -->
+
+### Key Components
+<!-- Module/component list -->
+
+### Integration Points
+<!-- External system integrations -->
+
+### ADRs
+<!-- Architecture Decision Records -->
+
+---
+
+## Session 6: Security Outputs
+_Populated after Session 6 completion_
+
+### Data Classification
+<!-- Data sensitivity levels -->
+
+### Compliance Framework
+<!-- Standards and regulations -->
+
+### Encryption
+<!-- In-transit, at-rest, key management -->
+
+### Network & Access
+<!-- Network security approach -->
+
+### Audit Logging
+<!-- Logging strategy and retention -->
+
+### Availability
+<!-- SLA targets -->
+
+---
+
+## Session 7: Identity Management Outputs
+_Populated after Session 7 completion_
+
+### RBAC Model
+<!-- Roles and permissions summary -->
+
+### IdP Integration
+<!-- Identity provider details -->
+
+### User Lifecycle
+<!-- Provisioning approach -->
+
+---
+
+## Session 8: Integration Outputs
+_Populated after Session 8 completion_
+
+### External Systems
+<!-- Systems and their interfaces -->
+
+### Interface Patterns
+<!-- Chosen patterns and protocols -->
+
+### Data Exchange
+<!-- Key data flows and formats -->
+
+---
+
+## Session 9: QA Outputs
+_Populated after Session 9 completion_
+
+### Test Strategy
+<!-- Testing approach -->
+
+### Tooling
+<!-- Test management and automation tools -->
+
+### Test Environments
+<!-- Environment list and purposes -->
+
+### Quality Gates
+<!-- Gate definitions -->
+
+### UAT
+<!-- UAT participants, period, criteria -->
+
+---
+
+## Session 10: Infrastructure Outputs
+_Populated after Session 10 completion_
+
+### Infrastructure
+<!-- Cloud/hosting setup -->
+
+### Deployment
+<!-- Deployment strategy -->
+
+### Monitoring
+<!-- Monitoring and alerting approach -->
+
+### Backup & DR
+<!-- Backup and disaster recovery -->
+
+### Go-Live Readiness
+<!-- Readiness checklist status -->
+
+---
+
+## Session 11: Roadmap Outputs
+_Populated after Session 11 completion_
+
+### Project Phases
+<!-- Phase breakdown -->
+
+### Timeline
+<!-- Sprint cadence and key dates -->
+
+### MVP Scope (Confirmed)
+<!-- Must-have vs nice-to-have -->
+
+### Build Order
+<!-- Sprint-by-sprint plan -->
+
+### Key Milestones
+<!-- Milestone dates -->
+
+### Risks
+<!-- Top risks and mitigations -->
+
+---
+
+## Session 12: Delivery Model Outputs
+_Populated after Session 12 completion_
+
+### Team Structure
+<!-- Key roles and people -->
+
+### Governance
+<!-- Governance framework summary -->
+
+### Ceremonies
+<!-- Sprint cadence and meetings -->
+
+### Support Model
+<!-- Post-go-live support approach -->
+
+---
+
+## Session 13: Wrap-up Outputs
+_Populated after Session 13 completion_
+
+### Decision Readiness
+<!-- Go / Conditional Go / No-Go assessment -->
+
+### Open Items
+<!-- Items carried forward -->
+
+### Next Steps
+<!-- Transition plan to execution -->
+```
+
+##### 4c.3 Progress Tracker
+
+Generate `Discovery/_progress.md`:
+
+```markdown
+# Discovery Sprint Progress — [PROJECT_NAME]
+
+**Project:** [PROJECT_NAME]
+**Client:** [CLIENT_NAME]
+**Created:** [today's date]
+**Last Updated:** [today's date]
+**Overall Status:** Not Started
+
+---
+
+## Session Progress
+
+| # | Session | Category | Status | Started | Completed | Score | Notes |
+|---|---------|----------|--------|---------|-----------|-------|-------|
+| 1 | Discovery Sprint Kick-off | Introduction & Closure | Not Started | | | | |
+| 2 | Business Process Mapping (As-Is) | Business Functional | Not Started | | | | |
+| 3 | Business Requirements (To-Be) | Business Functional | Not Started | | | | |
+| 4 | UX Design Principles | Business Functional | Not Started | | | | |
+| 5 | Application & Integration Architecture | Technical | Not Started | | | | |
+| 6 | Security & Compliance | Technical | Not Started | | | | |
+| 7 | User & Identity Management | Technical | Not Started | | | | |
+| 8 | Integration & Interface Design | Technical | Not Started | | | | |
+| 9 | QA & Testing Strategy | Technical | Not Started | | | | |
+| 10 | Infrastructure & Deployment | Technical | Not Started | | | | |
+| 11 | Roadmap & Release Planning | Governance & Costs | Not Started | | | | |
+| 12 | Team & Delivery Model | Governance & Costs | Not Started | | | | |
+| 13 | Discovery Sprint Wrap-up | Introduction & Closure | Not Started | | | | |
+
+---
+
+## Summary
+
+- **Completed:** 0/13
+- **In Progress:** 0/13
+- **Not Started:** 13/13
+
+---
+
+## Open Action Items
+
+| Action | From Session | Owner | Due Date | Status |
+|--------|-------------|-------|----------|--------|
+| | | | | |
+```
+
+##### 4c.4 Session Files (13 files)
+
+Generate one file per session in the `Discovery/` folder. Use this **session registry** for metadata:
+
+| # | Filename | Session Name | Category | Duration | Dependencies |
+|---|----------|-------------|----------|----------|-------------|
+| 1 | `01-discovery-sprint-kickoff.md` | Discovery Sprint Kick-off | Introduction & Closure | 2 hours | — |
+| 2 | `02-business-process-mapping-as-is.md` | Business Process Mapping (As-Is) | Business Functional | 2-3 hours | 1 |
+| 3 | `03-business-requirements-to-be.md` | Business Requirements & Future State (To-Be) | Business Functional | 2-3 hours | 1, 2 |
+| 4 | `04-ux-design-principles.md` | UX Design & User Experience Principles | Business Functional | 2-3 hours | 2, 3 |
+| 5 | `05-application-integration-architecture.md` | Application & Integration Architecture | Technical | 1.5-2 hours | 1, 2, 3, 4 |
+| 6 | `06-security-compliance-setup.md` | Security & Compliance Setup | Technical | 1.5-2 hours | 5 |
+| 7 | `07-user-identity-management.md` | User & Identity Management | Technical | 1.5-2 hours | 5, 6 |
+| 8 | `08-integration-interface-design.md` | Integration & Interface Design | Technical | 1.5-2 hours | 5 |
+| 9 | `09-quality-assurance-testing.md` | Quality Assurance & Testing Strategy | Technical | 1.5-2 hours | 3, 5 |
+| 10 | `10-infrastructure-deployment-readiness.md` | Infrastructure & Deployment Readiness | Technical | 1.5-2 hours | 5 |
+| 11 | `11-project-roadmap-release-planning.md` | Project Roadmap & Release Planning | Governance & Costs | 1-2 hours | 3, 5, 9 |
+| 12 | `12-team-delivery-model.md` | Team & Delivery Model Definition | Governance & Costs | 1-2 hours | 11 |
+| 13 | `13-discovery-sprint-wrapup.md` | Discovery Sprint Wrap-up & Next Steps | Introduction & Closure | 2 hours | 1-12 |
+
+**Each session file must contain:**
+
+1. **YAML frontmatter:**
+```yaml
+---
+session_number: [N]
+session_name: "[Session Name]"
+category: "[Category]"
+duration: "[Duration]"
+dependencies: [list]
+status: "Not Started"
+project_name: "[PROJECT_NAME]"
+started_date: ""
+completed_date: ""
+completeness_score: 0
+---
+```
+
+2. **Title:** `# Session [N] — [Session Name] — [PROJECT_NAME]`
+
+3. **Goal section:** The session's purpose — what it achieves and why it matters. This should describe the business value of completing this session.
+
+4. **What We Cover section:** Numbered topic list with **guiding questions** under each topic. These are the facilitation prompts that drive the Q&A dialog. For example, Session 1 covers: Project Context (What is happening? What problems?), Business Vision (Desired future state, KPIs), Stakeholders (Who decides? Who provides input?), Discovery Sprint Approach.
+
+5. **Pre-requisites:** Checklist of what must be ready before the session starts.
+
+6. **Outcomes / Deliverables:** Checklist of concrete outputs this session produces.
+
+7. **Notes Template:** The **structured tables** matching the Notes Template from the Discovery Sessions Guide for this specific session. These tables are the key interactive element — they get populated through the Q&A process. Include all relevant tables for the session (e.g., Session 2 has: Core Processes table, User Personas table, Pain Points table, Data Flow table, Current Systems table).
+
+8. **Key Decisions table:**
+```markdown
+| Decision | Rationale | Owner |
+|----------|-----------|-------|
+|          |           |       |
+```
+
+9. **Action Items table:**
+```markdown
+| Action | Owner | Deadline | Status |
+|--------|-------|----------|--------|
+|        |       |          |        |
+```
+
+10. **Footer:** Session date, Duration, Facilitator placeholders.
+
+**Reference the Discovery Sessions Guide for the exact content of each session's Goal, What We Cover, and Notes Template sections.**
+
+##### 4c.5 Project Definition Template
+
+Generate `[PROJECT_NAME]-Project-Definition.md`:
+
+```markdown
+# [PROJECT_NAME] — Project Definition
+
+> [PROJECT_DESCRIPTION]
+
+**Client:** [CLIENT_NAME]
+**Version:** 1.0
+**Date:** [today's date]
+**Status:** Draft — populated through Discovery Sprint sessions
+
+---
+
+## Table of Contents
+
+1. Executive Summary
+2. Project Context
+3. Solution Architecture
+4. Functional Requirements
+5. User Roles & Access Control
+6. Integration & Interfaces
+7. Security & Compliance
+8. Team & Governance
+9. Project Roadmap
+10. Licensing & Costs
+11. Risks & Mitigations
+12. Appendices
+
+---
+
+## 1. Executive Summary
+
+### Business Rationale
+<!-- Why this project? What problem does it solve? -->
+
+### Key Objectives
+
+| Objective | Description | Expected Improvement |
+|-----------|-------------|---------------------|
+|           |             |                     |
+
+### Success Criteria / KPIs
+
+| KPI | Target | Measurement |
+|-----|--------|-------------|
+|     |        |             |
+
+---
+
+## 2. Project Context
+
+### Current State (As-Is)
+<!-- From Session 2 -->
+
+### Future State (To-Be)
+<!-- From Session 3 -->
+
+### Scope Definition
+
+**In Scope (MVP):**
+-
+
+**Out of Scope:**
+-
+
+---
+
+## 3. Solution Architecture
+
+### System Overview
+<!-- From Session 5 -->
+
+### Technology Stack
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Backend |         |       |
+| Frontend |        |       |
+| Database |        |       |
+| Infrastructure | |       |
+
+### Architecture Decision Records
+
+| ADR | Decision | Context | Consequences |
+|-----|----------|---------|--------------|
+|     |          |         |              |
+
+---
+
+## 4. Functional Requirements
+
+See [requirements/functional-requirements.md](requirements/functional-requirements.md) for the full requirements matrix.
+
+### EPICs Overview
+
+| EPIC | Title | Phase | Priority |
+|------|-------|-------|----------|
+|      |       |       |          |
+
+### Requirements Summary
+
+| Category | Count |
+|----------|-------|
+| Functional Requirements | |
+| Non-Functional Requirements | |
+| Business Rules | |
+
+---
+
+## 5. User Roles & Access Control
+
+<!-- From Sessions 3, 7 -->
+
+| Role | Description | Permissions | Device |
+|------|-------------|-------------|--------|
+|      |             |             |        |
+
+---
+
+## 6. Integration & Interfaces
+
+<!-- From Sessions 5, 8 -->
+
+| Interface | System | Direction | Protocol | Phase |
+|-----------|--------|-----------|----------|-------|
+|           |        |           |          |       |
+
+---
+
+## 7. Security & Compliance
+
+<!-- From Session 6 -->
+
+| Aspect | Approach | Standard |
+|--------|----------|----------|
+| Data Classification | | |
+| Compliance | | |
+| Encryption (transit) | | |
+| Encryption (at rest) | | |
+| Authentication | | |
+| Audit Logging | | |
+| Availability SLA | | |
+
+---
+
+## 8. Team & Governance
+
+<!-- From Session 12 -->
+
+### Team Structure
+
+| Role | Who | Organization |
+|------|-----|--------------|
+|      |     |              |
+
+### Governance Framework
+
+| Level | Forum | Frequency | Purpose |
+|-------|-------|-----------|---------|
+|       |       |           |         |
+
+---
+
+## 9. Project Roadmap
+
+<!-- From Session 11 -->
+
+### Phases
+
+| Phase | Scope | Timeline | Budget |
+|-------|-------|----------|--------|
+|       |       |          |        |
+
+### Key Milestones
+
+| Milestone | Target Date | Owner |
+|-----------|-------------|-------|
+|           |             |       |
+
+---
+
+## 10. Licensing & Costs
+
+| Item | Cost | Frequency | Notes |
+|------|------|-----------|-------|
+|      |      |           |       |
+
+---
+
+## 11. Risks & Mitigations
+
+| Risk | Probability | Impact | Mitigation | Owner |
+|------|-------------|--------|------------|-------|
+|      |             |        |            |       |
+
+---
+
+## 12. Appendices
+
+- [Discovery Sessions Guide]([PROJECT_NAME]-Discovery-Sessions-Guide.md)
+- [Functional Requirements](requirements/functional-requirements.md)
+- [User Story Definition Guide](requirements/user-story-definition.md)
+- [Test Cases](requirements/test-cases.md)
+
+---
+
+**Document Status:** Draft
+**Generated by:** pareto-project-setup skill
+```
+
+##### 4c.6 Requirements Files
+
+Generate `requirements/functional-requirements.md`:
+
+```markdown
+# Functional Requirements — [PROJECT_NAME]
+
+Based on: [PROJECT_NAME] Discovery Sprint (Sessions 3, 5, 8)
+
+## How to Use This Document
+
+Requirements are captured during the Discovery Sprint, primarily in Session 3 (Business Requirements & To-Be).
+Each requirement has a unique ID, description, phase assignment, and priority.
+
+---
+
+## 1. [Module Name]
+
+### 1.1 [Sub-module]
+
+| ID | Requirement | Phase | Priority | Notes |
+|----|-------------|-------|----------|-------|
+| REQ-001 | | | | |
+
+---
+
+## Non-Functional Requirements
+
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | | |
+| NFR-002 | Security | | |
+| NFR-003 | Usability | | |
+| NFR-004 | Availability | | |
+
+---
+
+## Business Rules
+
+| ID | Rule Description | Applies To | Source |
+|----|-----------------|------------|--------|
+| BR-001 | | | |
+
+---
+
+## Out of Scope
+
+The following items are explicitly out of scope:
+-
+```
+
+Generate `requirements/user-story-definition.md` — this is the **full methodology guide** (reusable as-is across all projects). Include the complete User Story Definition Guide with:
+- Hierarchy: Epic → User Story → Acceptance Criteria → Test Case
+- Epic Definition (template, quality criteria, example)
+- User Story Definition (format, template, INVEST criteria, checklist, forbidden words)
+- Acceptance Criteria Definition (Given/When/Then + Concrete Condition formats)
+- Test Case Definition (template, test types, quality criteria)
+- Traceability Matrix
+- Status Definitions
+- Numbering Conventions
+- Review Checklists
+
+Generate `requirements/test-cases.md`:
+
+```markdown
+# Test Cases — [PROJECT_NAME]
+
+## Structure
+
+```
+TC-[US-ID]-[NR]: [Title]
+├── Test Type: Unit | Integration | E2E | Performance | Security
+├── User Story: US-XXX
+├── Acceptance Criterion: AC-XXX-XX
+├── Priority: Critical | High | Medium | Low
+├── Preconditions
+├── Test Steps
+├── Expected Result
+└── Test Data
+```
+
+## Test Phases
+
+| Phase | Focus | Responsibility |
+|-------|-------|----------------|
+| Unit Testing | Individual functions/components | Development team |
+| Integration Testing | Component collaboration | Development team |
+| System Testing | Complete system flows | QA team |
+| UAT | Business acceptance | Key users + PO |
+| Performance Testing | Speed and load | QA team |
+| Security Testing | Vulnerability assessment | Security team |
+
+## Test Cases
+
+_Test cases are added here as user stories are defined during the Discovery Sprint._
+
+| TC ID | User Story | AC | Type | Priority | Status |
+|-------|------------|-----|------|----------|--------|
+| | | | | | |
+```
+
+##### 4c.7 Prototype README
+
+Generate `prototype/README.md`:
+
+```markdown
+# Interactive Prototype — [PROJECT_NAME]
+
+This folder contains the interactive HTML prototype for [PROJECT_NAME].
+The prototype is a core Discovery Sprint deliverable — it makes abstract requirements tangible
+and gives stakeholders something concrete to react to.
+
+## When It Gets Built
+
+The prototype is **created after Discovery Session 4** (UX Design Principles) and
+**iteratively updated** after Sessions 5, 7, and 8. By Session 13, it reflects the full MVP scope.
+
+| Trigger Session | What Happens |
+|----------------|--------------|
+| Session 4 (UX Design) | **Create** — key screens, navigation, user flows based on personas, EPICs, and UX principles |
+| Session 5 (Architecture) | **Update** — reflect architecture decisions (component structure, data flow) |
+| Session 7 (Identity) | **Update** — add role-based views, login flow, permission-gated UI |
+| Session 8 (Integration) | **Update** — add integration touchpoints (document uploads, external system indicators) |
+
+## Structure
+
+```
+prototype/
+├── index.html              # Entry point — links to all screens
+├── src/
+│   ├── components/         # Reusable UI components (header, sidebar, cards, etc.)
+│   ├── pages/              # Individual screen HTML files
+│   ├── styles/
+│   │   ├── tokens.css      # Design tokens (colors, fonts, spacing) from brand
+│   │   ├── global.css      # Base styles, resets, typography
+│   │   └── components.css  # Component-specific styles
+│   └── assets/             # Images, icons, logos
+└── README.md               # This file
+```
+
+## How to View
+
+Open `index.html` in any browser. No build tools or dependencies required.
+
+## Principles
+
+1. **Interactive, not static** — working navigation, hover states, clickable elements
+2. **Realistic content** — domain-specific placeholder data, not Lorem ipsum
+3. **Progressive fidelity** — starts with layout/navigation, gains detail with each session
+4. **Annotated** — subtle references to requirement IDs (FR-xxx, US-xxx) for traceability
+5. **Branded** — uses the customer's brand tokens (colors, typography, logo)
+```
+
+##### 4c.8 Input Documents
+
+Create `Inputs/docs/.gitkeep` (empty file — placeholder for input documents, architecture notes, and reference materials gathered during discovery).
+
+---
+
+#### 4d. Set Up Obsidian Vault
+
+Configure the project as an Obsidian vault with the README as landing page.
+
+**`.obsidian/app.json`**
+```json
+{
+  "pdfExportSettings": {
+    "includeName": true,
+    "pageSize": "Letter",
+    "landscape": false,
+    "margin": "0",
+    "downscalePercent": 100
+  },
+  "alwaysUpdateLinks": true
+}
+```
+
+**`.obsidian/appearance.json`**
+```json
+{}
+```
+
+**`.obsidian/core-plugins.json`**
+```json
+{
+  "file-explorer": true,
+  "global-search": true,
+  "switcher": true,
+  "graph": true,
+  "backlink": true,
+  "canvas": true,
+  "outgoing-link": true,
+  "tag-pane": true,
+  "footnotes": false,
+  "properties": true,
+  "page-preview": true,
+  "daily-notes": true,
+  "templates": true,
+  "note-composer": true,
+  "command-palette": true,
+  "slash-command": false,
+  "editor-status": true,
+  "bookmarks": true,
+  "markdown-importer": false,
+  "zk-prefixer": false,
+  "random-note": false,
+  "outline": true,
+  "word-count": true,
+  "slides": false,
+  "audio-recorder": false,
+  "workspaces": false,
+  "file-recovery": true,
+  "publish": false,
+  "sync": true,
+  "bases": true,
+  "webviewer": false
+}
+```
+
+**`.obsidian/workspace.json`**
+```json
+{
+  "main": {
+    "id": "main-tabs",
+    "type": "split",
+    "children": [
+      {
+        "id": "tab-group",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "readme-tab",
+            "type": "leaf",
+            "state": {
+              "type": "markdown",
+              "state": {
+                "file": "README.md",
+                "mode": "source",
+                "source": false
+              },
+              "icon": "lucide-file",
+              "title": "README"
+            }
+          }
+        ]
+      }
+    ],
+    "direction": "vertical"
+  },
+  "left": {
+    "id": "left-sidebar",
+    "type": "split",
+    "children": [
+      {
+        "id": "left-tabs",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "file-explorer-tab",
+            "type": "leaf",
+            "state": {
+              "type": "file-explorer",
+              "state": { "sortOrder": "alphabetical" },
+              "icon": "lucide-folder-closed",
+              "title": "Files"
+            }
+          },
+          {
+            "id": "search-tab",
+            "type": "leaf",
+            "state": {
+              "type": "search",
+              "state": { "query": "" },
+              "icon": "lucide-search",
+              "title": "Search"
+            }
+          }
+        ]
+      }
+    ],
+    "direction": "horizontal",
+    "width": 300
+  },
+  "right": {
+    "id": "right-sidebar",
+    "type": "split",
+    "children": [
+      {
+        "id": "right-tabs",
+        "type": "tabs",
+        "children": [
+          {
+            "id": "outline-tab",
+            "type": "leaf",
+            "state": {
+              "type": "outline",
+              "state": { "file": "README.md" },
+              "icon": "lucide-list",
+              "title": "Outline"
+            }
+          }
+        ]
+      }
+    ],
+    "direction": "horizontal",
+    "width": 300,
+    "collapsed": true
+  },
+  "active": "readme-tab",
+  "lastOpenFiles": ["README.md"]
+}
+```
+
+---
+
+#### 4e. Generate Root Files
+
+Create the following files in the project root:
+
+**`README.md`**
+```markdown
+# [PROJECT_NAME]
+
+> [PROJECT_DESCRIPTION]
+
+**Client**: [CLIENT_NAME]
+**Delivery**: Pareto AI-First — Discovery → Requirements → Delivery → Validation
+
+## Discovery Sprint
+
+This project includes a complete Discovery Sprint framework. Open this folder in **Obsidian** to start.
+
+**How it works:**
+1. Open the project folder as an Obsidian vault
+2. Navigate to `Discovery/` and begin with Session 1 (Kick-off)
+3. Work through all 13 sessions via guided Q&A
+4. Use `[PROJECT_NAME]-Discovery-Sessions-Guide.md` for facilitation guidance
+5. Track progress in `Discovery/_progress.md`
+
+**Outcome:** A validated project definition, prioritized backlog, architecture decisions, and go/no-go assessment.
+
+| Document | Purpose |
+|----------|---------|
+| [Discovery Sessions Guide]([PROJECT_NAME]-Discovery-Sessions-Guide.md) | Full methodology — 13 session definitions |
+| [Project Definition]([PROJECT_NAME]-Project-Definition.md) | Consolidated output document |
+| [Discovery/_progress.md](Discovery/_progress.md) | Session progress tracker |
+| [Discovery/_context.md](Discovery/_context.md) | Cross-session context accumulator |
+| [prototype/](prototype/) | Interactive HTML prototype (created after Session 4) |
+
+## Project Structure
+```
+[PROJECT_NAME]/
+  .obsidian/              Obsidian vault configuration
+  Discovery/              Discovery Sprint — 13 session worksheets
+  prototype/              Interactive HTML prototype (built during Discovery)
+  requirements/           Functional requirements, user stories, test cases
+  Inputs/docs/            Input documents and reference materials
+  docs/                   Architecture decisions and guides
+```
+
+## Next Steps After Discovery
+
+Once the Discovery Sprint is complete and you have a validated project definition:
+1. Scaffold the application code (use `pareto-project-setup` or manually)
+2. Set up CI/CD pipeline (use `pareto-cicd-setup`)
+3. Create your first feature branch and start building
+
+Quality drives speed. Discover first, then build.
+```
+
+**`.gitignore`**
+```
+# IDE
+.idea/
+.vscode/settings.json
+*.iml
+
+# Obsidian (workspace is user-specific; vault config is version-controlled)
+.obsidian/workspace.json
+
+# OS
+.DS_Store
+Thumbs.db
+```
+
+#### 4f. Configure GitHub Project Board
+
+Set up the project board, labels, and milestone for tracking work.
+
+##### Labels
+
+Delete default GitHub labels first, then create the Pareto standard set:
+
+```bash
+# Remove default labels
+gh label delete "bug" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "documentation" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "duplicate" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "enhancement" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "good first issue" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "help wanted" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "invalid" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "question" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+gh label delete "wontfix" --yes -R [GITHUB_ORG]/[PROJECT_NAME] 2>/dev/null
+
+# Type labels
+gh label create "bug"           -c "d73a4a" -d "Something isn't working"           --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "feature"       -c "a2eeef" -d "New feature or capability"          --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "enhancement"   -c "84b6eb" -d "Improvement to existing feature"    --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "chore"         -c "e4e669" -d "Maintenance or housekeeping"        --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "docs"          -c "0075ca" -d "Documentation only"                 --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# Priority labels
+gh label create "priority:critical" -c "b60205" -d "Must fix immediately"           --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "priority:high"     -c "d93f0b" -d "Important, address soon"        --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "priority:medium"   -c "fbca04" -d "Normal priority"                --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "priority:low"      -c "0e8a16" -d "Nice to have, can wait"         --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# Phase labels
+gh label create "phase:discovery"   -c "c5def5" -d "Discovery Sprint"               --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "phase:mvp"         -c "bfdadc" -d "MVP phase"                      --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "phase:enhancement" -c "d4c5f9" -d "Post-MVP enhancement"           --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# Status labels
+gh label create "needs-review"  -c "f9d0c4" -d "Needs code review"                 --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "blocked"       -c "d73a4a" -d "Blocked by dependency"              --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "in-progress"   -c "fbca04" -d "Currently being worked on"          --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# Issue type labels
+gh label create "epic"          -c "3E4B9E" -d "Epic — high-level feature group"    --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "user-story"    -c "1D76DB" -d "User story"                         --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# MoSCoW prioritisation labels
+gh label create "must-have"     -c "B60205" -d "Must Have — MVP required"           --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "should-have"   -c "FBCA04" -d "Should Have — important but not blocking" --force -R [GITHUB_ORG]/[PROJECT_NAME]
+
+# UAT label
+gh label create "uat"           -c "fbca04" -d "User acceptance testing"            --force -R [GITHUB_ORG]/[PROJECT_NAME]
+```
+
+**Epic-specific labels** are created later, during or after the Discovery Sprint, once EPICs are defined. Use descriptive short names with distinct colors — not generic IDs. Pattern:
+
+```bash
+# Example — create after Discovery Sprint Session 3 (To-Be) when EPICs are known:
+gh label create "epic:lead-management" -c "0E8A16" -d "EPIC-001: Lead Management"  --force -R [GITHUB_ORG]/[PROJECT_NAME]
+gh label create "epic:ai-engine"       -c "B44EFF" -d "EPIC-002: AI Next-Action"   --force -R [GITHUB_ORG]/[PROJECT_NAME]
+# ... one per EPIC, each with a unique color for visual distinction on the board
+```
+
+**Color palette for epic labels** (16 distinct colors, use in order):
+`#0E8A16` (green), `#1AA393` (teal), `#D93F0B` (orange), `#B44EFF` (purple),
+`#4A9EFF` (blue), `#EF4444` (red), `#F5C842` (gold), `#8B5CF6` (violet),
+`#166534` (dark green), `#0891B2` (cyan), `#1E40AF` (navy), `#EA580C` (coral),
+`#DB2777` (magenta), `#6B7280` (gray), `#EC4899` (pink), `#0D9488` (dark teal)
+
+**Rules for epic labels:**
+- Use `epic:[short-name]` format (e.g. `epic:trips`, `epic:finance`, `epic:auth`)
+- Never use generic IDs like `epic:EPIC-001` — these are unreadable on the board
+- Each epic gets a unique color from the palette above
+- Description includes the EPIC ID for traceability (e.g. `"EPIC-001: Trip Management"`)
+- Apply `epic` label to EPIC issues, `user-story` label to story issues
+- Apply the relevant `epic:[short-name]` label to both the EPIC issue and its child stories
+
+##### Milestone
+
+```bash
+gh api repos/[GITHUB_ORG]/[PROJECT_NAME]/milestones \
+  -f title="v1.0 — MVP" \
+  -f description="Minimum viable product — core features for initial release" \
+  -f state="open"
+```
+
+##### Project Board
+
+Board creation, Status field configuration (Backlog → To Do → In Progress →
+Verification → Done), and all custom fields (Priority, Sprint, Estimate,
+Phase) are handled by the canonical shared script
+`../_shared/create-project-board.sh`.
+
+This is the single source of truth for the Pareto board schema. Every skill
+that touches project boards (this skill, `pareto-build-handoff`, and
+`pareto-push-issues`) sources it — edits must happen in that one file.
+
+```bash
+# Source the shared functions. The _shared/ directory ships as a peer of this
+# skill inside the same bundle, so resolve it relative to this skill's own
+# location (../_shared) rather than assuming any absolute install path.
+SHARED="$(dirname "${BASH_SOURCE[0]:-$0}")/../_shared/create-project-board.sh"
+source "$SHARED"
+
+# Create (or reuse) the board and configure all fields
+read PROJECT_NUM BOARD_OWNER < <(create_project_board \
+  "[GITHUB_ORG]" \
+  "[PROJECT_NAME]" \
+  "[GITHUB_ORG]/[PROJECT_NAME]")
+```
+
+If the project create fails due to org permissions, the shared script
+automatically falls back to `--owner "@me"` — `$BOARD_OWNER` will reflect
+the owner that was actually used. Use `2>/dev/null` on label deletes
+elsewhere in the skill to suppress errors for labels that don't exist.
+Board *view* (Kanban layout) must still be created manually in the GitHub
+web UI (click "New view" → "Board").
+
+#### 4g. Initial Commit and Push
+
+```bash
+git add .
+git commit -m "chore: initial project scaffold
+
+- Discovery Sprint framework (13 session templates + methodology guide)
+- Prototype folder structure (populated after Discovery Session 4)
+- Obsidian vault configured
+- Requirements templates (functional requirements, user stories, test cases)
+- Project Definition template
+- GitHub project board with Status, Priority, Sprint, Estimate fields
+- Repo labels (type, priority, phase, status, MoSCoW, issue type)
+- MVP milestone
+
+Client: [CLIENT_NAME]
+Generated by: pareto-project-setup skill"
+
+git push origin main
+```
+
+---
+
+### STEP 5 — Handoff Summary
+
+After successful push, give the developer a clean summary:
+
+> "Project `[PROJECT_NAME]` is live on GitHub.
+>
+> **Repo**: https://github.com/[GITHUB_ORG]/[PROJECT_NAME]
+>
+> **Next steps — Discovery Sprint (start here):**
+> 1. Open the project folder in **Obsidian** as a vault
+> 2. README.md loads as the landing page
+> 3. Navigate to `Discovery/` and begin **Session 1 (Kick-off)**
+> 4. Use `[PROJECT_NAME]-Discovery-Sessions-Guide.md` for facilitation guidance
+> 5. Track progress in `Discovery/_progress.md`
+> 6. Complete all 13 sessions to produce a validated project definition
+>
+> **Project Board:**
+> Open at: https://github.com/users/[GITHUB_ORG]/projects/ (or https://github.com/orgs/[GITHUB_ORG]/projects/)
+> Fields: Status (Backlog → To Do → In Progress → Verification → Done), Priority, Sprint, Estimate, Due Date
+> Tip: Click "New view" → "Board" in the project to create a Kanban board view
+>
+> **After Discovery:**
+> Once you have a validated project definition, scaffold the application and set up CI/CD.
+> Use `pareto-cicd-setup` for pipeline configuration and `pareto-deploy-setup` for deployment.
+>
+> Discover first, then build."
+
+---
+
+## Error Handling
+
+| Error | Likely Cause | Fix |
+|---|---|---|
+| `gh: command not found` | GitHub CLI not installed | `brew install gh` or `winget install GitHub.cli` |
+| `gh auth` fails | Not logged in | `gh auth login` |
+| Repo already exists | Name conflict | Ask user for alternative name |
+| `gh project create` fails | No permission to create projects in org | Use `--owner "@me"` instead |
+| Label delete fails | Label doesn't exist | Safe to ignore (suppressed with `2>/dev/null`) |
+
+---
+
+## Conventions Reference
+
+| Item | Convention |
+|---|---|
+| Repo name | `[client]-[product]` lowercase hyphens |
+| Branch name | `feature/`, `fix/`, `chore/` prefix |
+| Commit style | Conventional Commits (`feat:`, `fix:`, `chore:`) |