agentblueprint 0.7.15 → 0.7.18

package/dist/renderers.js

@@ -72,6 +72,24 @@ function numStr(val) {
 function isPlaceholder(val) {
     return ['—', '–', '-', 'N/A', 'n/a', 'TBD', 'null', 'undefined', 'none'].includes(val.trim());
 }
+/** Checks if the business profile has minimal data (fewer than 3 meaningful fields populated) */
+function isProfileSparse(bp) {
+    if (!bp)
+        return true;
+    const meaningfulFields = ['industry', 'size', 'revenue', 'description',
+        'technologyProfile', 'organizationalCapabilities', 'businessOperations', 'constraintsProfile'];
+    const populated = meaningfulFields.filter(f => {
+        const val = bp[f];
+        if (!val)
+            return false;
+        if (typeof val === 'string' && val.trim() === '')
+            return false;
+        if (typeof val === 'object' && Object.keys(val).length === 0)
+            return false;
+        return true;
+    });
+    return populated.length < 3;
+}
 /** Strips a trailing unit suffix to prevent double-units (e.g. "3.6 months" + " months") */
 function stripTrailingUnit(val, unit) {
     return val.replace(new RegExp(`\\s*${unit}\\s*$`, 'i'), '');
@@ -193,11 +211,11 @@ function buildSkillBody(input) {
     lines.push(`- **Pattern:** ${pattern}`);
     lines.push(`- **Agents:** ${team.length}`, '');
     if (input.baseSkill) {
-        lines.push('> A base implementation skill has been installed at `.claude/skills/agent-blueprint/`.', '> It contains deployment patterns and reference material for all platforms.', '');
+        lines.push('> A base implementation skill has been installed at `.claude/skills/agent-blueprint/` and `.agents/skills/agent-blueprint/`.', '> It contains deployment patterns and reference material for all platforms.', '');
     }
     if (input.vendorSkill) {
         const platformLabel = input.vendorSkill.platform.charAt(0).toUpperCase() + input.vendorSkill.platform.slice(1);
-        lines.push(`> A ${platformLabel} expert skill has been installed at \`.claude/skills/${input.vendorSkill.skillName}/\`.`, '> It will be auto-loaded for platform-specific tasks.', '');
+        lines.push(`> A ${platformLabel} expert skill has been installed at \`.claude/skills/${input.vendorSkill.skillName}/\` and \`.agents/skills/${input.vendorSkill.skillName}/\`.`, '> It will be auto-loaded for platform-specific tasks.', '');
     }
     else if (input.vendorGuide) {
         const guideFilename = `references/deployment-guide-${input.vendorGuide.platform}.md`;
@@ -1546,21 +1564,30 @@ function buildGettingStartedReturnVisit(input) {
         lines.push('');
     }
     if (input.baseSkill) {
-        lines.push('The `.claude/skills/agent-blueprint/` skill contains deployment patterns and');
+        lines.push('The `.claude/skills/agent-blueprint/` and `.agents/skills/agent-blueprint/` skills contain deployment patterns and');
         lines.push('reference material applicable to all platforms. Read it for general guidance.');
         lines.push('');
     }
     if (input.vendorSkill) {
-        lines.push(`The \`.claude/skills/${input.vendorSkill.skillName}/\` skill contains platform-specific`);
+        lines.push(`The \`.claude/skills/${input.vendorSkill.skillName}/\` and \`.agents/skills/${input.vendorSkill.skillName}/\` skills contain platform-specific`);
         lines.push('deployment guidance. Follow it for all platform-specific work.');
+        lines.push('For new apps or first deployments, re-check its deployment-path decision');
+        lines.push('gate before creating more records. Use direct record or API edits mainly');
+        lines.push('for existing deployments, live tuning, or blocked packaging paths. If you');
+        lines.push('choose a fallback, document the reason in blueprint-local `PROGRESS.md` before proceeding.');
         lines.push('');
     }
-    lines.push('For each agent:');
-    lines.push('1. Review the agent spec in `references/agent-specifications.md`');
-    lines.push('2. Build the agent with its tools and instructions');
+    lines.push('deployment-path decision checkpoint: before creating new app records, prefer the');
+    lines.push('platform\'s source-controlled or native packaging path when one is available.');
+    lines.push('Direct record or API edits are best for existing deployments, live tuning,');
+    lines.push('or blocked packaging paths. Document fallback reasons in blueprint-local `PROGRESS.md`.');
+    lines.push('');
+    lines.push('For the next pilot slice or agent:');
+    lines.push('1. Review the spec in `SKILL.md` and `references/agent-specifications.md`');
+    lines.push('2. Build the smallest executable slice that proves a useful path');
     lines.push('3. Test and iterate until behavior matches the spec');
-    lines.push('4. Update `implementation-state.yaml` with status and platform artifact');
-    lines.push('5. Move to the next agent');
+    lines.push('4. Update local `implementation-state.yaml` with status and platform artifact');
+    lines.push('5. Ask before syncing demo/test state back to Agent Blueprint');
     lines.push('');
     // Step 4
     lines.push('## Step 4: Validate and measure');
@@ -1577,7 +1604,9 @@ function buildGettingStartedReturnVisit(input) {
     // Step 5
     lines.push('## Step 5: Sync your progress');
     lines.push('');
-    lines.push('After implementing each agent or making significant changes, sync immediately:');
+    lines.push('After implementing each agent or making significant changes, update local');
+    lines.push('`implementation-state.yaml`. In demo/test mode, ask the user before syncing');
+    lines.push('state back to Agent Blueprint.');
     lines.push('');
     lines.push('**MCP tool** (preferred):');
     lines.push('');
@@ -1585,7 +1614,7 @@ function buildGettingStartedReturnVisit(input) {
     lines.push(`      blueprintId: "${input.blueprintId}"`);
     lines.push('      stateData: <contents of implementation-state.yaml as JSON>');
     lines.push('');
-    lines.push('**CLI**:');
+    lines.push('**CLI** (after user approval in demo/test mode):');
     lines.push('');
     lines.push(`    agentblueprint sync --blueprint ${input.blueprintId}`);
     lines.push('');
@@ -1598,6 +1627,7 @@ function buildGettingStartedReturnVisit(input) {
     lines.push('          actualValue: "measured value"');
     lines.push('');
     lines.push('See `AGENTS.md` for trigger points, deviation rules, and full sync guidance.');
+    lines.push('For demo/test implementations, ask before using MCP or CLI sync.');
     lines.push('');
     lines.push('**Claude Code users**: See `hooks/claude-code-sync.json` for a Stop hook that');
     lines.push('reminds you to sync when implementation-state.yaml has unsynced changes.');
@@ -1659,6 +1689,9 @@ function buildGettingStarted(input) {
     lines.push('  One fix, one alternative, then ask. Do not spiral.');
     lines.push('- **Verify before presenting.** Never give the user a URL, path, or command');
     lines.push('  you have not verified against the actual platform instance.');
+    lines.push('- **Ask before high-impact actions.** Get explicit approval before running');
+    lines.push('  background scripts, production writes, credential changes, cleanup/deletion,');
+    lines.push('  or syncing demo/test state back to Agent Blueprint.');
     lines.push('');
     // Staleness warnings
     const staleWarnings = buildStalenessWarnings(input);
@@ -1666,6 +1699,20 @@ function buildGettingStarted(input) {
         lines.push(staleWarnings);
         lines.push('');
     }
+    // Phase 0: Profile interview (only when profile is sparse and base skill is present)
+    if (isProfileSparse(input.businessProfileData) && input.baseSkill) {
+        lines.push('## Phase 0: Build your organization profile');
+        lines.push('');
+        lines.push('Organization context is incomplete. Before deploying agents, build a');
+        lines.push('comprehensive business profile using the interview protocol:');
+        lines.push('');
+        lines.push('1. Read `.claude/skills/agent-blueprint/references/INTERVIEW_PROTOCOL.md`');
+        lines.push('2. Follow the document-first approach: gather existing docs, extract, then interview for gaps');
+        lines.push('3. Output structured JSON for platform sync, or rewrite `references/organization-context.md` locally');
+        lines.push('');
+        lines.push('A richer profile produces better-tailored agent recommendations and more accurate financial projections.');
+        lines.push('');
+    }
     // Step 1
     lines.push('## Step 1: Understand the architecture');
     lines.push('');
@@ -1701,23 +1748,35 @@ function buildGettingStarted(input) {
     lines.push('  error messages) after each step.');
     lines.push('');
     if (input.baseSkill) {
-        lines.push('A base implementation skill has been installed at `.claude/skills/agent-blueprint/`.');
+        lines.push('A base implementation skill has been installed at `.claude/skills/agent-blueprint/` and `.agents/skills/agent-blueprint/`.');
         lines.push('It contains deployment patterns and reference material applicable to all platforms.');
         lines.push('Read it before starting any implementation work.');
         lines.push('');
     }
     if (input.vendorSkill) {
         const platformLabel = input.vendorSkill.platform.charAt(0).toUpperCase() + input.vendorSkill.platform.slice(1);
-        lines.push(`A ${platformLabel} expert skill has been installed at \`.claude/skills/${input.vendorSkill.skillName}/\`.`);
+        lines.push(`A ${platformLabel} expert skill has been installed at \`.claude/skills/${input.vendorSkill.skillName}/\` and \`.agents/skills/${input.vendorSkill.skillName}/\`.`);
         lines.push('It contains the connection verification steps, deployment sequence, platform');
         lines.push('patterns, and debugging guidance. Follow it for all platform-specific work.');
         lines.push('The deployment sequence adapts to the access level the user provides.');
+        lines.push('');
+        lines.push('Before creating a new app or first deployment, follow the expert skill\'s');
+        lines.push('deployment-path decision gate. Prefer the platform\'s source-controlled or');
+        lines.push('native packaging path when the expert skill recommends one. Use direct record');
+        lines.push('or API edits mainly for existing deployments, live tuning, or blocked packaging');
+        lines.push('paths. If you choose a fallback, document the reason in blueprint-local `PROGRESS.md`.');
     }
     else if (!input.baseSkill) {
         lines.push('If `references/deployment-guide-*.md` files are present, read those for');
         lines.push('platform-specific tooling, deployment sequence, and gotchas.');
     }
     lines.push('');
+    lines.push('deployment-path decision checkpoint: before creating a new app or first deployment,');
+    lines.push('choose the platform\'s source-controlled or native packaging path when one is');
+    lines.push('available. Use direct record or API edits mainly for existing deployments,');
+    lines.push('live tuning, or blocked packaging paths. If you choose a fallback, document');
+    lines.push('the reason in blueprint-local `PROGRESS.md`.');
+    lines.push('');
     lines.push('**B. User wants to build from scratch** (custom code, open-source frameworks):');
     lines.push('Help them choose a framework based on the blueprint architecture. Search the web');
     lines.push('for current agentic AI frameworks and their capabilities -- this space moves fast');
@@ -1735,8 +1794,9 @@ function buildGettingStarted(input) {
     // Step 3
     lines.push('## Step 3: Build and validate the pilot');
     lines.push('');
-    lines.push('Check the Phase 1 section in `SKILL.md` for pilot scope.');
-    lines.push('Build the lead agent first. **Do not expand to remaining agents until the');
+    lines.push('Check the Phase 1/Pilot sections in `SKILL.md` and');
+    lines.push('`references/agent-specifications.md` for pilot scope.');
+    lines.push('Build the smallest executable pilot slice first. **Do not expand to remaining agents until the');
     lines.push('pilot is fully working with real data.** This is a gate, not a suggestion.');
     lines.push('');
     if (input.vendorSkill) {
@@ -1753,7 +1813,9 @@ function buildGettingStarted(input) {
     lines.push('**Phase A: Scaffold and validate orchestration.**');
     lines.push('1. Create an application container for the pilot (project, workspace, or whatever');
     lines.push('   your platform uses to group related agents). State your intent to the user.');
-    lines.push('2. Build the first worker agent with its tools and instructions.');
+    lines.push('2. Build the smallest executable pilot slice: the minimum native workflow or');
+    lines.push('   orchestrator plus the worker agent(s), tools, and instructions needed to');
+    lines.push('   prove the first useful path.');
     lines.push('3. Use simulation scripts to validate the LLM orchestration (tool chaining,');
     lines.push('   parameter passing, sequencing). This proves the agent can chain tools correctly.');
     lines.push('4. **Test before proceeding.** Invoke the agent programmatically, read the execution');
@@ -1808,7 +1870,7 @@ function buildGettingStarted(input) {
     // Step 5
     lines.push('## Step 5: Track progress and close the loop');
     lines.push('');
-    lines.push('As you implement each agent, update `implementation-state.yaml`:');
+    lines.push('As you implement each agent, update local `implementation-state.yaml`:');
     lines.push('');
     lines.push('1. Set the agent\'s `status` to `in_progress` when you start, `implemented` when done.');
     lines.push('2. Record the `platform_artifact` (sys_id, function name, service URL, etc.).');
@@ -1817,9 +1879,10 @@ function buildGettingStarted(input) {
     lines.push('5. Update `overall_status` as you progress.');
     lines.push('6. Fill in the `platform` section with the actual platform, version, and environment.');
     lines.push('');
-    lines.push('### Sync trigger points');
+    lines.push('### Local update trigger points');
     lines.push('');
-    lines.push('Sync after each of these events (do not wait until the end):');
+    lines.push('Update local `implementation-state.yaml` after each of these events');
+    lines.push('(do not wait until the end):');
     lines.push('- After implementing an agent');
     lines.push('- After connecting an integration');
     lines.push('- After modifying an agent\'s behavior');
@@ -1827,13 +1890,16 @@ function buildGettingStarted(input) {
     lines.push('');
     lines.push('### How to sync');
     lines.push('');
+    lines.push('In demo/test mode, ask the user before syncing local state back to Agent');
+    lines.push('Blueprint. Sync only after approval.');
+    lines.push('');
     lines.push('**MCP tool** (preferred when Agent Blueprint MCP server is connected):');
     lines.push('');
     lines.push('    Use the sync_implementation_state tool with:');
     lines.push(`      blueprintId: "${input.blueprintId}"`);
     lines.push('      stateData: <contents of implementation-state.yaml as JSON>');
     lines.push('');
-    lines.push('**CLI**:');
+    lines.push('**CLI** (after approval in demo/test mode):');
     lines.push('');
     lines.push(`    agentblueprint sync --blueprint ${input.blueprintId}`);
     lines.push('');
@@ -2642,6 +2708,7 @@ export function renderSkillDirectory(input) {
     if (input.baseSkill) {
         for (const file of input.baseSkill.files) {
             files.set(`.claude/skills/agent-blueprint/${file.path}`, file.content);
+            files.set(`.agents/skills/agent-blueprint/${file.path}`, file.content);
         }
     }
     // Vendor expert skill (multi-file when available, single SKILL.md fallback)
@@ -2649,10 +2716,12 @@ export function renderSkillDirectory(input) {
         if (input.vendorSkill.files && input.vendorSkill.files.length > 0) {
             for (const file of input.vendorSkill.files) {
                 files.set(`.claude/skills/${input.vendorSkill.skillName}/${file.path}`, file.content);
+                files.set(`.agents/skills/${input.vendorSkill.skillName}/${file.path}`, file.content);
             }
         }
         else {
             files.set(`.claude/skills/${input.vendorSkill.skillName}/SKILL.md`, input.vendorSkill.content);
+            files.set(`.agents/skills/${input.vendorSkill.skillName}/SKILL.md`, input.vendorSkill.content);
         }
     }
     // Scripts