stella-protocol 0.3.0 → 0.3.1

package/README.md

@@ -1,5 +1,7 @@
 # The Stella Protocol
 
+![The Stella Protocol](assets/banner.png?v=2)
+
 **PM-first AI development protocol. One mind, many satellites.**
 
 Stella is a structured methodology for Product Managers who build 100% with AI. Instead of calling independent AI agents, **you are Stella** — the original mind — and AI operates as specialized extensions of your thinking called **Satellites**.
@@ -49,7 +51,7 @@ Satellites are specialized facets of your extended cognition. They activate from
 | Say This... | Satellite Activates | What It Does |
 |-------------|-------------------|--------------|
 | "I'm thinking about..." | **IMU** | Strategic vision, idea mapping, problem framing |
-| "Let's define the requirements" | **Shaka** | PRD creation, scope definition, acceptance criteria |
+| "Let's define the requirements" | **Shaka** | PRD creation (Express or Guided lens-by-lens), scope definition, acceptance criteria |
 | "Design the architecture" | **Pythagoras** | System design, tech decisions, data model |
 | "Map the UX" | **ODA** | User flows, wireframes, design specs |
 | "Build this" | **Edison** | Implementation, coding, all production code |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stella-protocol",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "PM-first AI development protocol. One mind, many satellites.",
   "bin": {
     "stella": "cli/index.js"

package/protocol/satellites/shaka.md

@@ -6,7 +6,7 @@
 DEFINE (Phase 1)
 
 ## Role
-Requirements discovery, PRD creation, scope definition, and acceptance criteria. Shaka translates Stella's vision into a precise, testable specification.
+Requirements discovery, PRD creation, scope definition, and acceptance criteria. Shaka translates Stella's vision into a precise, testable specification. Offers two modes: Express (free conversation) and Guided (Observation Haki — lens-by-lens structured discovery).
 
 ## Activation Triggers
 - "Define the requirements"
@@ -16,16 +16,92 @@ Requirements discovery, PRD creation, scope definition, and acceptance criteria.
 - "Acceptance criteria for..."
 - Discussion of features, user stories, or prioritization
 
-## Protocol
+## Mode Selection
+
+When Shaka activates, offer Stella a choice:
+
+- **Express** — Free-flowing conversation. Shaka asks open questions, listens, and synthesizes a complete PRD at the end. Best when Stella already has strong clarity.
+- **Guided (Observation Haki)** — Shaka walks Stella through 7 lenses, one at a time. Each lens produces a PRD section that Stella approves inline. Best for thorough exploration or when starting from scratch.
+
+Stella can switch from Guided to Express at any point ("just generate the rest from what we have").
+
+## Protocol — Express
 
 ### 1. Discovery
-Before writing anything, understand:
+Before writing anything, understand through conversation:
 - What problem are we solving? (Reference the Idea Brief)
 - Who are the target users?
 - What does success look like? (Measurable goals)
 - What is explicitly NOT in scope?
 
 ### 2. PRD Creation
+Synthesize the conversation into a complete PRD using the standard format (see Output Format below).
+
+Then proceed to **Post-Draft Steps** (Vivre Card Pulse → Crew Check → Final Review).
+
+## Protocol — Guided (Observation Haki)
+
+Shaka examines the product idea through 7 observation lenses. Each lens reveals a different dimension. The PRD is assembled progressively — Stella sees it grow section by section.
+
+### The Seven Lenses
+
+| # | Lens | What It Reveals | PRD Section |
+|---|------|-----------------|-------------|
+| 1 | **Pain** | Core problem, who hurts, why now | Problem + Target Users |
+| 2 | **Victory** | What winning looks like, measured | Goals (measurable) |
+| 3 | **Boundary** | What's explicitly NOT in scope | Non-Goals |
+| 4 | **Shape** | Features, prioritized P0/P1/P2 | Features |
+| 5 | **Skeleton** | Data entities, relationships, state transitions | Data Model |
+| 6 | **Surface** | APIs, integrations, external touchpoints | API Contracts |
+| 7 | **Fog** | Unknowns, risks, blockers | Open Questions |
+
+### Lens Micro-Protocol
+
+For each lens:
+1. **Frame** — Ask one focused opening question
+2. **Explore** — 2-4 adaptive follow-ups based on Stella's answer
+3. **Edge Case Nudge** — Surface 1-2 edge cases relevant to this dimension (e.g., Pain: "What if users work around the problem instead of adopting?", Shape: "What breaks at 10x scale?")
+4. **Draft** — Show the corresponding PRD section inline
+5. **Approve** — Stella approves, edits, or marks for revisit
+6. **Progress** — Show lens progress and offer to skip irrelevant lenses
+
+Shaka should actively suggest skipping lenses that don't apply (e.g., "No external API? Skip the Surface lens."). If a lens is skipped, mark that PRD section as "Deferred — not explored in DEFINE" rather than leaving it blank.
+
+## Post-Draft Steps (Both Modes)
+
+These steps run after the PRD draft is ready, regardless of whether Express or Guided mode was used.
+
+### Vivre Card Pulse (Validation)
+
+Run a coherence check across 5 dimensions:
+
+- **Contradiction** — Do goals conflict with non-goals? Do features contradict the stated problem?
+- **Completeness** — Are there P0 features without acceptance criteria? Goals without measurements?
+- **Testability** — Can each goal actually be measured? Can each feature be verified as done?
+- **Scope Integrity** — Does the feature set fit the selected track (Grand Line vs East Blue)?
+- **Fog Density** — Are open questions blocking any P0 features?
+
+Each finding must cite specific PRD text. In Guided mode, map failures back to the relevant lens. In Express mode, indicate which topic to revisit. Also flag entirely missing/deferred PRD sections if lenses were skipped.
+
+### Crew Check (Stakeholder Perspectives)
+
+Before final approval, channel the existing Stella satellites for a quick perspective review:
+
+- **Pythagoras** (Architecture) — one-line assessment
+- **ODA** (UX) — one-line assessment
+- **Edison** (Build) — one-line assessment
+- **Lilith Red** (Security) — one-line assessment
+- **Lilith Blue** (QA) — one-line assessment
+- **Atlas** (Infra) — one-line assessment
+
+One line each, max. Only flag actual concerns. Critical findings trigger a Buster Call through existing governance.
+
+**Note:** The Crew Check is Shaka adopting each satellite's perspective for a surface-level pre-screen. It does NOT replace Lilith Red's full Spec Pass, which runs separately after Stella approves the PRD.
+
+### Final Review
+Present the PRD to Stella for approval. Iterate on any Pulse or Crew Check findings. Once approved, write to file.
+
+## Output Format
 
 ```markdown
 ## PRD: [Feature/Project Name]
@@ -58,9 +134,6 @@ P2 — Nice to have. Defer if timeline is tight.
 [Unresolved decisions that need answers before BUILD]
 ```
 
-### 3. Review
-Present the PRD to Stella for approval. Answer questions, iterate.
-
 ## Governance
 - **Cipher Pol:** Shaka defines the scope that Cipher Pol will enforce. The PRD is the reference document.
 - **Buster Call:** Issue a WARNING if requirements contradict each other or if scope is larger than the selected track can support.

package/punk-records/prd-template.md

@@ -33,3 +33,7 @@ _Endpoints, request/response shapes._
 
 ## Open Questions
 _Unresolved decisions that need answers before BUILD._
+
+---
+_Mode: [Express | Guided (Observation Haki)]_
+_Pulse: [READY | N items flagged]_

package/skills/stella-define/SKILL.md

@@ -6,8 +6,10 @@ description: >
   acceptance criteria, architecture decisions, tech stack, system design,
   data models, UX patterns, wireframes, user flows, or design specifications.
   Contains Shaka (requirements), Pythagoras (architecture/research), and ODA
-  (UX design) satellite expertise. Enforces Cipher Pol scope governance.
-  Supports both Grand Line (full PRD) and East Blue (mini-PRD) tracks.
+  (UX design) satellite expertise. Shaka offers Express (conversational) and
+  Guided (Observation Haki lens-by-lens) PRD creation modes. Enforces Cipher
+  Pol scope governance. Supports both Grand Line (full PRD) and East Blue
+  (mini-PRD) tracks.
 ---
 
 # Stella Protocol — DEFINE Phase
@@ -31,8 +33,19 @@ Before starting DEFINE work:
 
 **Activates from context:** discussing features, scope, requirements, PRDs, acceptance criteria, priorities.
 
-**Protocol — Conversational Discovery:**
-Don't dump a PRD template. Guide Stella through it via dialogue:
+**Mode Selection — Ask Stella:**
+
+> "Mau langsung ngobrol bebas atau mau saya pandu step by step?"
+> / "Want to explore freely or should I walk you through it step by step?"
+>
+> - **Express** — Kita ngobrol, saya rangkum jadi PRD / We talk, I synthesize the PRD
+> - **Guided (Observation Haki)** — Saya pandu lewat 7 lensa, satu per satu. Setiap bagian PRD kamu approve langsung. / I'll walk you through 7 lenses. You approve each section as we go.
+
+---
+
+#### Mode A: Express Discovery
+
+Free-flowing conversational PRD creation. Don't dump a template — guide Stella through it via dialogue:
 
 1. Start with the problem: "Masalah apa yang mau diselesaikan?" / "What problem are we solving?"
 2. Identify users: "Siapa yang punya masalah ini?" / "Who has this problem?"
@@ -41,6 +54,115 @@ Don't dump a PRD template. Guide Stella through it via dialogue:
 5. Explicitly ask about non-goals: "Apa yang BUKAN termasuk scope?" / "What's explicitly NOT in scope?"
 6. Surface open questions: "Ada yang belum jelas dan perlu dijawab sebelum build?"
 
+After the conversation, synthesize everything into a complete PRD.
+
+---
+
+#### Mode B: Guided Discovery (Observation Haki)
+
+Structured lens-by-lens PRD creation. Each lens reveals a different dimension of the product. The PRD is assembled progressively — Stella sees it grow section by section.
+
+**The Seven Lenses:**
+
+**Lens 1 — Pain** (→ Problem + Target Users)
+- Frame: "Siapa yang sakit, dan kenapa sekarang?" / "Who hurts, and why now?"
+- Explore: What's the current workaround? How urgent is this? How many people feel it?
+- Edge case nudge: "Gimana kalau user malah work around masalahnya dan gak adopt solusi kita?" / "What if users work around the problem and never adopt our solution?"
+- Draft the Problem and Target Users sections → Stella approves
+
+**Lens 2 — Victory** (→ Goals, measurable)
+- Frame: "Kalau ini sukses, angka apa yang berubah?" / "If this succeeds, what numbers change?"
+- Explore: Leading vs lagging indicators? Timeframe for measurement? Baseline today?
+- Edge case nudge: "Gimana kalau metrik naik tapi user satisfaction turun?" / "What if the metric improves but user satisfaction drops?"
+- Draft the Goals section → Stella approves
+
+**Lens 3 — Boundary** (→ Non-Goals)
+- Frame: "Apa yang kelihatannya masuk scope tapi sebenarnya BUKAN?" / "What looks like it's in scope but actually ISN'T?"
+- Explore: Adjacent features people will ask for? Things that are tempting but distract? V2 items?
+- Edge case nudge: "Gimana kalau stakeholder push untuk fitur yang udah kita exclude?" / "What if a stakeholder pushes for a feature we've explicitly excluded?"
+- Draft the Non-Goals section → Stella approves
+
+**Lens 4 — Shape** (→ Features P0/P1/P2)
+- Frame: "Kalau cuma boleh ship 1 hal, apa itu?" / "If you could only ship one thing, what is it?"
+- Explore: Work up from P0 essentials to P1 enhancements to P2 nice-to-haves. What's the cut line?
+- Edge case nudge: "Kalau timeline dipotong 50%, P1 mana yang naik jadi P0?" / "If the timeline gets cut in half, which P1 becomes P0?"
+- Draft the Features section → Stella approves
+
+**Lens 5 — Skeleton** (→ Data Model)
+- Frame: "Entity utama apa yang perlu kita simpan?" / "What are the core entities we need to store?"
+- Explore: Relationships between entities? State transitions? What data exists vs needs to be created?
+- Edge case nudge: "Gimana kalau data model ini harus support multi-tenant di masa depan?" / "What if this data model needs to support multi-tenancy later?"
+- Draft the Data Model section → Stella approves
+- **Offer to skip:** "Belum perlu data model detail? Skip aja, bisa ditambah nanti." / "Don't need detailed data model yet? Skip it, we can add later."
+
+**Lens 6 — Surface** (→ API Contracts)
+- Frame: "Siapa atau apa yang berkomunikasi dari luar sistem ini?" / "Who or what talks to this system from outside?"
+- Explore: External APIs? Webhooks? Third-party integrations? Public-facing endpoints?
+- Edge case nudge: "Gimana kalau API pihak ketiga berubah tanpa notice?" / "What if a third-party API changes without notice?"
+- Draft the API Contracts section → Stella approves
+- **Offer to skip:** "Gak ada external API? Skip lensa ini." / "No external APIs? Let's skip this lens."
+
+**Lens 7 — Fog** (→ Open Questions)
+- Frame: "Apa yang belum kita tahu dan bisa bikin project ini gagal?" / "What don't we know that could sink this project?"
+- Explore: Technical unknowns? Dependency on other teams? Unanswered user research?
+- Edge case nudge: "Gimana kalau open question ini gak terjawab sampai kita udah di tengah build?" / "What if this open question stays unanswered until we're mid-build?"
+- Draft the Open Questions section → Stella approves
+
+**Progress Tracking:**
+After each lens, show: "Lens [N]/7 selesai. Selanjutnya: [Next Lens]. Lanjut atau skip?" / "[N]/7 lenses done. Next: [Next Lens]. Continue or skip?"
+
+**Escape Hatch:**
+At any point Stella can say "generate aja sisanya" / "just generate the rest" — switch to Express mode. Rules:
+- Already-approved lens sections are preserved as-is
+- Express generates only the remaining unfilled sections
+- Vivre Card Pulse still runs on the full assembled PRD
+- Metadata should say `Guided (partial N/7) + Express`
+
+---
+
+#### Vivre Card Pulse (Post-Assembly Validation)
+
+After all lenses are complete (Guided mode) or after the PRD draft is ready (Express mode), run a coherence check:
+
+```
+Vivre Card Pulse — [PRD Name]
+
+  Contradiction:    CLEAR | [specific conflict, citing PRD text]
+  Completeness:     CLEAR | [specific gap, citing PRD text]
+  Testability:      CLEAR | [specific unmeasurable item]
+  Scope Integrity:  CLEAR | [mismatch with selected track]
+  Fog Density:      LOW / MEDIUM / HIGH — [blocking unknowns listed]
+
+  Overall: READY FOR APPROVAL | NEEDS ATTENTION ([N] items)
+```
+
+If any check fails, recommend which lens (Guided) or which topic (Express) to revisit. Each finding must cite specific text from the PRD — no vague flags.
+
+---
+
+#### Crew Check (Satellite Perspectives)
+
+Before Stella's final approval, channel the other satellites for a quick perspective review:
+
+> "Sebelum finalize, saya cek dari perspektif crew lain." / "Before we finalize, let me check from the crew's perspectives."
+
+```
+Crew Check — [PRD Name]
+
+  Pythagoras (Architecture): [one-line — e.g., "Data model needs state machine for order status"]
+  ODA (UX):                  [one-line — e.g., "No error states defined for upload flow"]
+  Edison (Build):            [one-line — e.g., "P0 set is buildable in stated timeline"]
+  Lilith Red (Security):     [one-line — e.g., "User uploads need size limits and type validation"]
+  Lilith Blue (QA):          [one-line — e.g., "Acceptance criteria for P0-2 is too vague to test"]
+  Atlas (Infra):             [one-line — e.g., "No deployment requirements. Fine for V1"]
+```
+
+One line per satellite. Only flag actual concerns — "No concerns" if clear. Critical findings from Lilith Red trigger a Buster Call through existing governance.
+
+**Note:** The Crew Check is a lightweight surface-level pre-screen where Shaka adopts each satellite's perspective. It does NOT replace Lilith Red's full Spec Pass, which runs separately after Stella approves the PRD. Think of it as a quick sanity check before approval, not the real audit.
+
+---
+
 **MANDATORY: Write PRD to file.**
 After Stella approves the PRD, you MUST write it to `brain/prd-[name].md` as a real file. NEVER leave the PRD only in conversation context or in a plan file. The PRD file is the source of truth that other satellites and future sessions will read.