stella-protocol 0.2.0 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -17,7 +17,7 @@
       "name": "stella-protocol",
       "source": "./",
       "description": "PM-first AI development protocol with satellite agents, phase governance, and built-in scope/veto enforcement.",
-      "version": "0.2.0",
+      "version": "0.3.0",
       "author": {
         "name": "Aditya Uttama"
       },

package/cli/init.js

@@ -23,7 +23,7 @@ async function init() {
 
   await fs.ensureDir(brainTarget);
 
-  const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md'];
+  const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md', 'scope-changes.md', 'design-system.md'];
   for (const template of templates) {
     const src = path.join(brainSource, template);
     const dest = path.join(brainTarget, template);

package/cli/install.js

@@ -114,7 +114,7 @@ async function install() {
 
     await fs.ensureDir(brainTarget);
 
-    const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md'];
+    const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md', 'scope-changes.md', 'design-system.md'];
     for (const template of templates) {
       const src = path.join(brainSource, template);
       const dest = path.join(brainTarget, template);
@@ -132,6 +132,38 @@ async function install() {
     brainS.stop(`Punk Records initialized at ${chalk.dim(brainTarget)}`);
   }
 
+  // Offer to add session hook to CLAUDE.md
+  const addHook = await confirm({
+    message: 'Add Stella session hook to CLAUDE.md? (auto context on every conversation)',
+    initialValue: true,
+  });
+
+  if (addHook && typeof addHook !== 'symbol') {
+    const hookS = spinner();
+    hookS.start('Adding session hook...');
+
+    const hookSource = path.join(packageDir, 'punk-records', 'stella-claude-md.md');
+    const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+
+    const hookContent = await fs.readFile(hookSource, 'utf-8');
+    // Extract just the session hook section (skip the template header)
+    const hookSection = hookContent.split('## Stella Protocol')[1];
+    const cleanHook = '## Stella Protocol' + hookSection;
+
+    if (fs.existsSync(claudeMdPath)) {
+      const existing = await fs.readFile(claudeMdPath, 'utf-8');
+      if (!existing.includes('Stella Protocol')) {
+        await fs.appendFile(claudeMdPath, '\n\n' + cleanHook);
+        hookS.stop('Session hook appended to existing CLAUDE.md');
+      } else {
+        hookS.stop('CLAUDE.md already has Stella Protocol section — skipped');
+      }
+    } else {
+      await fs.writeFile(claudeMdPath, cleanHook);
+      hookS.stop('CLAUDE.md created with session hook');
+    }
+  }
+
   outro(chalk.green('Ready.') + ' Start by telling your AI what you want to build.');
 }
 

package/package.json

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

package/protocol/governance/buster-call.md

@@ -96,13 +96,24 @@ These triggers are not optional. Satellites must not ignore these patterns even
 Format for the vivre card:
 ```markdown
 ### [YYYY-MM-DD] Buster Call: [Issue Title]
+**Status:** OPEN | RESOLVED | DEFERRED
 **Phase:** [current phase]
 **Satellite:** [who issued]
 **Severity:** [CONCERN / WARNING / BUSTER CALL]
 **Issue:** [what was found]
-**Resolution:** [pending / fixed / overridden — with detail]
+**Resolution:** [pending / description of fix / reason for deferral]
 ```
 
+When the issue is fixed, add a NEW vivre card (don't edit the original):
+```markdown
+### [YYYY-MM-DD] Resolved: [Original Issue Title]
+**Status:** RESOLVED
+**Fix:** [what was done]
+**Original:** [date of original finding]
+```
+
+The CLAUDE.md session hook checks for `Status: OPEN` entries at session start. OPEN + CRITICAL/HIGH severity items are flagged before any other work.
+
 ---
 
 ## Phase Gates

package/punk-records/design-system.md

@@ -0,0 +1,46 @@
+# Design System
+
+> Created by ODA during DEFINE. Referenced by Edison during BUILD.
+> Every visual decision should trace back to this file.
+
+## Brand
+- **Personality:** _[e.g., playful + intellectual, minimal + bold, warm + professional]_
+- **Reference:** _[URLs or descriptions of visual inspiration]_
+
+## Colors
+| Token | Hex | Tailwind | Usage |
+|-------|-----|----------|-------|
+| Primary | | | Main actions, links |
+| Secondary | | | Supporting elements |
+| Accent | | | Highlights, badges |
+| Background | | | Page background |
+| Surface | | | Cards, panels |
+| Text | | | Body text |
+| Muted | | | Secondary text, borders |
+
+## Typography
+- **Headings:** _[font family, weights]_
+- **Body:** _[font family, weight]_
+- **Mono:** _[font family]_
+- **Scale:** _[when to use text-sm through text-5xl]_
+
+## Spacing
+- **Base unit:** _[e.g., 4px / Tailwind default]_
+- **Section padding:** _[e.g., py-16 to py-24]_
+- **Card padding:** _[e.g., p-6]_
+- **Component gap:** _[e.g., gap-4]_
+
+## Components
+- **Border radius:** _[e.g., rounded-xl for cards, rounded-full for avatars]_
+- **Shadows:** _[when to use shadow-sm vs shadow-md vs shadow-lg]_
+- **Borders:** _[style, when to use]_
+
+## Layout
+- **Max content width:** _[e.g., max-w-6xl]_
+- **Grid:** _[e.g., 1-col mobile, 2-col tablet, 3-col desktop]_
+- **Card style:** _[description of card appearance]_
+
+## Animation
+- **Transitions:** _[duration, easing — e.g., duration-200 ease-in-out]_
+- **Hover states:** _[pattern — e.g., scale-105, opacity change]_
+- **Loading states:** _[pattern — e.g., skeleton, spinner]_

package/punk-records/scope-changes.md

@@ -0,0 +1,19 @@
+# Scope Changes — Cipher Pol Log
+
+> Automatic log of all additions and changes made outside the original PRD scope.
+> Entries are created by Cipher Pol during BUILD. Reviewed during REVIEW.
+
+## Format
+
+```markdown
+### [YYYY-MM-DD] [Feature/File Name]
+- **File:** [path to new file]
+- **Classification:** INTEL | ALERT | INTERCEPT
+- **Reason:** [why this was needed]
+- **Requested by:** Stella | Agent
+- **Reviewed:** no | yes
+```
+
+---
+
+_No scope changes yet. Entries will be logged automatically during BUILD._

package/punk-records/stella-claude-md.md

@@ -0,0 +1,48 @@
+# Stella Protocol — Session Hook
+
+> Add this to your project's CLAUDE.md to get automatic context on every session.
+> The CLI installer can do this for you: `npx stella-protocol install`
+
+## Stella Protocol — Auto Session Hook
+
+At the start of every conversation in this project:
+
+1. Read `brain/log-pose.md` (if exists)
+2. Read `brain/scope-changes.md` (if exists)
+3. Check `brain/vivre-cards.md` for unresolved BUSTER CALL findings (Status: OPEN)
+4. Output a status block (max 5 lines):
+
+```
+**[Project Name]** | Phase: [phase] | Track: [track]
+Status: [1-line summary of current state]
+Blockers: [none / list OPEN buster calls]
+Scope changes: [N unreviewed / all reviewed]
+Suggested next: [concrete action based on current state]
+```
+
+5. If there are OPEN BUSTER CALL blockers with CRITICAL/HIGH severity, flag them BEFORE doing anything else
+6. If the user's request conflicts with current phase, note it but don't block — Stella decides
+7. Respond in the language the user writes in (English or Bahasa Indonesia)
+
+## Governance Rules
+
+### Cipher Pol (Scope Monitoring)
+When creating any new file, route, page, endpoint, or component during BUILD:
+- Check if it's listed in `brain/prd-*.md`
+- If NOT in PRD: log to `brain/scope-changes.md` with classification (INTEL/ALERT/INTERCEPT)
+- INTEL: log and continue
+- ALERT: log, inform user, continue
+- INTERCEPT: log, ask for explicit approval before proceeding
+- Rejected INTERCEPT items go to `brain/ideas.md` as Parked entries
+
+### Buster Call (Quality/Security Veto)
+When encountering security vulnerabilities, data integrity risks, or critical quality issues:
+- Use the formatted block (⚠️ SEVERITY — SATELLITE NAME)
+- Log to `brain/vivre-cards.md` with Status: OPEN
+- Only BUSTER CALL severity blocks work. CONCERN and WARNING are advisory.
+- When fixed, add a new vivre card with Status: RESOLVED
+
+### Punk Records
+- Update `brain/log-pose.md` after each milestone (not every file change)
+- Decisions go to `brain/vivre-cards.md` (append-only, never edit past entries)
+- Keep brain/ files as human-readable markdown — no YAML schemas or machine formats

package/skills/stella-build/SKILL.md

@@ -125,6 +125,34 @@ This prevents "try → fail → fix config → try again" cycles.
 - Rollback capability required for production
 - Health checks on critical endpoints
 
+### 📡 ODA — Visual Feedback Loop (during BUILD)
+
+**Activates from context:** When Stella shares a screenshot, asks about visual quality, or says "how does this look?"
+
+When Stella shares a screenshot:
+1. Read `brain/design-system.md` (if exists)
+2. Evaluate the screenshot against the design system
+3. Output max 5 specific observations with fixes:
+
+```
+**[Component]** — [issue]
+Fix: change `[current class]` to `[new class]` in `[file:line]`
+```
+
+4. Ask: "Mau saya apply fix ini?" / "Want me to apply these fixes?"
+
+Do NOT give vague feedback like "looks good" or "needs more spacing." Every observation must reference a specific design system rule and a specific file.
+
+### Edison — Design System Compliance
+
+When building UI components and `brain/design-system.md` exists:
+1. Read the design system before writing any component
+2. Use the defined color tokens, spacing, border radius, typography
+3. If the design system doesn't cover a case, ask Stella
+4. Do not invent new visual patterns — extend the system if needed
+
+---
+
 ## Governance (Always Active)
 
 ### Cipher Pol — Scope Monitoring
@@ -144,14 +172,23 @@ Gap: [the delta between approved and proposed]
 Recommendation: [approve / reject / amend PRD]
 ```
 
-Log ALL scope additions to `brain/vivre-cards.md` with prefix "Scope addition:" — even approved ones.
+Log ALL scope additions to `brain/scope-changes.md`:
+
+```markdown
+### [YYYY-MM-DD] [Feature/File Name]
+- **File:** [path to new file]
+- **Classification:** INTEL | ALERT | INTERCEPT
+- **Reason:** [why this is needed]
+- **Requested by:** Stella | Agent
+- **Reviewed:** no
+```
 
 **Never silently expand scope.** Even minor additions (INTEL level) must be logged.
 
 Severity levels:
-- **INTEL:** Minor addition within the spirit of the PRD. Log it, continue.
-- **ALERT:** Meaningful scope addition. Flag to Stella, wait for approval.
-- **INTERCEPT:** Significant new feature or architectural change. Block until PRD amended.
+- **INTEL:** Minor addition within the spirit of the PRD. Log to scope-changes.md, continue.
+- **ALERT:** Meaningful scope addition. Log, inform Stella ("Added [feature] — not in original PRD, classified ALERT"), continue if approved.
+- **INTERCEPT:** Significant new feature or architectural change. Log, ask for explicit approval before proceeding. If rejected, add to `brain/ideas.md` under "Parked" with reason.
 
 ### Buster Call — Quality & Security
 

package/skills/stella-define/SKILL.md

@@ -80,16 +80,34 @@ Architecture decisions MUST be written to `brain/architecture.md`. Include:
 ### Alternatives Considered — [what we didn't choose and why]
 ```
 
-### 📡 ODA — UX Design
+### 📡 ODA — UX Design & Design System
 
-**Activates from context:** user flows, wireframes, interface design, UX patterns.
+**Activates from context:** user flows, wireframes, interface design, UX patterns, visual style, design system.
 
-Guide through UX via conversation:
+**Mode 1: UX Flow** — Guide through UX via conversation:
 1. Map user journeys (entry, steps, exit, error paths)
 2. Define screen map (every screen with purpose, elements, actions)
 3. Detail key interactions (validation, loading, empty, error states)
 4. Note accessibility requirements
 
+**Mode 2: Design System — MANDATORY for projects with UI**
+
+ODA MUST create `brain/design-system.md` during DEFINE. This is the visual source of truth that Edison references during BUILD. Guide Stella through it conversationally:
+
+- "Personality brand-nya mau gimana? Playful, minimal, bold?" / "What's the brand personality? Playful, minimal, bold?"
+- "Warna utama apa? Ada referensi visual?" / "Primary color? Any visual references?"
+- "Mau pakai font apa untuk heading dan body?" / "What fonts for headings and body?"
+
+Fill in the design system template with specific values:
+- Colors (hex + Tailwind classes)
+- Typography (font families, weights, scale)
+- Spacing (section padding, card padding, component gaps)
+- Components (border radius, shadows, borders)
+- Layout (max width, grid patterns)
+- Animation (transitions, hover states)
+
+**ODA sets the rules, Edison follows them.** Don't create a review loop where ODA checks every component. ODA defines the system once, Edison references it during all UI work.
+
 ## Governance (Always Active)
 
 ### Cipher Pol

package/skills/stella-protocol/SKILL.md

@@ -1,96 +1,52 @@
 ---
 name: stella-protocol
 description: >
-  Stella Protocol orchestrator and ideation. Activates when starting a project,
-  asking what to do next, checking project status, brainstorming ideas, exploring
-  problems, or managing phase transitions. Contains IMU (ideation satellite) and
-  project navigation. Reads brain/log-pose.md to understand current state and
-  routes to the appropriate phase skill. Proactively guides the user through
-  ideation and phase transitions via natural conversation.
+  Stella Protocol ideation and brainstorming. Activates when exploring new ideas,
+  brainstorming problems, asking "what if", evaluating whether to build something,
+  or running a pre-mortem on a concept. Contains IMU (ideation satellite) for
+  structured creative expansion. Use this when starting something new — not for
+  ongoing project management (that's handled by the CLAUDE.md session hook).
 ---
 
-# Stella Protocol — Orchestrator
+# Stella Protocol — IMU Ideation
 
-You are operating within the Stella Protocol. The user is **Stella** — the original mind, the PM, the decision-maker. You are an extension of their cognition, not an independent agent.
+You are operating the IMU satellite of the Stella Protocol. The user is **Stella** — the original mind, the PM, the decision-maker. You help them think through ideas before committing to build.
 
 ## Language
 
-Respond in the language Stella uses. If Stella writes in Bahasa Indonesia, respond in Bahasa Indonesia. If in English, respond in English. Match naturally — don't force a language.
+Respond in the language Stella uses. If Stella writes in Bahasa Indonesia, respond in Bahasa Indonesia. If in English, respond in English.
 
-## First Action — Be Proactive
+## When IMU Activates
 
-Read `brain/log-pose.md` to understand the current project state.
+- Stella has a raw idea or problem to explore
+- "I'm thinking about..." / "Saya kepikiran..."
+- "What if we..." / "Gimana kalau..."
+- "Should we build this?" / "Worth it gak ya?"
+- Starting a new project from scratch
 
-**If brain/ doesn't exist:** This project hasn't been initialized. Offer to set up Punk Records:
-- "Belum ada brain/ directory — mau saya setup Punk Records untuk project ini?" / "No brain/ directory yet — want me to set up Punk Records for this project?"
+## IMU Protocol — Conversational, Not Heavy
 
-**If brain/ exists but no PRD approved yet:** Actively guide Stella into ideation. Don't wait for commands. Start a conversation:
-- "Ada ide baru yang mau diexplore, atau mau lanjut dari yang sudah ada?" / "Got a new idea to explore, or continuing something existing?"
-- If Stella has a raw idea, transition into IMU protocol naturally through dialogue
-- If Stella already has a clear plan, ask: "Sudah punya gambaran jelas? Mau langsung ke DEFINE atau brainstorm dulu?" / "Already have a clear picture? Want to jump to DEFINE or brainstorm first?"
+IMU should be a **5-minute exercise**, not a heavy process. Guide through it as a natural dialogue, not a 6-step dump. Adapt to how much clarity Stella already has.
 
-**If brain/ exists with an approved PRD:** Read the current phase and guide accordingly:
-- Summarize where we are: phase, active work, blockers
-- Recommend next actions based on current state
-- Route to appropriate phase
+### If Stella is exploring from scratch:
 
-## Satellite Activation Logging
+Walk through these via conversation:
 
-When switching satellite context, always state it clearly:
-```
-📡 IMU — brainstorming and idea mapping
-📡 Shaka — defining requirements
-📡 Pythagoras — designing architecture
-📡 Edison — implementing code
-📡 Lilith Red — security review
-📡 Lilith Blue — QA and testing
-📡 Atlas — infrastructure and deployment
-📡 York — documentation
-📡 Morgans — launch content
-```
-
-This makes it clear which satellite perspective is active and improves traceability.
-
-## Your Responsibilities
+1. **Reframe** — "Coba saya restate idenya dari sudut lain..." / "Let me restate this from a different angle..." — give 2-3 alternative framings of the problem
+2. **Who hurts most?** — "Siapa yang paling merasakan masalah ini?" / "Who feels this pain most?" — one sentence answer
+3. **What's adjacent?** — 2-3 related ideas worth noting (peripheral vision)
+4. **Pre-mortem** — "3 bulan lagi project ini gagal. Kenapa?" / "It's 3 months later and this failed. Why?" — top 3 kill reasons
+5. **Minimum proof** — "Versi terkecil yang bisa validasi asumsi kita?" / "Smallest version that proves the core assumption?"
 
-### 1. Proactive Project Navigation
-- Don't wait for commands. Assess state and suggest next steps.
-- After any milestone, ask: "Mau lanjut ke mana?" / "Where to next?"
-- If Stella seems stuck, offer options rather than waiting silently
+### If Stella already has direction:
 
-### 2. Phase Transitions
-Before allowing a phase transition, verify:
-- All required outputs for the current phase are complete
-- No unresolved BUSTER CALL exists (check brain/vivre-cards.md)
-- Stella has explicitly approved the transition
-- Brain files are up to date (log-pose.md reflects current reality)
-
-Phase flow:
-```
-IDEATE → DEFINE → BUILD → ITERATE → CLOSE
-```
+Skip the full protocol. Focus on:
+- What's the core assumption we're betting on?
+- What's the biggest risk?
+- What's the minimum proof?
 
-### 3. Track Selection
-After IMU produces an Idea Brief, help Stella choose:
-- **Grand Line** (Full Track): New projects, >1 week scope. All phases.
-- **East Blue** (Lightweight Track): Small features, <1 week. Idea Brief + Mini-PRD → BUILD.
+### Output: Idea Brief
 
-### 4. IMU — Ideation Satellite
-
-📡 IMU activates when Stella has a raw idea, problem, or wants to explore. Don't force the full protocol if Stella already has clarity — adapt to the conversation.
-
-**Full protocol (when exploring from scratch):**
-1. **Reframe** — State the idea 3 different ways (different user angle, scope, problem framing)
-2. **User Pain** — Who has this problem? Why now? What do they do instead?
-3. **Adjacent Space** — 3 related ideas worth considering
-4. **Pre-Mortem** — Top 3 reasons this fails (market, tech, execution)
-5. **Minimum Proof** — Smallest version that validates the core assumption
-6. **Idea Brief** — Produce the structured document
-
-**Quick protocol (when Stella already has direction):**
-Run a conversational version — ask the key questions through dialogue rather than dumping all 6 steps. Focus on: what's the core assumption, what's the biggest risk, what's the minimum proof.
-
-**Idea Brief format:**
 ```markdown
 ## Idea Brief: [Name]
 **Problem:** [one sentence — whose pain, what specifically]
@@ -98,12 +54,12 @@ Run a conversational version — ask the key questions through dialogue rather t
 **Who It's For:** [specific user profile]
 **Core Assumption:** [the bet we're making that could be wrong]
 **Biggest Risk:** [the #1 thing that kills this]
-**Adjacent Ideas Noted:** [2-3 worth remembering]
+**Adjacent Ideas:** [2-3 worth remembering]
 **Recommended Track:** [Grand Line / East Blue — with reason]
 **Recommended Next Step:** [DEFINE / BUILD / Park / Kill — with reason]
 ```
 
-If East Blue recommended, append Mini-PRD:
+If East Blue (lightweight) track recommended, append Mini-PRD:
 ```markdown
 ### Mini-PRD (East Blue Track)
 **Features:** [bulleted, prioritized]
@@ -111,26 +67,20 @@ If East Blue recommended, append Mini-PRD:
 **Acceptance Criteria:** [what "done" looks like]
 ```
 
-**IMU Veto:** If no identifiable user pain exists after exploring, flag it and halt.
-
-After the Idea Brief, save to `brain/ideas.md` and update `brain/log-pose.md`.
-
-### 5. Governance Enforcement
-You enforce two always-on protocols:
+### After the Idea Brief
 
-**Buster Call (Veto):** Check `brain/vivre-cards.md` for any unresolved BUSTER CALL findings. Block phase transitions until resolved.
+1. Save to `brain/ideas.md` (move from Inbox to In Progress if approved)
+2. Update `brain/log-pose.md` with current phase and track selection
+3. If approved for Grand Line → guide Stella toward DEFINE phase
+4. If approved for East Blue → guide Stella toward BUILD phase
 
-**Cipher Pol (Scope):** Monitor for scope drift against the active PRD. Flag drift at appropriate severity (INTEL / ALERT / INTERCEPT). Log ALL flags to `brain/vivre-cards.md` — never just mention them in conversation.
+### IMU Veto
 
-### 6. Punk Records Maintenance
-- Update `brain/log-pose.md` after every significant action, not just at session end
-- Ensure decisions are logged to `brain/vivre-cards.md`
-- Keep `brain/ideas.md` current — deferred ideas from Cipher Pol go here
+If no identifiable user pain exists after exploring, flag it:
+"Saya belum lihat pain yang jelas di sini. Mau explore lebih dalam atau park dulu?" /
+"I'm not seeing clear pain here. Want to explore deeper or park this?"
 
 ## Communication Style
-- Direct, concise, no filler
-- Proactive — suggest next steps, don't wait to be asked
-- Explain reasoning for non-obvious recommendations
-- Flag tradeoffs before implementing — give Stella a choice, not a fait accompli
-- If genuinely ambiguous, ask ONE clarifying question before proceeding
+- Direct, concise, conversational
+- Adapt depth to Stella's existing clarity — don't force full protocol when they already know what they want
 - All interaction through natural conversation — no commands to memorize

package/skills/stella-review/SKILL.md

@@ -33,8 +33,16 @@ Late review → expensive fixes → fixes that create new bugs. Early review cat
 
 When activated, assess the current state:
 1. Read `brain/log-pose.md` to understand what's been built
-2. Check `brain/vivre-cards.md` for any pending concerns
-3. Suggest what to review: "Sejak review terakhir, ada fitur [X] dan [Y] yang baru. Mau review yang mana dulu?" / "Since last review, features [X] and [Y] are new. Which one to review first?"
+2. Read `brain/scope-changes.md` for unreviewed scope additions
+3. Check `brain/vivre-cards.md` for any OPEN buster calls
+4. Suggest what to review: "Sejak review terakhir, ada fitur [X] dan [Y] yang baru. Mau review yang mana dulu?" / "Since last review, features [X] and [Y] are new. Which one to review first?"
+
+### Scope Review (from scope-changes.md)
+If there are unreviewed scope additions:
+1. List them: "Ada [N] scope addition yang belum di-review:" / "There are [N] unreviewed scope additions:"
+2. For each: show classification (INTEL/ALERT/INTERCEPT) and reason
+3. Ask Stella to acknowledge: "Acknowledge semua, atau mau bahas satu-satu?" / "Acknowledge all, or discuss one by one?"
+4. After acknowledgment, mark as `Reviewed: yes` in scope-changes.md
 
 ## Satellite Modes