product-design-ceo-orchestrator 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kai Zhang
+
+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,211 @@
+# Product Design CEO Orchestrator
+
+A reusable agent skill for product-management and product-design work that benefits from CEO-style orchestration without unnecessary ceremony.
+
+The skill helps an agent decide when to answer directly, when to use a few product-role perspectives, and when to create a full multi-phase workspace for durable product artifacts such as PRDs, feature proposals, UI demo plans, competitor research, product reviews, and roadmap strategy.
+
+## What This Skill Optimizes For
+
+- correct scope before execution
+- the lightest useful workflow
+- explicit role selection
+- evidence-aware product recommendations
+- final integrated artifacts instead of scattered notes
+- clear validation before claiming completion
+
+## When It Activates
+
+Use this skill when the user asks for durable product-design work such as:
+
+- PRDs and requirements
+- feature design and user flows
+- product strategy and roadmap thinking
+- competitor or market research
+- user research synthesis
+- product reviews
+- UI demo or prototype planning
+- turning a product idea into execution-ready artifacts
+
+For tiny copy tweaks or narrow UX opinions, the skill intentionally downgrades to a lightweight manager-only response.
+
+## Repository Layout
+
+```text
+.
+├── SKILL.md
+├── README.md
+├── LICENSE
+├── package.json
+├── skill.json
+├── bin/
+│   └── product-design-ceo-orchestrator.js
+├── lib/
+│   └── install.js
+├── references/
+│   ├── kb-policy.md
+│   ├── orchestration-model.md
+│   ├── role-catalog.md
+│   └── workspace-structure.md
+└── tests/
+    ├── install.test.js
+    └── pressure-scenarios.md
+```
+
+## Install
+
+### npm / npx
+
+Install explicitly with `npx`:
+
+```bash
+npx product-design-ceo-orchestrator install --ai codex
+```
+
+Supported explicit targets:
+
+```bash
+npx product-design-ceo-orchestrator install --ai codex
+npx product-design-ceo-orchestrator install --ai claude
+npx product-design-ceo-orchestrator install --ai cursor
+```
+
+Overwrite an existing local copy:
+
+```bash
+npx product-design-ceo-orchestrator install --ai codex --force
+```
+
+Install into a custom agent skills directory:
+
+```bash
+npx product-design-ceo-orchestrator install \
+  --target ~/.my-agent/skills/product-design-ceo-orchestrator
+```
+
+Preview the target path without writing files:
+
+```bash
+npx product-design-ceo-orchestrator install --ai codex --dry-run
+```
+
+### Codex
+
+Manual Git install for Codex:
+
+```bash
+mkdir -p ~/.codex/skills
+git clone https://github.com/burpeepoo/product-design-ceo-orchestrator.git \
+  ~/.codex/skills/product-design-ceo-orchestrator
+```
+
+Restart Codex or open a new session after installation.
+
+### Claude Code
+
+Manual Git install for Claude Code:
+
+```bash
+mkdir -p ~/.claude/skills
+git clone https://github.com/burpeepoo/product-design-ceo-orchestrator.git \
+  ~/.claude/skills/product-design-ceo-orchestrator
+```
+
+### Other Agent Runtimes
+
+If your agent supports local skills, copy or clone this repository into that runtime's skills directory. The required entry point is:
+
+```text
+SKILL.md
+```
+
+The `references/` and `tests/` folders should stay next to `SKILL.md`.
+
+## Update
+
+If installed with npm / npx, re-run the explicit install with `--force`:
+
+```bash
+npx product-design-ceo-orchestrator@latest install --ai codex --force
+```
+
+If installed with Git, update an installed copy with:
+
+```bash
+cd ~/.codex/skills/product-design-ceo-orchestrator
+git pull --ff-only
+```
+
+Use the equivalent path for other agent runtimes.
+
+## Usage
+
+Ask naturally for product-design help. Examples:
+
+```text
+Draft a PRD for calendar conflict reminders.
+```
+
+```text
+Review this product idea quickly. Do not make a big framework.
+```
+
+```text
+Design a UI demo for a new family weekly report experience. I need something execution-ready.
+```
+
+The skill chooses among three operating modes:
+
+| Mode | Use when | Output |
+|---|---|---|
+| None | quick critique, copy, narrow UX suggestion | chat answer |
+| Light | medium PRD, proposal, review, flow, research summary | one integrated Markdown artifact |
+| Full | complex work with roles, phases, KB, artifacts, or handoff | workspace with `outputs/final.md` |
+
+## Validation
+
+The skill includes pressure scenarios in `tests/pressure-scenarios.md`. Use them when changing the skill to verify it still:
+
+- avoids over-orchestration
+- uses role perspectives only when they add distinct value
+- records KB and evidence status when needed
+- backs current market or competitor claims with sources
+- finishes durable work with one integrated recommendation
+
+Basic static checks:
+
+```bash
+npm test
+npm pack --dry-run
+test -s SKILL.md
+test -s references/orchestration-model.md
+test -s references/role-catalog.md
+test -s references/workspace-structure.md
+test -s references/kb-policy.md
+test -s tests/pressure-scenarios.md
+rg -n "description: Use when|Quick Decision Table|Role Selection Matrix|Workspace Modes|Pressure Scenarios" .
+```
+
+## Publishing Workflow
+
+Future updates should be committed and pushed to this repository:
+
+```bash
+git status -sb
+git add SKILL.md README.md LICENSE package.json skill.json .gitignore bin lib references tests
+git commit -m "update product design ceo orchestrator skill"
+git push
+```
+
+For npm releases:
+
+```bash
+npm test
+npm pack --dry-run
+npm publish
+```
+
+For larger behavior changes, update `tests/pressure-scenarios.md` first so the expected behavior is explicit before editing the skill.
+
+## License
+
+MIT. See `LICENSE`.

package/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: product-design-ceo-orchestrator
+description: Use when the user asks for durable product-design work such as PRDs, requirements, feature design, product strategy, competitor or market research, user research, product review, UI demo planning, prototype planning, roadmap thinking, or turning a product idea into execution-ready artifacts.
+---
+
+# Product Design CEO Orchestrator
+
+Act as the smallest useful product leadership system before acting as an individual contributor. The goal is not to maximize ceremony; it is to preserve user intent, gather the right evidence, choose the right roles, and finish with one integrated artifact.
+
+## Start
+
+1. Respond in the language the user is using unless they ask otherwise.
+2. Classify the request before doing product work: simple, medium, or complex.
+3. State the orchestration decision briefly using the first response templates below.
+4. If durable, plan roles, phases, KB needs, workspace mode, and final artifact before executing.
+5. Default to one agent executing phases in order. Suggest parallel or sub-agent execution only when tasks are independent and the environment supports it clearly.
+
+## Quick Decision Table
+
+| Request shape | Classification | Workspace | Roles | First action | Final output |
+|---|---|---|---|---|---|
+| Copy tweak, short UX opinion, one-screen critique, narrow wording | Simple | None | Manager only | Answer directly | Chat answer unless files requested |
+| PRD draft, feature proposal, user flow refinement, small product review | Medium | Light document when useful | Manager plus 1-3 role perspectives | State selected perspectives, then execute | One integrated Markdown artifact |
+| UI demo, prototype plan, new product concept, strategy with implementation impact, ambiguous market or user problem | Complex | Full workspace | Formal selected roles | Create orchestration plan first | `outputs/final.md` plus artifacts |
+
+Use multi-role orchestration when the task needs at least two of: user understanding, market or competitor evidence, requirement definition, interaction or design output, technical review, data or ops analysis, QA or acceptance, and final synthesis.
+
+Always create a final integration phase for complex tasks so outputs do not remain scattered.
+
+## First Response Templates
+
+Use the lightest template that fits.
+
+Simple:
+
+> This is narrow enough to handle directly. I will use the manager lens only and keep the answer focused.
+
+Medium:
+
+> I will treat this as a medium product-design task: use a few role perspectives in sequence, avoid a heavy workspace unless useful, and end with one integrated artifact. Selected roles: [roles]. KB needed: [sources or assumptions].
+
+Complex:
+
+> I will treat this as a complex product-design task: first create the orchestration plan, then execute phases in order, and finish with one integrated result plus paths. Selected roles: [roles]. Workspace mode: full. KB needed: [sources or assumptions].
+
+When missing information materially changes the answer, ask 1-3 concise questions before execution. Do not block on minor gaps; mark assumptions and continue.
+
+## Over-Orchestration Red Flags
+
+Stop and downgrade the workflow when any of these appear:
+
+- The user asked for a quick wording, small critique, or narrow opinion.
+- The answer would fit in one concise response and no durable artifact was requested.
+- Role files would restate obvious perspectives without adding evidence or decisions.
+- A workspace would create more navigation burden than reusable value.
+- The user explicitly asks to keep it lightweight or fast.
+- You are creating phases because the skill says "CEO" rather than because the task needs them.
+
+## Sub-Skill Split Criteria
+
+Keep this as one skill unless repeated use shows a specific section needs independent triggering. Split into a sub-skill only when all are true:
+
+- The section has a distinct trigger that users or agents would search for directly.
+- The section has its own workflow, inputs, outputs, and validation.
+- Keeping it here makes the main skill harder to use.
+- Pressure scenarios show agents repeatedly misuse or skip that section.
+
+Likely future split candidates are competitor research, UI demo orchestration, PRD writing, and skill pressure testing. Do not split them preemptively.
+
+## Workflow
+
+1. Classify the request: simple / medium / complex.
+2. State the orchestration decision briefly:
+   - roles needed
+   - phases needed
+   - KB needed
+   - execution mode
+   - missing inputs, if any
+3. Choose workspace mode from `references/workspace-structure.md`: none / light / full.
+4. Choose roles from `references/role-catalog.md`; create role boundary files only for selected roles in full workspace mode.
+5. For medium work, keep the orchestration plan in the response or light-mode `README.md`. For complex work, create `orchestration-plan.md` with phases, tasks, dependencies, expected outputs, and final synthesis criteria.
+6. Execute in order: understand -> define -> design or write -> review -> final integration.
+7. Save durable final output to the selected output path. In full workspace mode, use `outputs/final.md` and put non-Markdown artifacts under `outputs/artifacts/`.
+8. Update `reflections.md` only for durable tasks where reusable lessons or follow-ups emerged.
+
+## References
+
+- Read `references/orchestration-model.md` when deciding whether to split roles/tasks.
+- Read `references/role-catalog.md` when creating role files or assigning work.
+- Read `references/workspace-structure.md` before creating directories.
+- Read `references/kb-policy.md` before asking for files, folders, links, screenshots, data, or existing docs.
+- Use `tests/pressure-scenarios.md` when verifying edits to this skill or checking whether it resists over-orchestration.
+
+## Output Contract
+
+Every durable task must end with:
+
+- orchestration decision
+- roles and phases used
+- KB used or requested
+- final artifact summary
+- output paths, or an explicit note that no files were created
+- unresolved risks or follow-ups
+
+## Final Validation Checklist
+
+Before claiming a durable task is complete, verify:
+
+- User goal is restated and the final artifact answers it.
+- Classification, workspace mode, selected roles, and phases are recorded.
+- Facts, assumptions, recommendations, and evidence gaps are separated.
+- Current market or competitor claims are backed by browsing or user-provided sources.
+- The final integration resolves conflicts between role outputs instead of pasting them together.
+- Non-goals, risks, and follow-ups are explicit.
+- Output paths exist when files were promised.
+- The response names any validation that was not performed.

package/bin/product-design-ceo-orchestrator.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+const path = require("node:path");
+const { copySkill, resolveInstallDir, AI_TARGETS } = require("../lib/install");
+const packageJson = require("../package.json");
+
+function usage() {
+  const supported = Object.keys(AI_TARGETS).join("|");
+  return `Product Design CEO Orchestrator
+
+Usage:
+  product-design-ceo-orchestrator install --ai ${supported} [--force]
+  product-design-ceo-orchestrator install --target <directory> [--force]
+  product-design-ceo-orchestrator --help
+  product-design-ceo-orchestrator --version
+
+Examples:
+  npx product-design-ceo-orchestrator install --ai codex
+  npx product-design-ceo-orchestrator install --ai claude --force
+  npx product-design-ceo-orchestrator install --target ~/.my-agent/skills/product-design-ceo-orchestrator
+`;
+}
+
+function parseArgs(argv) {
+  const options = {
+    command: null,
+    ai: null,
+    targetDir: null,
+    force: false,
+    dryRun: false,
+    help: false,
+    version: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (index === 0 && !arg.startsWith("-")) {
+      options.command = arg;
+      continue;
+    }
+
+    if (arg === "--ai") {
+      options.ai = argv[++index];
+    } else if (arg === "--target") {
+      options.targetDir = argv[++index];
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--dry-run") {
+      options.dryRun = true;
+    } else if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--version" || arg === "-v") {
+      options.version = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function main(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+
+  if (options.version) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  if (options.help || !options.command) {
+    console.log(usage());
+    return;
+  }
+
+  if (options.command !== "install") {
+    throw new Error(`Unknown command: ${options.command}`);
+  }
+
+  const destination = resolveInstallDir({
+    ai: options.ai,
+    targetDir: options.targetDir,
+  });
+
+  if (options.dryRun) {
+    console.log(`Would install to: ${destination}`);
+    return;
+  }
+
+  const result = copySkill({
+    packageRoot: path.resolve(__dirname, ".."),
+    destination,
+    force: options.force,
+  });
+
+  console.log(`Installed product-design-ceo-orchestrator to ${result.destination}`);
+  console.log(`Copied ${result.files.length} files.`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  console.error("");
+  console.error(usage());
+  process.exitCode = 1;
+}

package/lib/install.js

@@ -0,0 +1,96 @@
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const SKILL_NAME = "product-design-ceo-orchestrator";
+
+const AI_TARGETS = {
+  codex: [".codex", "skills"],
+  claude: [".claude", "skills"],
+  cursor: [".cursor", "skills"],
+};
+
+const INSTALL_ENTRIES = [
+  "SKILL.md",
+  "README.md",
+  "LICENSE",
+  "skill.json",
+  path.join("references", "kb-policy.md"),
+  path.join("references", "orchestration-model.md"),
+  path.join("references", "role-catalog.md"),
+  path.join("references", "workspace-structure.md"),
+  path.join("tests", "pressure-scenarios.md"),
+];
+
+function expandHome(input, homeDir = os.homedir()) {
+  if (input === "~") {
+    return homeDir;
+  }
+  if (input.startsWith("~/")) {
+    return path.join(homeDir, input.slice(2));
+  }
+  return input;
+}
+
+function resolveInstallDir({ ai, targetDir, homeDir = os.homedir() }) {
+  if (targetDir) {
+    return path.resolve(expandHome(targetDir, homeDir));
+  }
+
+  if (!ai) {
+    throw new Error("Pass --ai codex|claude|cursor or --target <directory>.");
+  }
+
+  const normalized = ai.toLowerCase();
+  const parts = AI_TARGETS[normalized];
+
+  if (!parts) {
+    throw new Error(
+      `Unsupported --ai "${ai}". Supported: ${Object.keys(AI_TARGETS).join(", ")}.`,
+    );
+  }
+
+  return path.join(homeDir, ...parts, SKILL_NAME);
+}
+
+function copyFileWithParents(source, destination) {
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(source, destination);
+}
+
+function copySkill({ packageRoot, destination, force = false }) {
+  const sourceSkill = path.join(packageRoot, "SKILL.md");
+  if (!fs.existsSync(sourceSkill)) {
+    throw new Error(`Cannot find SKILL.md in package root: ${packageRoot}`);
+  }
+
+  if (fs.existsSync(destination)) {
+    if (!force) {
+      throw new Error(
+        `${destination} already exists. Re-run with --force to overwrite it.`,
+      );
+    }
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+
+  for (const entry of INSTALL_ENTRIES) {
+    const source = path.join(packageRoot, entry);
+    if (!fs.existsSync(source)) {
+      throw new Error(`Missing package file: ${entry}`);
+    }
+    copyFileWithParents(source, path.join(destination, entry));
+  }
+
+  return {
+    destination,
+    files: INSTALL_ENTRIES.slice(),
+  };
+}
+
+module.exports = {
+  AI_TARGETS,
+  INSTALL_ENTRIES,
+  SKILL_NAME,
+  copySkill,
+  resolveInstallDir,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "product-design-ceo-orchestrator",
+  "version": "0.2.0",
+  "description": "Installable agent skill for product-design orchestration, PRDs, strategy, research, product reviews, and UI demo planning.",
+  "license": "MIT",
+  "author": "Kai Zhang",
+  "homepage": "https://github.com/burpeepoo/product-design-ceo-orchestrator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/burpeepoo/product-design-ceo-orchestrator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/burpeepoo/product-design-ceo-orchestrator/issues"
+  },
+  "bin": {
+    "product-design-ceo-orchestrator": "bin/product-design-ceo-orchestrator.js",
+    "pdco": "bin/product-design-ceo-orchestrator.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "references/",
+    "tests/pressure-scenarios.md",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "skill.json"
+  ],
+  "scripts": {
+    "test": "node --test tests/install.test.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "agent-skill",
+    "codex",
+    "claude",
+    "product-design",
+    "product-management",
+    "prd",
+    "requirements",
+    "strategy",
+    "ui-demo"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/kb-policy.md

@@ -0,0 +1,59 @@
+# Knowledge Base Policy
+
+KB means the material that should inform the product-design work.
+
+## Decide KB Needs
+
+Ask for or search local context when the task depends on:
+
+- existing product docs
+- screenshots or UI flows
+- user feedback
+- analytics or funnel data
+- competitor references
+- brand/design system
+- technical constraints
+- existing code or repo behavior
+- prior decisions or roadmaps
+
+## Ask the User When
+
+Ask 1-3 concise questions when missing information changes the output materially.
+
+Examples:
+- target user is unknown
+- product stage is unknown
+- output format is unclear
+- source docs or screenshots are required
+- competitor list is required and browsing is not enough
+- implementation platform matters
+
+Do not block on minor gaps. Mark assumptions and continue.
+
+## Record KB Status
+
+In `kb/README.md`, record:
+
+- needed sources
+- provided sources
+- sources used
+- sources intentionally not used
+- open evidence gaps
+
+## Use Evidence Carefully
+
+- Do not claim current market facts without browsing or user-provided sources.
+- Do not treat a local folder path as permission to summarize everything unless the user allowed it.
+- Distinguish facts, assumptions, and recommendations.
+- For screenshots/images, state what was visually inferred.
+- For data files, state metric definitions, timeframe, and uncertainty.
+
+## Output Evidence
+
+Final output should include:
+
+- "Used KB" list
+- "Assumptions" list
+- "Evidence gaps" list
+- "What to collect next" when relevant
+

package/references/orchestration-model.md

@@ -0,0 +1,116 @@
+# Orchestration Model
+
+## Goal
+
+Act like a product CEO/manager before acting like an individual contributor. Decide the smallest useful team and workflow for the user's product-design request.
+
+## Decision Table
+
+| Signal | Use | Do not use |
+|---|---|---|
+| User asks for quick wording, a short critique, or a narrow decision | Simple | Medium or complex ceremony |
+| User asks for a PRD, feature proposal, flow, product review, or roadmap slice | Medium | Full workspace unless files or phases matter |
+| User asks for UI demo, prototype, new product concept, broad strategy, or ambiguous problem framing | Complex | Single-role answer |
+| User provides or requests source docs, screenshots, analytics, competitors, or implementation constraints | KB-aware medium or complex | Evidence-free recommendation |
+| User explicitly says "keep it light", "quick", or "no big process" | Downgrade one level | Forced role split |
+
+If two signals conflict, preserve the user's explicit preference first, then choose the smallest workflow that can still produce a correct answer.
+
+## Complexity
+
+### Simple
+
+Use one agent and no workspace unless the user asks for files.
+
+Examples:
+- button copy
+- short UX critique
+- one-screen wording
+- quick product opinion
+
+Still state why no multi-role split is needed, but keep it to one sentence.
+
+### Medium
+
+Use several role perspectives but execute sequentially in one agent.
+
+Examples:
+- PRD draft
+- feature proposal
+- small competitor scan
+- user flow refinement
+- product review with clear context
+
+Recommended phases:
+1. understand
+2. define
+3. design or write
+4. review
+5. final synthesis
+
+Use a light document when the result should be reusable. Do not create role files unless the task grows into complex work.
+
+### Complex
+
+Use formal roles, phase folders, explicit KB, and final integration.
+
+Examples:
+- UI Demo or prototype
+- new product concept
+- large PRD
+- ambiguous market/user problem
+- strategy with implementation implications
+- work that needs design + technical + review perspectives
+
+Default phases:
+1. Understand problem: user, scenario, market, competitor, constraints.
+2. Define product: goals, scope, requirements, acceptance criteria.
+3. Design output: IA, flow, UI, prototype, PRD, demo, or artifact.
+4. Review: product goal fit, technical feasibility, risks.
+5. Final integration: one CEO-readable final result and paths.
+
+## Split Rules
+
+Split into roles when:
+- evidence and design judgment are both needed
+- solution quality depends on multiple viewpoints
+- output will be reviewed or implemented
+- user asks for a demo, PRD, competitive analysis, roadmap, or prototype
+
+Do not split when:
+- one narrow answer is enough
+- user explicitly wants speed over rigor
+- role output would be fake busywork
+- selected roles cannot produce distinct decisions or evidence
+- the "role" would only rename the same reasoning
+
+## Execution Mode
+
+Default: one agent executes roles sequentially and labels each role's contribution.
+
+Suggest parallel/sub-agent execution only when:
+- tasks are independent
+- the environment supports subagents
+- the user wants speed
+- each subagent can get clear context and output contract
+
+## Required CEO Decisions
+
+Before executing, produce:
+- task classification
+- selected roles
+- selected phases
+- KB needed
+- workspace mode and directory plan
+- output artifacts
+- assumptions and open questions
+
+## First Response Shape
+
+Keep the first response proportional to the task:
+
+- Simple: one sentence explaining direct handling, then answer.
+- Medium: one short paragraph naming roles, KB status, and expected artifact.
+- Complex: a concise plan with roles, phases, workspace mode, KB status, and final integration criteria.
+
+Do not turn the first response into a full final artifact unless the request is simple.

package/references/role-catalog.md

@@ -0,0 +1,134 @@
+# Role Catalog
+
+Use only the smallest useful set of roles.
+
+## Role Selection Matrix
+
+Always include CEO / Manager for durable tasks. Add only roles that can create distinct evidence, decisions, or quality checks.
+
+| Task type | Default roles | Add only when |
+|---|---|---|
+| Quick wording or narrow UX critique | CEO / Manager | Product Designer if visual or interaction behavior matters |
+| PRD or requirements | CEO / Manager, Requirements Specialist, QA / Acceptance Specialist | Tech Lead for implementation constraints; User Researcher when user evidence is thin |
+| Feature proposal | CEO / Manager, User Researcher, Requirements Specialist, Product Designer | Data / Operations Analyst when metrics or experiments matter |
+| Product review | CEO / Manager, Product Designer, QA / Acceptance Specialist | Tech Lead for feasibility; Data / Operations Analyst for performance or funnel questions |
+| UI demo or prototype plan | CEO / Manager, Product Designer, Requirements Specialist, Tech Lead, QA / Acceptance Specialist | User Researcher for unclear scenarios; Market Analyst for category conventions |
+| Competitor or market research | CEO / Manager, Market Analyst | Product Designer for UX comparison; Requirements Specialist when research must become scope |
+| Roadmap or strategy | CEO / Manager, Market Analyst, Data / Operations Analyst, Requirements Specialist | Tech Lead for sequencing constraints; User Researcher for segment uncertainty |
+
+Role selection rules:
+
+- Prefer 2-4 roles for medium tasks.
+- Use 5+ roles only for complex tasks with real cross-functional risk.
+- Do not create a role file for a role that only contributes generic commentary.
+- If a role depends on missing evidence, record the gap instead of inventing the role's findings.
+
+## CEO / Manager
+
+Owns orchestration, scope, priorities, tradeoffs, dependencies, and final synthesis.
+
+Inputs:
+- CEO brief
+- all role outputs
+- user constraints
+
+Outputs:
+- orchestration plan
+- final integrated artifact
+- risks and next steps
+
+Boundaries:
+- must not invent missing evidence as fact
+- must preserve user intent over role preferences
+
+## User Researcher
+
+Owns user scenarios, jobs-to-be-done, pain points, behavior assumptions, and validation needs.
+
+Outputs:
+- user segments
+- scenarios
+- needs and anxieties
+- research gaps
+
+Boundaries:
+- mark assumptions clearly when no user evidence is provided
+
+## Market Analyst
+
+Owns competitor landscape, positioning, alternatives, differentiation, and market signals.
+
+Outputs:
+- competitor map
+- feature/positioning comparison
+- opportunity and risk notes
+
+Boundaries:
+- current market facts require browsing or user-provided sources
+- do not fabricate competitor details
+
+## Requirements Specialist
+
+Owns PRD, scope, flows, user stories, acceptance criteria, edge cases, and non-goals.
+
+Outputs:
+- requirement breakdown
+- acceptance criteria
+- open questions
+- implementation-ready scope
+
+Boundaries:
+- does not decide visual direction alone
+- escalates vague business goals to the manager
+
+## Product Designer
+
+Owns information architecture, interaction model, UI states, visual hierarchy, prototype or UI demo direction.
+
+Outputs:
+- IA and flows
+- wireframe/prototype guidance
+- UI demo or design spec
+- state and empty/error/loading behavior
+
+Boundaries:
+- design must trace back to user needs and product goals
+
+## Tech Lead
+
+Owns feasibility, implementation risks, architecture constraints, integration paths, and engineering tradeoffs.
+
+Outputs:
+- feasibility review
+- technical risks
+- suggested implementation slices
+- test/build considerations
+
+Boundaries:
+- does not override product goals without explaining tradeoffs
+
+## Data / Operations Analyst
+
+Owns metrics, funnels, retention, operations loops, experiment design, and data interpretation.
+
+Outputs:
+- KPI tree
+- analysis plan
+- experiment or ops recommendations
+- measurement risks
+
+Boundaries:
+- separate measured facts from assumptions
+
+## QA / Acceptance Specialist
+
+Owns test scenarios, acceptance review, edge cases, quality gates, and release readiness.
+
+Outputs:
+- acceptance checklist
+- test scenarios
+- failure modes
+- release-readiness notes
+
+Boundaries:
+- does not expand product scope; only verifies quality and risks

package/references/workspace-structure.md

@@ -0,0 +1,102 @@
+# Workspace Structure
+
+Create a workspace only for durable tasks that produce files or need multi-step collaboration.
+
+## Workspace Modes
+
+| Mode | Use when | Create | Output |
+|---|---|---|---|
+| None | Simple answers, quick critique, narrow copy or UX suggestion | No files | Chat response |
+| Light | Medium PRD, proposal, review, flow, or research summary that should be reusable | One task folder with one main Markdown file | `{task-slug}/final.md` |
+| Full | Complex work with phases, selected roles, KB tracking, artifacts, or handoff needs | Full structure below | `{task-slug}/outputs/final.md` |
+
+Choose the lightest mode that can preserve the work. Upgrade only when the task gains durable files, multiple phases, or real evidence tracking.
+
+## Light Layout
+
+```text
+{task-slug}/
+  README.md
+  final.md
+  kb-notes.md
+```
+
+Use light layout for medium tasks when a single reusable artifact is enough.
+
+## Full Layout
+
+```text
+{task-slug}/
+  README.md
+  ceo-brief.md
+  orchestration-plan.md
+  kb/
+    README.md
+    sources/
+  roles/
+    manager.md
+    user-researcher.md
+    market-analyst.md
+    requirements-specialist.md
+    product-designer.md
+    tech-lead.md
+  matters/
+    01-understand/
+    02-define/
+    03-design/
+    04-review/
+    05-final-integration/
+  outputs/
+    final.md
+    artifacts/
+  reflections.md
+```
+
+## File Purposes
+
+- `README.md`: task purpose, current status, how to continue.
+- `final.md`: light-mode integrated artifact.
+- `kb-notes.md`: light-mode sources, assumptions, and evidence gaps.
+- `ceo-brief.md`: original user request, assumptions, constraints, requested outputs.
+- `orchestration-plan.md`: roles, phases, dependencies, KB, execution order, output contract.
+- `kb/README.md`: what sources are needed, available, missing, and used.
+- `kb/sources/`: copied or linked local materials when the user allows it.
+- `roles/*.md`: role boundary, inputs, outputs, and current assignment.
+- `matters/*/brief.md`: phase-specific brief.
+- `matters/*/output.md`: phase-specific output.
+- `outputs/final.md`: final CEO-readable synthesis.
+- `outputs/artifacts/`: HTML, images, diagrams, code, spreadsheets, or other deliverables.
+- `reflections.md`: lessons, mistakes, follow-ups, and reusable product insight.
+
+## Creation Rules
+
+- Create nothing for none mode.
+- For light mode, create only `README.md`, `final.md`, and `kb-notes.md` unless the user asks for additional artifacts.
+- Create only role files for selected roles; do not create all role files by default.
+- Create only phase folders that will be used.
+- Keep paths local and explicit.
+- If the user provides a preferred project folder, create inside it.
+- If no folder is provided, ask for one when durable files matter; otherwise use the current workspace.
+- If the task starts in light mode and becomes complex, upgrade by adding the full layout without discarding the existing files.
+
+## Required Plan Fields
+
+Full-mode `orchestration-plan.md` must include:
+
+- CEO brief summary
+- classification: simple / medium / complex
+- workspace mode
+- selected roles and why
+- phases and expected outputs
+- KB needed and current status
+- execution order
+- final artifact path
+- risks and assumptions
+
+Light-mode `README.md` must include:
+
+- original request
+- classification and why light mode was enough
+- selected role perspectives
+- KB used or missing
+- final artifact path

package/skill.json

@@ -0,0 +1,32 @@
+{
+  "name": "product-design-ceo-orchestrator",
+  "displayName": "Product Design CEO Orchestrator",
+  "description": "A product-design orchestration skill for PRDs, feature design, strategy, research, product reviews, UI demo planning, and execution-ready artifacts.",
+  "version": "0.2.0",
+  "author": "Kai Zhang",
+  "license": "MIT",
+  "repository": "https://github.com/burpeepoo/product-design-ceo-orchestrator",
+  "entry": "SKILL.md",
+  "install": "npx product-design-ceo-orchestrator install --ai {{platform}}",
+  "keywords": [
+    "product-design",
+    "product-management",
+    "prd",
+    "requirements",
+    "strategy",
+    "user-research",
+    "market-research",
+    "competitor-analysis",
+    "ui-demo",
+    "prototype",
+    "agent-skill"
+  ],
+  "platforms": [
+    "codex",
+    "claude",
+    "cursor",
+    "windsurf",
+    "gemini",
+    "opencode"
+  ]
+}

package/tests/pressure-scenarios.md

@@ -0,0 +1,164 @@
+# Pressure Scenarios
+
+Use these scenarios when editing this skill or checking whether it remains easy to use. Each scenario should be tested with and without the skill when subagents are available. Without subagents, use them as a manual review checklist against `SKILL.md` and the reference files.
+
+## Success Signals
+
+An agent using this skill should:
+
+- choose the lightest workflow that can produce a correct result
+- explain orchestration decisions briefly
+- ask only material questions
+- avoid fake role work
+- record KB status when evidence matters
+- finish durable work with one integrated artifact and explicit risks
+
+## Scenario 1: Tiny Copy Fix Under Process Temptation
+
+User request:
+
+> Help me improve this button label: "Submit all family changes".
+
+Pressures:
+- The skill has "CEO" in its name.
+- Role and workspace references are available.
+- The agent may want to show process.
+
+Expected behavior:
+- Classify as simple.
+- Use manager only.
+- No workspace, role files, or orchestration plan.
+- Provide the improved label and a short rationale.
+
+Failure this prevents:
+- Creating a multi-role plan for a one-line copy task.
+
+## Scenario 2: Medium PRD Without Heavy Workspace
+
+User request:
+
+> Draft a PRD for calendar conflict reminders. Keep it practical.
+
+Pressures:
+- PRD is durable product-design work.
+- The user asks to keep it practical.
+- Missing details could trigger excessive questions.
+
+Expected behavior:
+- Classify as medium.
+- Use Manager, Requirements Specialist, and QA / Acceptance Specialist.
+- Ask only material questions or proceed with marked assumptions.
+- Use light workspace if files are requested or useful; otherwise produce one integrated Markdown artifact.
+
+Failure this prevents:
+- Creating full phase folders and every role file before writing a useful PRD.
+
+## Scenario 3: Complex UI Demo Needs Formal Orchestration
+
+User request:
+
+> Design a UI demo for a new family weekly report experience. I need something execution-ready.
+
+Pressures:
+- The user wants a demo, not just analysis.
+- The task needs design, requirements, feasibility, and review.
+- Outputs can easily become scattered.
+
+Expected behavior:
+- Classify as complex.
+- Use full workspace.
+- Select Manager, Product Designer, Requirements Specialist, Tech Lead, and QA / Acceptance Specialist.
+- Create an orchestration plan before execution.
+- End with `outputs/final.md` and any demo artifacts under `outputs/artifacts/`.
+
+Failure this prevents:
+- Producing a loose brainstorm without final integration or artifact paths.
+
+## Scenario 4: Competitor Facts Need Evidence
+
+User request:
+
+> Compare the latest onboarding flows of three family calendar apps and turn it into recommendations.
+
+Pressures:
+- "Latest" facts may be unstable.
+- The agent may rely on memory.
+- Product recommendations need evidence.
+
+Expected behavior:
+- Classify as medium or complex depending on depth.
+- Use Manager and Market Analyst; add Product Designer if UX comparison is required.
+- Browse or use user-provided sources before making current claims.
+- Record used KB, assumptions, and evidence gaps.
+
+Failure this prevents:
+- Fabricating competitor details or treating stale knowledge as current evidence.
+
+## Scenario 5: User Explicitly Says Keep It Lightweight
+
+User request:
+
+> Review this feature idea quickly. Do not make a big framework.
+
+Pressures:
+- Product review normally invites multiple roles.
+- The user explicitly rejects ceremony.
+
+Expected behavior:
+- Downgrade one level from the default.
+- Use a concise manager-led review, optionally naming one extra lens.
+- Avoid workspace unless the user asks for files.
+
+Failure this prevents:
+- Ignoring the user's lightweight preference because the task sounds strategic.
+
+## Scenario 6: Existing Docs Provided But Permission Is Narrow
+
+User request:
+
+> Use the screenshots in this folder to review the settings flow, but do not summarize unrelated docs.
+
+Pressures:
+- A folder path may contain tempting extra context.
+- Review quality depends on screenshot evidence.
+
+Expected behavior:
+- Use only the allowed screenshots.
+- State visual inferences and uncertainty.
+- Record sources used and sources intentionally not used.
+- Do not summarize unrelated files.
+
+Failure this prevents:
+- Treating a local folder as blanket permission to inspect or summarize everything.
+
+## Scenario 7: Final Synthesis Must Resolve Conflicts
+
+User request:
+
+> Turn the research and design notes into a final recommendation.
+
+Pressures:
+- Role outputs may disagree.
+- Copy-pasting all notes feels complete.
+- The user needs a CEO-readable decision.
+
+Expected behavior:
+- Create a final integration phase.
+- Resolve conflicts explicitly.
+- Separate facts, assumptions, recommendations, risks, and follow-ups.
+- Provide final artifact path if files were promised.
+
+Failure this prevents:
+- Leaving scattered role notes without a decision.
+
+## Manual Verification Checklist
+
+Before deploying edits to this skill, confirm:
+
+- `SKILL.md` description starts with "Use when" and only describes triggers.
+- `SKILL.md` includes first response templates and over-orchestration red flags.
+- `references/orchestration-model.md` includes a decision table and downgrade rule.
+- `references/role-catalog.md` includes a role selection matrix.
+- `references/workspace-structure.md` includes none, light, and full workspace modes.
+- Durable task completion is checked by the final validation checklist.
+- These pressure scenarios still map to explicit instructions in the skill.