agentblueprint 0.7.15 → 0.7.19

package/dist/renderers.js

@@ -60,6 +60,9 @@ function arr(val) {
 function rec(val) {
     return val && typeof val === 'object' && !Array.isArray(val) ? val : {};
 }
+function jsonTemplate(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
 /** Returns string representation for numbers, passes through strings, '' otherwise */
 function numStr(val) {
     if (typeof val === 'number')
@@ -72,6 +75,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'), '');
@@ -1553,14 +1574,38 @@ function buildGettingStartedReturnVisit(input) {
     if (input.vendorSkill) {
         lines.push(`The \`.claude/skills/${input.vendorSkill.skillName}/\` skill contains 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('## Maintain the business profile and artifacts');
+    lines.push('');
+    lines.push('Markdown files are readable snapshots. MCP/CLI writes are the source of truth.');
+    lines.push('When implementation reveals new profile facts or artifact corrections, update');
+    lines.push('Agent Blueprint with a focused patch:');
+    lines.push('');
+    lines.push('1. Read the current markdown context in `references/` and `CURRENT-STATE.md`');
+    lines.push('2. Fill in the matching template in `editable/*.json`');
+    lines.push('3. Call the matching MCP write tool, such as `update_business_profile`,');
+    lines.push('   `update_use_case`, `update_blueprint`, `update_business_case`, or');
+    lines.push('   `update_implementation_plan`');
+    lines.push('4. Re-download this export after staleness changes or recalculations');
+    lines.push('');
+    lines.push('See `references/artifact-editing.md` for the full workflow and tool mapping.');
+    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 +1622,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 +1632,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 +1645,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 +1707,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 +1717,37 @@ 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('');
+    }
+    lines.push('## Maintain the business profile');
+    lines.push('');
+    lines.push('If you learn new facts while implementing, update Agent Blueprint instead of');
+    lines.push('only editing local markdown snapshots.');
+    lines.push('');
+    lines.push('1. Read `references/organization-context.md` and the current implementation context');
+    lines.push('2. Fill in `editable/business-profile.update.json` with only verified changes');
+    lines.push('3. Call the `update_business_profile` MCP tool with the `fields` object');
+    lines.push('4. Re-download this export when staleness changes affect downstream artifacts');
+    lines.push('');
+    lines.push('## Ad-hoc artifact edits');
+    lines.push('');
+    lines.push('Markdown files are readable snapshots. MCP/CLI writes are the source of truth.');
+    lines.push('For piecemeal edits to use cases, blueprints, business cases, or implementation');
+    lines.push('plans, follow `references/artifact-editing.md` and use the templates in');
+    lines.push('`editable/*.json`.');
+    lines.push('');
     // Step 1
     lines.push('## Step 1: Understand the architecture');
     lines.push('');
@@ -1712,12 +1794,24 @@ function buildGettingStarted(input) {
         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 +1829,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 +1848,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 +1905,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 +1914,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 +1925,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('');
@@ -2043,6 +2144,281 @@ function buildPlatformConnectivity() {
     return lines.join('\n');
 }
 // =============================================================================
+// ARTIFACT EDITING REFERENCE + JSON TEMPLATES
+// =============================================================================
+function buildArtifactEditingReference(input) {
+    const lines = [
+        '# Artifact Editing Reference',
+        '',
+        '> Markdown files in this export are readable snapshots. Agent Blueprint MCP/CLI',
+        '> writes are the source of truth for saved changes.',
+        '',
+        `Blueprint ID: \`${input.blueprintId}\``,
+        '',
+        '## Workflow',
+        '',
+        '1. Read the current markdown context in `references/` and `SKILL.md`.',
+        '2. Prepare a focused JSON patch using the matching file in `editable/`.',
+        '3. Call the matching MCP write tool with only the fields or sections that changed.',
+        '4. If the tool reports downstream staleness, refresh the affected artifact before relying on it.',
+        '5. Re-download this blueprint export after important changes so local markdown snapshots match Agent Blueprint.',
+        '',
+        'Do not edit markdown snapshots as the canonical record. Local markdown edits are notes only unless they are written back through MCP or CLI.',
+        '',
+        '## Tool Mapping',
+        '',
+        '| Change area | Template | Write tool |',
+        '|-------------|----------|------------|',
+        '| Profile facts, systems, capabilities, operations, constraints | `editable/business-profile.update.json` | `update_business_profile` |',
+        '| Use case, pain points, outcomes, success metrics | `editable/use-case.update.json` | `update_use_case` |',
+        '| Agent team, architecture, phases, success criteria | `editable/blueprint.update.json` | `update_blueprint` |',
+        '| ROI narrative, benefits, risks, recommendation | `editable/business-case.update.json` | `update_business_case`, then `recalculate_financials` when numbers need refresh |',
+        '| Implementation sequencing, epics, resources, agent specs | `editable/implementation-plan.update.json` | `update_implementation_plan` |',
+        '',
+        '## Patch Rules',
+        '',
+        '- Keep patches small. Include only the top-level fields or sections you intend to change.',
+        '- Delete placeholder keys before submitting if you are not changing them.',
+        '- Preserve IDs, agent names, phase names, and metric names unless the user explicitly asks to rename them.',
+        '- For financial narrative edits, call `update_business_case` first. Call `recalculate_financials` only when numeric assumptions or ROI inputs changed.',
+        '- Unknown keys may be ignored or preserved depending on the endpoint. Prefer the keys shown in the templates.',
+        '',
+        '## MCP Examples',
+        '',
+        'Business profile:',
+        '',
+        '```json',
+        '{',
+        '  "fields": {',
+        '    "companyName": "Replace with verified company name",',
+        '    "technology": { "systems": [] }',
+        '  }',
+        '}',
+        '```',
+        '',
+        'Blueprint section:',
+        '',
+        '```json',
+        '{',
+        `  "blueprintId": "${input.blueprintId}",`,
+        '  "sections": {',
+        '    "executiveSummary": "Replace with the revised summary"',
+        '  }',
+        '}',
+        '```',
+        '',
+        'After a successful write, inspect the response for `downstreamStale` or staleness warnings. Refresh or recalculate those artifacts before treating the export as current.',
+    ];
+    return lines.join('\n');
+}
+function buildBusinessProfileUpdateTemplate() {
+    return jsonTemplate({
+        _instructions: 'Replace placeholders, delete unused keys, then call update_business_profile with the fields object. Use only verified facts.',
+        fields: {
+            companyName: '<replace with verified company name>',
+            industry: '<replace with industry>',
+            size: '<replace with employee or company size>',
+            revenue: '<replace with revenue range if known>',
+            currency: 'USD',
+            description: '<replace with concise business description>',
+            companyWebsite: '<replace with company website>',
+            technology: {
+                systems: [
+                    {
+                        name: '<replace with system name>',
+                        category: '<replace with system category>',
+                        criticality: '<replace with criticality>',
+                    },
+                ],
+            },
+            capabilities: {
+                technicalTeam: {
+                    developmentCapacity: '<replace with capacity if known>',
+                    aiMlExperience: '<replace with AI/ML experience level>',
+                },
+            },
+            operations: {
+                keyProcesses: [
+                    {
+                        name: '<replace with process name>',
+                        volume: '<replace with process volume if known>',
+                    },
+                ],
+                painPoints: ['<replace with operational pain point>'],
+            },
+            constraints: {
+                budget: {
+                    totalAiBudget: '<replace with budget if known>',
+                },
+                timeline: {
+                    preferredTimeline: '<replace with timeline if known>',
+                },
+            },
+            strategicInitiatives: [
+                {
+                    title: '<replace with initiative title>',
+                    description: '<replace with initiative description>',
+                },
+            ],
+        },
+    });
+}
+function buildUseCaseUpdateTemplate(input) {
+    return jsonTemplate({
+        _instructions: 'Replace placeholders, delete unused sections, then call update_use_case with blueprintId and sections.',
+        blueprintId: input.blueprintId,
+        sections: {
+            title: '<replace with use case title>',
+            description: '<replace with concise use case description>',
+            businessChallenge: '<replace with updated business challenge>',
+            description5Ws: {
+                who: '<replace with impacted people or teams>',
+                what: '<replace with work being changed>',
+                where: '<replace with business area or systems>',
+                when: '<replace with timing or trigger>',
+                why: '<replace with reason this matters>',
+            },
+            currentPainPoints: ['<replace with pain point>'],
+            desiredBusinessOutcomes: ['<replace with desired outcome>'],
+            processDocumentation: {
+                steps: [
+                    {
+                        stepNumber: 1,
+                        description: '<replace with current process step>',
+                        performer: '<replace with performer>',
+                    },
+                ],
+            },
+            transformationStory: {
+                situation: '<replace with current situation>',
+                complication: '<replace with complication>',
+                resolution: '<replace with desired resolution>',
+            },
+            typedSuccessMetrics: [
+                {
+                    metric: '<replace with metric name>',
+                    target: '<replace with target>',
+                },
+            ],
+            organizationalConstraints: ['<replace with constraint>'],
+            affectedDepartments: ['<replace with department>'],
+        },
+    });
+}
+function buildBlueprintUpdateTemplate(input) {
+    return jsonTemplate({
+        _instructions: 'Replace placeholders, delete unused sections, then call update_blueprint with blueprintId and sections. Top-level sections are shallow-merged.',
+        blueprintId: input.blueprintId,
+        sections: {
+            executiveSummary: '<replace with revised executive summary>',
+            agenticPattern: '<replace with agentic pattern if changed>',
+            enhancedDigitalTeam: [
+                {
+                    name: '<replace with agent name>',
+                    role: '<replace with agent role>',
+                    agentRole: '<replace with orchestration role>',
+                    responsibilities: ['<replace with responsibility>'],
+                },
+            ],
+            phases: [
+                {
+                    name: '<replace with phase name>',
+                    phaseGoal: '<replace with phase goal>',
+                    durationWeeks: '<replace with duration in weeks>',
+                },
+            ],
+            architectureRationale: {
+                whyAgentic: ['<replace with rationale>'],
+            },
+            successCriteria: {
+                kpis: [
+                    {
+                        name: '<replace with KPI name>',
+                        target: '<replace with target>',
+                    },
+                ],
+            },
+        },
+    });
+}
+function buildBusinessCaseUpdateTemplate(input) {
+    return jsonTemplate({
+        _instructions: 'Replace placeholders, delete unused sections, then call update_business_case with blueprintId and sections. If numeric assumptions or ROI inputs changed, call recalculate_financials next.',
+        blueprintId: input.blueprintId,
+        sections: {
+            executiveSummary: {
+                purpose: '<replace with revised purpose>',
+                valueProposition: '<replace with revised value proposition>',
+            },
+            businessContext: {
+                problemStatement: '<replace with updated problem statement>',
+            },
+            objectives: {
+                successMetrics: [
+                    {
+                        metric: '<replace with metric name>',
+                        targetValue: '<replace with target value>',
+                    },
+                ],
+            },
+            proposedSolution: {
+                summary: '<replace with solution summary>',
+            },
+            benefits: {
+                tangibleBenefits: {
+                    processEfficiency: '<replace with benefit>',
+                },
+            },
+            risks: {
+                implementationRisks: [
+                    {
+                        title: '<replace with risk title>',
+                        severity: '<replace with severity>',
+                        impact: '<replace with impact>',
+                    },
+                ],
+            },
+            recommendation: {
+                summary: '<replace with recommendation>',
+            },
+        },
+    });
+}
+function buildImplementationPlanUpdateTemplate(input) {
+    return jsonTemplate({
+        _instructions: 'Replace placeholders, delete unused sections, then call update_implementation_plan with blueprintId and sections.',
+        blueprintId: input.blueprintId,
+        sections: {
+            projectOverview: {
+                summary: '<replace with updated implementation summary>',
+            },
+            epics: [
+                {
+                    name: '<replace with epic name>',
+                    description: '<replace with epic description>',
+                    phase: '<replace with phase>',
+                },
+            ],
+            dependencies: ['<replace with dependency>'],
+            resources: {
+                team: ['<replace with required role or team>'],
+            },
+            risks: [
+                {
+                    title: '<replace with implementation risk>',
+                    mitigation: '<replace with mitigation>',
+                },
+            ],
+            agentSpecifications: [
+                {
+                    name: '<replace with agent name>',
+                    implementationNotes: '<replace with implementation notes>',
+                },
+            ],
+        },
+    });
+}
+// =============================================================================
 // IMPLEMENTATION STATE TEMPLATE
 // =============================================================================
 function buildImplementationState(input) {
@@ -2337,6 +2713,31 @@ function buildAgentsMd(input) {
     lines.push('');
     lines.push(`    ${bpId}`);
     lines.push('');
+    lines.push('## Source of truth for edits');
+    lines.push('');
+    lines.push('Markdown files in this export are readable snapshots. Agent Blueprint MCP/CLI');
+    lines.push('writes are the source of truth for saved profile and artifact changes.');
+    lines.push('Use `references/artifact-editing.md` and `editable/*.json` to prepare focused');
+    lines.push('patches, then write them back with MCP tools.');
+    lines.push('');
+    lines.push('## Maintain the business profile');
+    lines.push('');
+    lines.push('When you discover new profile facts, systems, capabilities, operations,');
+    lines.push('constraints, or strategic initiatives:');
+    lines.push('1. Read `references/organization-context.md`');
+    lines.push('2. Fill in `editable/business-profile.update.json`');
+    lines.push('3. Call `update_business_profile` with the `fields` object');
+    lines.push('4. Re-download or refresh stale artifacts before continuing');
+    lines.push('');
+    lines.push('## Ad-hoc artifact edits');
+    lines.push('');
+    lines.push('For piecemeal corrections, use the matching template and MCP write tool:');
+    lines.push('- Use case changes: `editable/use-case.update.json` -> `update_use_case`');
+    lines.push('- Blueprint changes: `editable/blueprint.update.json` -> `update_blueprint`');
+    lines.push('- Business case changes: `editable/business-case.update.json` -> `update_business_case`');
+    lines.push('- Financial number changes: `update_business_case`, then `recalculate_financials`');
+    lines.push('- Implementation plan changes: `editable/implementation-plan.update.json` -> `update_implementation_plan`');
+    lines.push('');
     lines.push('## When to sync implementation state');
     lines.push('');
     lines.push('Sync after each of these events:');
@@ -2625,6 +3026,13 @@ export function renderSkillDirectory(input) {
     files.set('references/guardrails-and-governance.md', buildGuardrailsAndGovernance(input));
     files.set('references/evaluation-criteria.md', buildEvaluationCriteria(input));
     files.set('references/platform-connectivity.md', buildPlatformConnectivity());
+    files.set('references/artifact-editing.md', buildArtifactEditingReference(input));
+    // Editable JSON helper templates (not canonical state)
+    files.set('editable/business-profile.update.json', buildBusinessProfileUpdateTemplate());
+    files.set('editable/use-case.update.json', buildUseCaseUpdateTemplate(input));
+    files.set('editable/blueprint.update.json', buildBlueprintUpdateTemplate(input));
+    files.set('editable/business-case.update.json', buildBusinessCaseUpdateTemplate(input));
+    files.set('editable/implementation-plan.update.json', buildImplementationPlanUpdateTemplate(input));
     // Getting Started guide
     files.set('GETTING-STARTED.md', buildGettingStarted(input));
     // Sync rules (universal -- all coding agents via AGENTS.md standard)