@planu/cli 1.1.2 → 1.3.0

package/dist/engine/onboarding-engine.js

@@ -0,0 +1,575 @@
+// engine/onboarding-engine.ts — SPEC-360: Interactive Onboarding & Guided Tours
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+// ---------------------------------------------------------------------------
+// Recommendations
+// ---------------------------------------------------------------------------
+export function buildRecommendations(role, projectType, teamSize) {
+    const recs = [];
+    // Role-based
+    if (role === 'solo-dev') {
+        recs.push({
+            category: 'Workflow',
+            text: 'As a solo developer, use `quick_start` with the `solo-dev` template to get started fast.',
+            toolSuggestion: 'quick_start',
+        });
+    }
+    else if (role === 'team-lead') {
+        recs.push({
+            category: 'Collaboration',
+            text: 'Set up team roles with `configure_roles` and use `plan_team_distribution` to assign specs.',
+            toolSuggestion: 'configure_roles',
+        });
+        recs.push({
+            category: 'Visibility',
+            text: 'Use `workspace_overview` to monitor all team projects from a single view.',
+            toolSuggestion: 'workspace_overview',
+        });
+    }
+    else if (role === 'pm') {
+        recs.push({
+            category: 'Planning',
+            text: 'Use `create_spec` to capture requirements and `check_readiness` before starting implementation.',
+            toolSuggestion: 'create_spec',
+        });
+        recs.push({
+            category: 'Reporting',
+            text: 'Use `workspace_report` to generate progress summaries for stakeholders.',
+            toolSuggestion: 'workspace_report',
+        });
+    }
+    else {
+        // architect
+        recs.push({
+            category: 'Architecture',
+            text: 'Use `generate_diagram` to document architecture and `analyze_spec_dependencies` for dependency graphs.',
+            toolSuggestion: 'generate_diagram',
+        });
+    }
+    // Project type based
+    if (projectType === 'saas') {
+        recs.push({
+            category: 'SaaS Specifics',
+            text: 'Explore the Spec Cookbook for SaaS patterns: billing, onboarding, team management.',
+            toolSuggestion: 'cookbook_list',
+        });
+    }
+    else if (projectType === 'api') {
+        recs.push({
+            category: 'API Quality',
+            text: 'Use `validate_api_contract` to keep your OpenAPI spec aligned with implementation.',
+            toolSuggestion: 'validate_api_contract',
+        });
+    }
+    else if (projectType === 'mobile') {
+        recs.push({
+            category: 'Mobile CI',
+            text: 'Use `generate_automation_guide` with the mobile template to set up iOS/Android CI pipelines.',
+            toolSuggestion: 'generate_automation_guide',
+        });
+    }
+    // Team size based
+    if (teamSize === '1') {
+        recs.push({
+            category: 'Efficiency',
+            text: 'Enable compact mode with `set_work_mode` to minimize token usage while working solo.',
+            toolSuggestion: 'set_work_mode',
+        });
+    }
+    else if (teamSize === '6-20' || teamSize === '20+') {
+        recs.push({
+            category: 'Scale',
+            text: 'Configure approval policies with `configure_approval_policy` to enforce review workflows.',
+            toolSuggestion: 'configure_approval_policy',
+        });
+        recs.push({
+            category: 'Integrations',
+            text: 'Connect your issue tracker (Jira/Linear) to keep specs and tickets in sync.',
+            toolSuggestion: 'configure_jira',
+        });
+    }
+    return recs;
+}
+export function formatRecommendationsMarkdown(config, recommendations) {
+    const lines = [
+        `# Welcome to Planu!`,
+        ``,
+        `**Role:** ${config.role} | **Project type:** ${config.projectType} | **Team size:** ${config.teamSize}`,
+        ``,
+        `## Personalized Recommendations`,
+        ``,
+    ];
+    const byCategory = new Map();
+    for (const rec of recommendations) {
+        const existing = byCategory.get(rec.category) ?? [];
+        existing.push(rec);
+        byCategory.set(rec.category, existing);
+    }
+    for (const [category, recs] of byCategory) {
+        lines.push(`### ${category}`);
+        for (const rec of recs) {
+            lines.push(`- ${rec.text}`);
+        }
+        lines.push('');
+    }
+    lines.push(`## Next Steps`, ``);
+    lines.push(`1. Run \`onboarding_checklist\` to see what's already set up`);
+    lines.push(`2. Run \`guided_tour\` with area \`spec-lifecycle\` to learn the basics`);
+    lines.push(`3. Run \`quick_start\` to scaffold your first spec`);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Guided Tours
+// ---------------------------------------------------------------------------
+const TOURS = {
+    'spec-lifecycle': {
+        area: 'spec-lifecycle',
+        title: 'Spec Lifecycle: From Idea to Done',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Create a Spec',
+                description: 'Every feature starts with a spec. Use `create_spec` to define the feature title, description, and acceptance criteria.',
+                toolHint: 'create_spec',
+                example: 'create_spec with title="User login" and projectPath="/path/to/project"',
+            },
+            {
+                stepNumber: 2,
+                title: 'Challenge & Refine',
+                description: 'Use `challenge_spec` to stress-test your spec and find gaps before implementation starts.',
+                toolHint: 'challenge_spec',
+                example: 'challenge_spec with specId="SPEC-001" and projectPath="..."',
+            },
+            {
+                stepNumber: 3,
+                title: 'Check Readiness',
+                description: '`check_readiness` verifies the spec has enough detail for implementation. Fix any issues it flags.',
+                toolHint: 'check_readiness',
+            },
+            {
+                stepNumber: 4,
+                title: 'Approve & Implement',
+                description: 'Move the spec to `approved` status. Implement the feature, then move to `done`.',
+                toolHint: 'update_status',
+            },
+            {
+                stepNumber: 5,
+                title: 'Validate',
+                description: 'Run `validate` to confirm the implementation matches the spec criteria.',
+                toolHint: 'validate',
+            },
+        ],
+    },
+    'team-collaboration': {
+        area: 'team-collaboration',
+        title: 'Team Collaboration Workflows',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Configure Roles',
+                description: 'Set up roles (owner, reviewer, developer) with `configure_roles`.',
+                toolHint: 'configure_roles',
+            },
+            {
+                stepNumber: 2,
+                title: 'Assign Specs',
+                description: 'Use `assign_role` to assign specs to team members.',
+                toolHint: 'assign_role',
+            },
+            {
+                stepNumber: 3,
+                title: 'Comments & Reviews',
+                description: 'Use `add_comment` and `request_changes` to collaborate on spec details.',
+                toolHint: 'add_comment',
+            },
+            {
+                stepNumber: 4,
+                title: 'Approval Policy',
+                description: 'Configure who can approve specs with `configure_approval_policy`.',
+                toolHint: 'configure_approval_policy',
+            },
+        ],
+    },
+    integrations: {
+        area: 'integrations',
+        title: 'Connecting Your Tools',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Issue Trackers',
+                description: 'Sync specs with Jira, Linear, or Asana using the respective configure tools.',
+                toolHint: 'configure_jira',
+            },
+            {
+                stepNumber: 2,
+                title: 'CI/CD',
+                description: 'Generate CI workflows with `generate_planu_ci` for GitHub Actions.',
+                toolHint: 'generate_planu_ci',
+            },
+            {
+                stepNumber: 3,
+                title: 'Notifications',
+                description: 'Configure Slack notifications for spec status changes with `configure_slack`.',
+                toolHint: 'configure_slack',
+            },
+            {
+                stepNumber: 4,
+                title: 'Webhooks',
+                description: 'Set up outbound webhooks to trigger custom workflows on spec events.',
+                toolHint: 'configure_webhook',
+            },
+        ],
+    },
+    'ai-tools': {
+        area: 'ai-tools',
+        title: 'AI-Powered Features',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Suggest Criteria',
+                description: 'Use `suggest_criteria` to auto-generate acceptance criteria from a description.',
+                toolHint: 'suggest_criteria',
+            },
+            {
+                stepNumber: 2,
+                title: 'Clarify Requirements',
+                description: '`clarify_requirements` runs an interview-style session to uncover hidden requirements.',
+                toolHint: 'clarify_requirements',
+            },
+            {
+                stepNumber: 3,
+                title: 'Red Team',
+                description: 'Use `red_team` to adversarially challenge your spec for edge cases.',
+                toolHint: 'red_team',
+            },
+            {
+                stepNumber: 4,
+                title: 'Generate Tests',
+                description: 'Generate test scaffolds from spec criteria with `tdd_scaffold`.',
+                toolHint: 'tdd_scaffold',
+            },
+        ],
+    },
+    security: {
+        area: 'security',
+        title: 'Security & Compliance',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Security Scan',
+                description: 'Run `security_scan` to check specs for security anti-patterns.',
+                toolHint: 'security_scan',
+            },
+            {
+                stepNumber: 2,
+                title: 'Compliance',
+                description: 'Configure compliance checks (GDPR, SOC2) with `configure_compliance`.',
+                toolHint: 'configure_compliance',
+            },
+            {
+                stepNumber: 3,
+                title: 'Audit Trail',
+                description: 'View spec change history with `audit_trail` for compliance reporting.',
+                toolHint: 'audit_trail',
+            },
+        ],
+    },
+    reporting: {
+        area: 'reporting',
+        title: 'Reporting & Metrics',
+        steps: [
+            {
+                stepNumber: 1,
+                title: 'Velocity Report',
+                description: 'See team velocity trends with `velocity_report`.',
+                toolHint: 'velocity_report',
+            },
+            {
+                stepNumber: 2,
+                title: 'Usage Stats',
+                description: 'View tool usage and spec activity with `usage_stats`.',
+                toolHint: 'usage_stats',
+            },
+            {
+                stepNumber: 3,
+                title: 'Workspace Report',
+                description: 'Generate a workspace-level HTML report with `workspace_report`.',
+                toolHint: 'workspace_report',
+            },
+            {
+                stepNumber: 4,
+                title: 'Export',
+                description: 'Export specs as CSV, Markdown, or PDF for external stakeholders.',
+                toolHint: 'export_specs_csv',
+            },
+        ],
+    },
+};
+export function getGuidedTour(area) {
+    return TOURS[area];
+}
+export function formatTourMarkdown(tour) {
+    const lines = [
+        `# Guided Tour: ${tour.title}`,
+        ``,
+        `This tour covers ${String(tour.steps.length)} steps.`,
+        ``,
+    ];
+    for (const step of tour.steps) {
+        lines.push(`## Step ${String(step.stepNumber)}: ${step.title}`, ``);
+        lines.push(step.description, ``);
+        if (step.example !== undefined) {
+            lines.push(`**Example:** \`${step.example}\``, ``);
+        }
+        if (step.toolHint !== undefined) {
+            lines.push(`**Tool:** \`${step.toolHint}\``, ``);
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Checklist
+// ---------------------------------------------------------------------------
+export async function buildOnboardingChecklist(projectPath) {
+    const items = [];
+    // Check planu.json
+    const planuJson = await fileExists(path.join(projectPath, 'planu.json'));
+    items.push({
+        id: 'planu-init',
+        label: 'Project initialized (planu.json exists)',
+        completed: planuJson,
+        hint: 'Run `init_project` to initialize your project',
+    });
+    // Check CLAUDE.md or constitution
+    const constitutionExists = (await fileExists(path.join(projectPath, 'CLAUDE.md'))) ||
+        (await fileExists(path.join(projectPath, '.claude', 'CLAUDE.md')));
+    items.push({
+        id: 'constitution',
+        label: 'Project constitution (CLAUDE.md) exists',
+        completed: constitutionExists,
+        hint: 'Run `init_constitution` to create your project constitution',
+    });
+    // Check planu/ directory has specs
+    const planuDir = path.join(projectPath, 'planu', 'specs');
+    const specsExist = await dirHasContents(planuDir);
+    items.push({
+        id: 'first-spec',
+        label: 'At least one spec created',
+        completed: specsExist,
+        hint: 'Run `create_spec` to create your first spec',
+    });
+    // Check .claude/rules/ exists
+    const rulesDir = await dirHasContents(path.join(projectPath, '.claude', 'rules'));
+    items.push({
+        id: 'rules',
+        label: 'Project rules configured (.claude/rules/ exists)',
+        completed: rulesDir,
+        hint: 'Run `reconcile_rules` to set up project rules',
+    });
+    // Check .claude/skills/ exists
+    const skillsDir = await dirHasContents(path.join(projectPath, '.claude', 'skills'));
+    items.push({
+        id: 'skills',
+        label: 'Project skills configured (.claude/skills/ exists)',
+        completed: skillsDir,
+        hint: 'Run `reconcile_skills` to set up project skills',
+    });
+    const completedCount = items.filter((i) => i.completed).length;
+    const totalCount = items.length;
+    return {
+        projectPath,
+        items,
+        completedCount,
+        totalCount,
+        percentComplete: Math.round((completedCount / totalCount) * 100),
+    };
+}
+export function formatChecklistMarkdown(checklist) {
+    const lines = [
+        `# Onboarding Checklist`,
+        ``,
+        `**Progress:** ${String(checklist.completedCount)}/${String(checklist.totalCount)} steps complete (${String(checklist.percentComplete)}%)`,
+        ``,
+    ];
+    for (const item of checklist.items) {
+        const icon = item.completed ? '✅' : '⬜';
+        lines.push(`${icon} **${item.label}**`);
+        if (!item.completed && item.hint !== undefined) {
+            lines.push(`   > ${item.hint}`);
+        }
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Quick Start Templates
+// ---------------------------------------------------------------------------
+const QUICK_START_CONTENT = {
+    'solo-dev': `# Solo Developer Quick Start
+
+## 1. Initialize your project
+\`\`\`
+init_project projectPath="/path/to/your/project"
+\`\`\`
+
+## 2. Create your first spec
+\`\`\`
+create_spec title="My First Feature" projectPath="/path/to/your/project"
+\`\`\`
+
+## 3. Check readiness and implement
+\`\`\`
+check_readiness specId="SPEC-001" projectPath="..."
+\`\`\`
+
+## 4. Validate when done
+\`\`\`
+validate specId="SPEC-001" projectPath="..."
+update_status specId="SPEC-001" newStatus="done" projectPath="..."
+\`\`\`
+`,
+    'team-project': `# Team Project Quick Start
+
+## 1. Initialize and configure roles
+\`\`\`
+init_project projectPath="/path/to/your/project"
+configure_roles projectPath="..."
+\`\`\`
+
+## 2. Set up approval policy
+\`\`\`
+configure_approval_policy projectPath="..." requiredApprovals=1
+\`\`\`
+
+## 3. Create specs and assign reviewers
+\`\`\`
+create_spec title="Feature Name" projectPath="..."
+assign_role specId="SPEC-001" role="reviewer" userId="..."
+\`\`\`
+
+## 4. Connect integrations
+\`\`\`
+configure_slack webhookUrl="https://..."
+configure_jira host="..." apiToken="..."
+\`\`\`
+`,
+    'api-first': `# API-First Development Quick Start
+
+## 1. Initialize and set up API spec validation
+\`\`\`
+init_project projectPath="/path/to/your/project"
+\`\`\`
+
+## 2. Create API specs from cookbook
+\`\`\`
+cookbook_get id="api-rate-limiting"
+cookbook_apply id="api-auth" projectName="My API"
+\`\`\`
+
+## 3. Validate API contract
+\`\`\`
+validate_api_contract projectPath="..." specFile="openapi.yaml"
+\`\`\`
+
+## 4. Generate tests
+\`\`\`
+tdd_scaffold specId="SPEC-001" projectPath="..."
+\`\`\`
+`,
+    'mobile-app': `# Mobile App Quick Start
+
+## 1. Initialize project
+\`\`\`
+init_project projectPath="/path/to/your/project"
+\`\`\`
+
+## 2. Browse mobile cookbook patterns
+\`\`\`
+cookbook_list domain="mobile"
+\`\`\`
+
+## 3. Generate CI/CD pipeline
+\`\`\`
+generate_automation_guide projectPath="..." platform="mobile"
+\`\`\`
+
+## 4. Set up push notification spec
+\`\`\`
+cookbook_apply id="mobile-push-notifications" projectName="MyApp"
+\`\`\`
+`,
+    'open-source': `# Open Source Project Quick Start
+
+## 1. Initialize project
+\`\`\`
+init_project projectPath="/path/to/your/project"
+\`\`\`
+
+## 2. Create contribution guidelines via spec
+\`\`\`
+create_spec title="Contribution Workflow" projectPath="..."
+\`\`\`
+
+## 3. Set up CI validation
+\`\`\`
+generate_planu_ci projectPath="..." provider="github-actions"
+\`\`\`
+
+## 4. Generate documentation site
+\`\`\`
+generate_docs_site projectPath="..."
+\`\`\`
+`,
+};
+export function getQuickStart(template) {
+    return QUICK_START_CONTENT[template];
+}
+// ---------------------------------------------------------------------------
+// Progress Summary
+// ---------------------------------------------------------------------------
+export async function buildProgressSummary(projectPath, config) {
+    const checklist = await buildOnboardingChecklist(projectPath);
+    const nextSteps = [];
+    for (const item of checklist.items) {
+        if (!item.completed && item.hint !== undefined) {
+            nextSteps.push(item.hint);
+        }
+        if (nextSteps.length >= 3) {
+            break;
+        }
+    }
+    if (nextSteps.length === 0) {
+        nextSteps.push('All setup steps complete! Explore `guided_tour` for advanced topics.');
+    }
+    return {
+        projectPath,
+        config,
+        checklist,
+        percentComplete: checklist.percentComplete,
+        nextSteps,
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function dirHasContents(dirPath) {
+    try {
+        const entries = await fs.readdir(dirPath);
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export function formatTourStep(step) {
+    return `**Step ${String(step.stepNumber)}:** ${step.title} — ${step.description}`;
+}
+//# sourceMappingURL=onboarding-engine.js.map

package/dist/engine/onboarding-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-engine.js","sourceRoot":"","sources":["../../src/engine/onboarding-engine.ts"],"names":[],"mappings":"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"}

package/dist/engine/parallel-safety-engine.d.ts

@@ -0,0 +1,8 @@
+import type { ParallelSafetyResult } from '../types/index.js';
+export declare function getRepoRoot(cwd: string): string | null;
+export declare function detectCurrentWorktreeId(cwd: string): string | null;
+export declare function getActiveWorktreeIds(projectPath: string): string[];
+export declare function generateSafeAgentNames(numAgents: number, activeIds: string[], currentId: string | null): string[];
+export declare function checkParallelSafety(cwd: string, projectPath: string, numAgents?: number): ParallelSafetyResult;
+export declare const PARALLEL_WORKTREE_SAFETY_RULE = "# parallel-worktree-safety\n\n## Problem\nWhen Claude Code runs inside a worktree (.claude/worktrees/agent-XXXX) and launches subagents\nwith `isolation: \"worktree\"`, a silent collision can occur if the new agent receives an ID whose\nprefix matches the parent session's worktree. The result: the agent writes into the parent\nsession's worktree instead of a new one, and the work is lost when the worktree is cleaned up.\n\n## Solution\nBefore launching parallel agents, call `check_parallel_safety` to:\n1. Detect if you're inside a worktree\n2. Get a list of safe agent names that won't collide\n3. Use those names as the `name:` parameter in Agent tool calls\n\n## Rules\n- NEVER use `isolation: \"worktree\"` when already inside a worktree\n- ALWAYS pass explicit `name:` to Agent tool calls when running parallel sessions\n- USE `check_parallel_safety` at session start if launching 3+ parallel agents\n- IF in a worktree, use manual branch strategy instead of isolation:worktree\n";
+//# sourceMappingURL=parallel-safety-engine.d.ts.map

package/dist/engine/parallel-safety-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel-safety-engine.d.ts","sourceRoot":"","sources":["../../src/engine/parallel-safety-engine.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAA2B,MAAM,mBAAmB,CAAC;AAEvF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMtD;AAED,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYlE;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAYlE;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EAAE,EACnB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,MAAM,EAAE,CAiBV;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,SAAI,GACZ,oBAAoB,CAoCtB;AAED,eAAO,MAAM,6BAA6B,k+BAmBzC,CAAC"}