stella-protocol 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,33 @@
+{
+  "name": "stella-protocol",
+  "owner": {
+    "name": "Aditya Uttama"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/adityauttama/stella-protocol",
+  "repository": "https://github.com/adityauttama/stella-protocol",
+  "keywords": [
+    "product-management",
+    "ai-development",
+    "methodology",
+    "pm-tools"
+  ],
+  "plugins": [
+    {
+      "name": "stella-protocol",
+      "source": "./",
+      "description": "PM-first AI development protocol with satellite agents, phase governance, and built-in scope/veto enforcement.",
+      "version": "0.1.0",
+      "author": {
+        "name": "Aditya Uttama"
+      },
+      "skills": [
+        "./skills/stella-protocol",
+        "./skills/stella-define",
+        "./skills/stella-build",
+        "./skills/stella-review",
+        "./skills/stella-close"
+      ]
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya Uttama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# The Stella Protocol
+
+**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**.
+
+## Why Stella?
+
+Most AI development frameworks are built for developers. Stella is built for **the PM who owns the product vision and uses AI to execute everything else** — architecture, code, tests, deployment, documentation.
+
+- **No commands to memorize.** Satellites activate from natural conversation, not slash commands.
+- **Built-in governance.** Scope enforcement and veto protocols are always on — not optional tools you remember to invoke.
+- **Persistent project brain.** A structured `brain/` directory tracks decisions, state, and scope — committed to git, reviewable in PRs.
+
+## Quick Start
+
+```bash
+npx stella-protocol install
+```
+
+This will:
+1. Install 5 phase-based Agent Skills into your AI tool
+2. Initialize a `brain/` directory (Punk Records) in your project
+3. You're ready — start by telling your AI what you want to build
+
+## The Protocol
+
+### Phases
+
+```
+PHASE 0: IDEATE    →  Think about the problem space
+PHASE 1: DEFINE    →  Requirements, architecture, UX, PRD
+PHASE 2: BUILD     →  Implementation, deployment
+PHASE 2.5: ITERATE →  Post-launch feedback loop
+PHASE 3: CLOSE     →  Documentation, launch, go-to-market
+```
+
+### Two Tracks
+
+| Track | When to Use | What Happens |
+|-------|-------------|--------------|
+| **Grand Line** (Full) | New projects, >1 week scope | All phases in order, full PRD |
+| **East Blue** (Lightweight) | Small features, <1 week | Idea Brief with Mini-PRD, skip to BUILD |
+
+### Satellites
+
+Satellites are specialized facets of your extended cognition. They activate from conversational context:
+
+| 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 |
+| "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 |
+| "Review for security issues" | **Lilith Red** | Adversarial review, security audit |
+| "Write tests" | **Lilith Blue** | QA, test suites, edge case coverage |
+| "Deploy this" | **Atlas** | Infrastructure, CI/CD, deployment |
+| "Document this" | **York** | Knowledge capture, changelogs |
+| "Announce this" | **Morgans** | Launch, blog posts, go-to-market |
+
+### Governance (Always On)
+
+**Buster Call** — Any satellite can halt progress when it identifies critical issues. Severity: CONCERN → WARNING → BUSTER CALL. At BUSTER CALL level, work stops until you resolve it.
+
+**Cipher Pol** — Continuous scope monitoring against the approved PRD. Severity: INTEL → ALERT → INTERCEPT. Drift is detected and flagged automatically. You decide whether to approve or reject.
+
+### Punk Records (Project Brain)
+
+Every project gets a `brain/` directory — git-committed, PR-reviewable:
+
+```
+brain/
+├── log-pose.md        # Where are we? Phase, track, blockers, active work
+├── architecture.md    # Tech decisions with rationale
+├── vivre-cards.md     # Append-only decision log
+├── ideas.md           # Unprocessed idea backlog
+└── prd-*.md           # PRD documents (created as needed)
+```
+
+## Agent Skills
+
+Stella packages satellites into 5 phase-based skills:
+
+| Skill | Contains | Activates When |
+|-------|----------|----------------|
+| `stella-protocol` | Orchestrator + IMU | Starting a project, "what's next," phase routing |
+| `stella-define` | Shaka + Pythagoras + ODA | Requirements, architecture, UX, PRDs |
+| `stella-build` | Edison + Atlas | Coding, deploying, implementation |
+| `stella-review` | Lilith Red + Lilith Blue | Code review, security, QA |
+| `stella-close` | York + Morgans | Documentation, launch, go-to-market |
+
+Compatible with Claude Code, Cursor, and any tool supporting the Agent Skills open standard.
+
+## Philosophy
+
+> You are not "talking to an AI agent." You are thinking, and specialized facets of your extended cognition activate to help you execute.
+
+Stella inverts the typical framework model. You don't call agents — you think out loud, and the right expertise surfaces. The governance protocols aren't tools you invoke — they're constitutional rules that every satellite enforces.
+
+This is a protocol, not a product. The methodology in `protocol/` is human-readable markdown. You can apply it manually without any tooling. The `skills/` layer packages it for AI tools, but the protocol stands on its own.
+
+## Project Structure
+
+```
+stella-protocol/
+├── protocol/          # The methodology (human-readable markdown)
+│   ├── stella.md      # Master protocol
+│   ├── satellites/    # Satellite definitions
+│   ├── governance/    # Buster Call + Cipher Pol
+│   └── tracks/        # Grand Line + East Blue
+├── punk-records/      # Brain directory templates
+├── skills/            # Agent Skills (AI-consumable)
+├── cli/               # CLI installer
+└── docs/              # Documentation
+```
+
+## License
+
+MIT
+
+## Author
+
+[Aditya Uttama](https://github.com/adityauttama) — Product Manager who builds 100% with AI.

package/cli/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const { version } = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('stella')
+  .description('The Stella Protocol — PM-first AI development framework')
+  .version(version);
+
+program
+  .command('install')
+  .description('Install Stella Protocol skills and initialize Punk Records')
+  .action(async () => {
+    const { install } = require('./install');
+    await install();
+  });
+
+program
+  .command('init')
+  .description('Initialize Punk Records (brain/) in the current project')
+  .action(async () => {
+    const { init } = require('./init');
+    await init();
+  });
+
+program
+  .command('status')
+  .description('Show current project status from Punk Records')
+  .action(async () => {
+    const { status } = require('./status');
+    await status();
+  });
+
+program.parse();

package/cli/init.js

@@ -0,0 +1,44 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { intro, outro, spinner } = require('@clack/prompts');
+const chalk = require('chalk');
+
+async function init() {
+  intro(chalk.bold('Punk Records') + chalk.dim(' — Initialize project brain'));
+
+  const packageDir = path.resolve(__dirname, '..');
+  const brainSource = path.join(packageDir, 'punk-records');
+  const brainTarget = path.join(process.cwd(), 'brain');
+
+  if (fs.existsSync(brainTarget)) {
+    const files = await fs.readdir(brainTarget);
+    if (files.length > 0) {
+      outro(chalk.yellow('brain/ already exists with files. Skipping to avoid overwriting.'));
+      return;
+    }
+  }
+
+  const s = spinner();
+  s.start('Initializing Punk Records...');
+
+  await fs.ensureDir(brainTarget);
+
+  const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md'];
+  for (const template of templates) {
+    const src = path.join(brainSource, template);
+    const dest = path.join(brainTarget, template);
+    await fs.copy(src, dest);
+  }
+
+  // Replace project name placeholder
+  const logPosePath = path.join(brainTarget, 'log-pose.md');
+  const logPose = await fs.readFile(logPosePath, 'utf-8');
+  const projectName = path.basename(process.cwd());
+  await fs.writeFile(logPosePath, logPose.replace('{project-name}', projectName));
+
+  s.stop('Punk Records initialized');
+
+  outro(chalk.green('brain/ is ready.') + ' Files: log-pose.md, architecture.md, vivre-cards.md, ideas.md');
+}
+
+module.exports = { init };

package/cli/install.js

@@ -0,0 +1,138 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { intro, outro, select, confirm, spinner, note } = require('@clack/prompts');
+const chalk = require('chalk');
+
+const SKILLS = [
+  'stella-protocol',
+  'stella-define',
+  'stella-build',
+  'stella-review',
+  'stella-close',
+];
+
+function detectAITool() {
+  const cwd = process.cwd();
+  const home = process.env.HOME || process.env.USERPROFILE;
+
+  // Check for Claude Code
+  if (fs.existsSync(path.join(cwd, '.claude')) || fs.existsSync(path.join(home, '.claude'))) {
+    return 'claude';
+  }
+
+  // Check for Cursor
+  if (fs.existsSync(path.join(cwd, '.cursor')) || fs.existsSync(path.join(home, '.cursor'))) {
+    return 'cursor';
+  }
+
+  return null;
+}
+
+function getSkillsDir(tool, scope) {
+  const home = process.env.HOME || process.env.USERPROFILE;
+  const cwd = process.cwd();
+
+  if (tool === 'claude') {
+    return scope === 'project'
+      ? path.join(cwd, '.claude', 'skills')
+      : path.join(home, '.claude', 'skills');
+  }
+
+  if (tool === 'cursor') {
+    return scope === 'project'
+      ? path.join(cwd, '.cursor', 'skills')
+      : path.join(home, '.cursor', 'skills');
+  }
+
+  // Generic fallback
+  return path.join(cwd, '.ai-skills');
+}
+
+async function install() {
+  intro(chalk.bold('THE STELLA PROTOCOL') + chalk.dim(' — One mind, many satellites.'));
+
+  // Detect AI tool
+  const detected = detectAITool();
+  const toolLabel = detected === 'claude' ? 'Claude Code' : detected === 'cursor' ? 'Cursor' : null;
+
+  if (toolLabel) {
+    note(`Detected: ${chalk.green(toolLabel)}`, 'Environment');
+  }
+
+  const tool = detected || 'claude';
+
+  // Ask installation scope
+  const scope = await select({
+    message: 'Where should skills be installed?',
+    options: [
+      { value: 'project', label: 'This project', hint: 'recommended' },
+      { value: 'user', label: 'My user profile', hint: 'available in all projects' },
+    ],
+  });
+
+  if (typeof scope === 'symbol') {
+    outro('Installation cancelled.');
+    return;
+  }
+
+  // Ask about Punk Records
+  const initBrain = await confirm({
+    message: 'Initialize Punk Records (brain/) in this project?',
+    initialValue: true,
+  });
+
+  if (typeof initBrain === 'symbol') {
+    outro('Installation cancelled.');
+    return;
+  }
+
+  // Install skills
+  const s = spinner();
+  s.start('Installing skills...');
+
+  const packageDir = path.resolve(__dirname, '..');
+  const skillsSource = path.join(packageDir, 'skills');
+  const skillsTarget = getSkillsDir(tool, scope);
+
+  await fs.ensureDir(skillsTarget);
+
+  for (const skill of SKILLS) {
+    const src = path.join(skillsSource, skill);
+    const dest = path.join(skillsTarget, skill);
+    await fs.copy(src, dest, { overwrite: true });
+  }
+
+  s.stop(`${SKILLS.length} skills installed to ${chalk.dim(skillsTarget)}`);
+
+  // Initialize Punk Records
+  if (initBrain) {
+    const brainS = spinner();
+    brainS.start('Initializing Punk Records...');
+
+    const brainSource = path.join(packageDir, 'punk-records');
+    const brainTarget = path.join(process.cwd(), 'brain');
+
+    await fs.ensureDir(brainTarget);
+
+    const templates = ['log-pose.md', 'architecture.md', 'vivre-cards.md', 'ideas.md'];
+    for (const template of templates) {
+      const src = path.join(brainSource, template);
+      const dest = path.join(brainTarget, template);
+      if (!fs.existsSync(dest)) {
+        await fs.copy(src, dest);
+      }
+    }
+
+    // Replace project name placeholder in log-pose
+    const logPosePath = path.join(brainTarget, 'log-pose.md');
+    const logPose = await fs.readFile(logPosePath, 'utf-8');
+    const projectName = path.basename(process.cwd());
+    await fs.writeFile(logPosePath, logPose.replace('{project-name}', projectName));
+
+    brainS.stop(`Punk Records initialized at ${chalk.dim(brainTarget)}`);
+  }
+
+  outro(chalk.green('Ready.') + ' Start by telling your AI what you want to build.');
+}
+
+module.exports = { install };

package/cli/status.js

@@ -0,0 +1,41 @@
+const path = require('path');
+const fs = require('fs-extra');
+const chalk = require('chalk');
+
+async function status() {
+  const brainDir = path.join(process.cwd(), 'brain');
+  const logPosePath = path.join(brainDir, 'log-pose.md');
+
+  if (!fs.existsSync(logPosePath)) {
+    console.log(chalk.yellow('No brain/log-pose.md found.'));
+    console.log('Run ' + chalk.bold('stella init') + ' to initialize Punk Records.');
+    return;
+  }
+
+  const content = await fs.readFile(logPosePath, 'utf-8');
+
+  // Parse frontmatter
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (fmMatch) {
+    const fm = fmMatch[1];
+    const lines = fm.split('\n').filter(Boolean);
+
+    console.log(chalk.bold('\n  THE STELLA PROTOCOL — Project Status\n'));
+
+    for (const line of lines) {
+      const [key, ...valueParts] = line.split(':');
+      const value = valueParts.join(':').trim();
+      if (key && value) {
+        const label = key.trim().replace(/"/g, '');
+        console.log(`  ${chalk.dim(label + ':')} ${value}`);
+      }
+    }
+    console.log('');
+  }
+
+  // Print body (skip frontmatter)
+  const body = content.replace(/^---\n[\s\S]*?\n---\n*/, '');
+  console.log(body);
+}
+
+module.exports = { status };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "stella-protocol",
+  "version": "0.1.0",
+  "description": "PM-first AI development protocol. One mind, many satellites.",
+  "bin": {
+    "stella": "./cli/index.js"
+  },
+  "files": [
+    "protocol/",
+    "punk-records/",
+    "skills/",
+    "cli/",
+    ".claude-plugin/"
+  ],
+  "keywords": [
+    "ai",
+    "agent-skills",
+    "product-management",
+    "development-methodology",
+    "stella-protocol",
+    "ai-native",
+    "pm-tools"
+  ],
+  "author": {
+    "name": "Aditya Uttama",
+    "url": "https://github.com/adityauttama"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/adityauttama/stella-protocol.git"
+  },
+  "homepage": "https://github.com/adityauttama/stella-protocol",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "@clack/prompts": "^1.0.0",
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.3.0"
+  }
+}

package/protocol/governance/buster-call.md

@@ -0,0 +1,74 @@
+# Buster Call — Veto Protocol
+
+> The power to stop everything when something is critically wrong.
+
+## Purpose
+
+Buster Call is the Stella Protocol's veto mechanism. Any satellite can issue a Buster Call when it identifies an issue that could compromise the project's integrity, security, or viability.
+
+Unlike optional review tools, Buster Call is **always active**. Every satellite has the authority and responsibility to flag critical issues.
+
+---
+
+## Severity Levels
+
+### CONCERN
+- **Impact:** Low. Something worth noting but not blocking.
+- **Action:** Log to `brain/vivre-cards.md`. Work continues.
+- **Example:** A dependency has a newer major version available.
+
+### WARNING
+- **Impact:** Medium. A real issue that Stella should weigh in on.
+- **Action:** Flag to Stella with recommendation. Work continues pending response.
+- **Stella response:** Acknowledge, adjust, or dismiss with reasoning.
+- **Example:** The proposed data model doesn't account for a likely future requirement.
+
+### BUSTER CALL
+- **Impact:** Critical. Proceeding would cause serious harm.
+- **Action:** Work stops immediately. Satellite refuses to proceed.
+- **Stella response required:** Must resolve, adjust approach, or explicitly override.
+- **Example:** SQL injection vulnerability in production code. Auth bypass in API. PRD contradicts legal requirements.
+
+---
+
+## Format
+
+When issuing a Buster Call at any severity:
+
+```
+⚠️ [SEVERITY] — [SATELLITE NAME]
+Issue: [specific problem identified]
+Impact: [what breaks or degrades if we proceed]
+Recommendation: [what to do instead]
+Status: Awaiting Stella's decision.
+```
+
+---
+
+## Override
+
+Stella can override any Buster Call, including BUSTER CALL severity:
+
+```
+Override — [reason for proceeding despite the finding]
+```
+
+Overrides are logged to `brain/vivre-cards.md` with timestamp and reasoning. Satellites respect the override and proceed.
+
+---
+
+## Who Can Issue
+
+Every satellite has Buster Call authority. The most common issuers:
+
+- **Lilith Red** — Security vulnerabilities, abuse vectors, privacy risks
+- **Shaka** — Scope contradictions, requirement conflicts
+- **Pythagoras** — Architecture problems, scaling bottlenecks
+- **Lilith Blue** — Test coverage gaps, untestable code
+- **Edison** — Implementation impossibilities, technical debt traps
+
+---
+
+## Phase Gates
+
+Buster Call status is checked at every phase transition. The orchestrator will not approve a phase transition if any unresolved BUSTER CALL exists. WARNINGS and CONCERNS do not block transitions but are surfaced for awareness.

package/protocol/governance/cipher-pol.md

@@ -0,0 +1,77 @@
+# Cipher Pol — Scope Enforcement Protocol
+
+> Silent watchers that ensure no one drifts from the mission.
+
+## Purpose
+
+Cipher Pol is the Stella Protocol's scope enforcement mechanism. It continuously monitors all satellite work against the approved PRD (Road Poneglyph) to detect and flag scope drift.
+
+Unlike a review you invoke, Cipher Pol is **always active**. Every satellite that produces or modifies artifacts checks its work against the approved scope.
+
+---
+
+## How It Works
+
+1. Every satellite reads the active PRD before beginning work
+2. As work progresses, the satellite continuously compares output against PRD scope
+3. When drift is detected, it is classified by severity and flagged
+4. Stella decides whether to approve the drift, reject it, or amend the PRD
+
+---
+
+## Severity Levels
+
+### INTEL
+- **Drift:** Minor. Within the spirit of the PRD but not explicitly specified.
+- **Action:** Noted in `brain/log-pose.md` under Cipher Pol Report. Work continues.
+- **Example:** Adding a loading spinner not mentioned in the PRD.
+
+### ALERT
+- **Drift:** Moderate. A meaningful addition or change to the approved scope.
+- **Action:** Flagged to Stella. Work continues only if Stella approves.
+- **Stella response:** Approve (continue), reject (revert), or amend PRD.
+- **Example:** Adding an export feature not in the PRD but related to existing functionality.
+
+### INTERCEPT
+- **Drift:** Significant. A new feature, major UX change, or architectural shift.
+- **Action:** Blocked. Cannot proceed without PRD amendment.
+- **Stella response:** Must create a PRD amendment before work continues.
+- **Example:** Adding a user roles system when the PRD specifies single-user only.
+
+---
+
+## Format
+
+When flagging scope drift:
+
+```
+🔍 CIPHER POL [SEVERITY]
+Drift: [what's being added/changed]
+PRD says: [what the approved scope specifies]
+Gap: [the delta between approved and proposed]
+Recommendation: [approve / reject / amend PRD]
+```
+
+---
+
+## PRD Amendments
+
+When scope drift is approved, it must be formalized:
+
+1. Append an amendment to the existing PRD with date, rationale, and change description
+2. Log the amendment decision in `brain/vivre-cards.md`
+3. Update `brain/log-pose.md` to reflect the expanded scope
+
+---
+
+## The 30% Rule
+
+When accumulated amendments represent more than ~30% new surface area beyond the original PRD, Cipher Pol recommends returning to the DEFINE phase for a full PRD v2. This prevents scope from growing unbounded through incremental drift.
+
+---
+
+## When Cipher Pol Is Not Active
+
+- **IDEATE phase** — No PRD exists yet. Scope enforcement doesn't apply.
+- **East Blue track before PRD** — If working from a Mini-PRD, Cipher Pol monitors against that.
+- **Explicit exploration** — If Stella says "explore freely," Cipher Pol logs but does not flag.