popilot 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoonjae Song
+
+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/adapters/claude-code/.claude/commands/start.md

@@ -19,14 +19,14 @@ ARGUMENTS: $ARGUMENTS
 
 ## Execution Steps
 
-### -1. Setup Check (First Run Detection) ⭐
+### -1. Setup + Ambiguity Gate Check ⭐
 
 **First**, check whether the `.context/project.yaml` file exists.
 
 ```
 project.yaml exists?
-├── Yes → Normal flow (proceed to step 0)
-└── No  → Start Setup Wizard
+├── No  → Start Setup Wizard
+└── Yes → Evaluate ambiguity gate before normal flow
 ```
 
 #### Setup Wizard Start
@@ -54,13 +54,10 @@ If `.context/project.yaml` does not exist, treat this as a first run and start t
    - Communication style, work style preferences
    - → Generate `user-context.yaml`
 
-4. **Phase 2: In-depth Project Interview** (🎯 Simon deployed)
-   - Core problem, target customers, market
-   - Solution, differentiators, expected outcomes
-   - Current stage, uncertainties, milestones
-   - What's validated / what needs validation
-   - Research unknown areas together via WebSearch
-   - → Generate `project.yaml`
+4. **Phase 2: Project Skeleton Setup**
+   - Fill minimal project defaults and metadata gate fields
+   - Keep deep interview for ambiguity-gate phase
+   - → Generate initial `project.yaml`
 
 5. **Phase 3: Sensitive Information Guidance** (🎩 Oscar)
    - Suggest creating `.secrets.yaml` template
@@ -76,6 +73,37 @@ Generated files:
 What would you like to start working on?
 ```
 
+#### Ambiguity Gate (mandatory before normal `/start`)
+
+If `.context/project.yaml` exists, read `_meta` and evaluate:
+
+```js
+meta = _meta ?? {};
+needsDeepInterview = meta.needs_deep_interview === true;
+ambiguityScoreRaw = meta.ambiguity_score ?? (needsDeepInterview ? 1 : 0);
+ambiguityScoreParsed = Number(ambiguityScoreRaw);
+ambiguityScore = Number.isFinite(ambiguityScoreParsed) ? ambiguityScoreParsed : 1;
+
+if (needsDeepInterview || ambiguityScore >= 0.6) {
+  // Gate is open: run deep interview first
+} else {
+  // Gate is closed: proceed to step 0
+}
+```
+
+If `_meta` is missing or malformed, treat it as **gate open** (safe default).
+If gate is open, **do not proceed to step 0/session selection yet**.
+Run the deep project interview first (🎯 Simon-led), then update `.context/project.yaml`:
+
+```yaml
+_meta:
+  needs_deep_interview: false
+  ambiguity_score: <updated numeric score>
+  last_interview: "<ISO8601>"
+```
+
+Only after this metadata update should `/start` continue with normal session flow.
+
 ---
 
 ### 0. Load Secret Variables (Required)

package/lib/setup-wizard.mjs

@@ -2,7 +2,7 @@
  * Interactive setup wizard — terminal interview → project.yaml + related files.
  *
  * Collects only essential config. AI deep interview is deferred to Claude Code
- * via `_meta.needs_deep_interview: true`.
+ * via metadata gate fields (`_meta.needs_deep_interview`, `_meta.ambiguity_score`).
  */
 
 import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
@@ -16,6 +16,7 @@ import { parse as parseYaml, stringify as stringifyYaml } from './yaml-lite.mjs'
  * @param {string} targetDir - Project root (scaffold already copied)
  * @param {object} [opts]
  * @param {import('node:readline/promises').Interface} [opts.rl] - Inject readline for testing
+ * @param {string|null} [opts.platform] - Optional adapter/platform name
  * @returns {Promise<void>}
  */
 export async function runSetupWizard(targetDir, opts = {}) {
@@ -232,14 +233,76 @@ async function collectObjectList(rl, question) {
   return items;
 }
 
+// ── Ambiguity score ─────────────────────────────────────
+
+/**
+ * Calculate ambiguity score from project.yaml content.
+ * Returns 0.0 (clear) to 1.0 (high ambiguity).
+ *
+ * Note: fresh setup defaults are usually high ambiguity because deep-interview
+ * fields are empty, but this may be below 1.0 if users fill optional basics
+ * (for example `project.tagline`) during setup.
+ *
+ * @param {object} yaml
+ * @returns {number}
+ */
+export function calculateAmbiguityScore(yaml) {
+  const root = (yaml && typeof yaml === 'object') ? yaml : {};
+
+  const checks = [
+    // Basic clarity
+    { weight: 0.1, filled: !!root.project?.tagline },
+
+    // Problem & market
+    { weight: 0.15, filled: !!root.problem?.core },
+    { weight: 0.1, filled: !!root.problem?.target },
+    { weight: 0.05, filled: root.problem?.alternatives?.length > 0 },
+    { weight: 0.05, filled: !!root.problem?.timing },
+
+    // Solution
+    { weight: 0.15, filled: !!root.solution?.approach },
+    { weight: 0.08, filled: !!root.solution?.differentiation },
+    { weight: 0.05, filled: root.solution?.outcome?.length > 0 },
+
+    // Current state
+    { weight: 0.1, filled: !!root.current_state?.stage },
+    { weight: 0.07, filled: !!root.current_state?.focus },
+    { weight: 0.05, filled: !!root.current_state?.next_milestone },
+
+    // Validation
+    { weight: 0.05, filled: root.validation?.confirmed?.length > 0 },
+  ];
+
+  let totalWeight = 0;
+  let filledWeight = 0;
+
+  for (const { weight, filled } of checks) {
+    totalWeight += weight;
+    if (filled) filledWeight += weight;
+  }
+
+  return Math.round((1 - filledWeight / totalWeight) * 100) / 100;
+}
+
 // ── project.yaml builder ────────────────────────────────
 
+export const ALL_INTEGRATION_PROVIDERS = [
+  'ga4',
+  'mixpanel',
+  'notion',
+  'linear',
+  'channel_io',
+  'intercom',
+  'prod_db',
+  'notebooklm',
+  'corti',
+];
+
 function buildProjectYaml({ projectName, tagline, projectType, domains, devScope, integrations, platform }) {
   // Build the full integrations block with all known providers
-  const allProviders = ['ga4', 'mixpanel', 'notion', 'linear', 'channel_io', 'intercom', 'prod_db', 'notebooklm', 'corti'];
   const integrationsBlock = {};
 
-  for (const id of allProviders) {
+  for (const id of ALL_INTEGRATION_PROVIDERS) {
     if (integrations[id]) {
       integrationsBlock[id] = integrations[id];
     } else {
@@ -247,7 +310,7 @@ function buildProjectYaml({ projectName, tagline, projectType, domains, devScope
     }
   }
 
-  return {
+  const yaml = {
     project: {
       name: projectName,
       tagline: tagline || '',
@@ -298,11 +361,16 @@ function buildProjectYaml({ projectName, tagline, projectType, domains, devScope
       created_at: new Date().toISOString(),
       created_by: 'popilot init',
       needs_deep_interview: true,
+      ambiguity_score: 0,
       last_interview: null,
       version: '1.0.0',
       ...(platform ? { platform } : {}),
     },
   };
+
+  yaml._meta.ambiguity_score = calculateAmbiguityScore(yaml);
+
+  return yaml;
 }
 
 // ── Helpers ─────────────────────────────────────────────

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "popilot",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Multi-agent PO/PM system scaffold for Claude Code",
   "type": "module",
   "bin": {
-    "popilot": "./bin/cli.mjs"
+    "popilot": "bin/cli.mjs"
   },
   "scripts": {
+    "lint": "node scripts/lint.mjs",
+    "typecheck": "node scripts/typecheck.mjs",
     "test": "node --test test/*.test.mjs"
   },
   "files": [
     "bin/",
     "lib/",
+    "scripts/",
     "scaffold/",
     "adapters/",
     "README.md"

package/scaffold/.context/project.yaml.example

@@ -63,12 +63,20 @@ operations:
     ga4:
       enabled: false
       property_id: ""          # {{integrations.ga4.property_id}}
+    mixpanel:
+      enabled: false
+      project_id: ""
     notion:
       enabled: false
       workspace: ""
       daily_page_id: ""
+    linear:
+      enabled: false
+      team_id: ""
     channel_io:
       enabled: false
+    intercom:
+      enabled: false
     prod_db:
       enabled: false
       mcp_name: ""             # {{integrations.prod_db.mcp_name}}
@@ -97,6 +105,8 @@ operations:
 # ============================================================
 _meta:
   created_at: ""
-  created_by: "Oscar (Setup Wizard)"
+  created_by: "popilot init"
+  needs_deep_interview: true
+  ambiguity_score: 1.0
   last_interview: null
   version: "1.0.0"