@higrowth/cli 0.3.3 → 0.3.5

package/dist/index.js

@@ -703,7 +703,7 @@ just say which one \u2014 you don't have to redo the whole interview."*
 // src/skills/marketing-strategy.ts
 var MARKETING_STRATEGY = `---
 name: higrowth-marketing-strategy
-description: Helps the user interpret a Higrowth diagnostic, choose a bounded scoped-plan area, review imagination hypotheses, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, ask what can be fixed in an area, or plan.
+description: Helps the user interpret a Higrowth diagnostic, choose a bounded scoped-plan or topic-roadmap area, review imagination hypotheses, and shape the next 2-4 week sprint. Use when the user wants to talk through their report, decide what to ship, ask what can be fixed in an area, create/update content from roadmap gaps, or plan.
 allowed-tools: mcp__higrowth__execute_typescript
 ---
 
@@ -717,7 +717,8 @@ measurable scoped plan that can move the needle.
 
 Trigger on: "what should I focus on", "walk me through my report",
 "prioritize this", "what's the move", "plan my sprint", "what can we
-fix in [area/topic/page]".
+fix in [area/topic/page]", "what are the gaps in this topic", "plan this
+roadmap", "what new pages or updates should we create".
 
 ## Mental model
 
@@ -725,20 +726,32 @@ Plans are not giant backlogs. A good plan is a scoped intervention:
 one topic area, page cluster, gap type, or conversion slice with enough
 evidence to act and narrow enough boundaries to avoid conflicting work.
 
-The planning stack has four layers:
+The planning stack has six layers:
 
 1. **Answer map** \u2014 what questions the site answers for which persona
    and decision stage.
 2. **Decision candidates** \u2014 executable moves grounded in answer cells,
    gaps, GSC, GA, strategy, and conflict checks.
-3. **Imagination candidates** \u2014 adjacent hypotheses HG can infer from
+3. **Topic roadmap** \u2014 the topic-area execution ledger: new pages to
+   create, pages to refresh, consolidation/removal, internal links, and
+   measurement/setup rows. When the user asks about a topic's gaps or
+   roadmap, these rows are a first-class planning source.
+4. **Imagination candidates** \u2014 adjacent hypotheses HG can infer from
    weak or missing answers. They are ideas only.
-4. **Scoped plans** \u2014 a small selected scope that generates execution
-   items from decision candidates.
+5. **Scoped plans** \u2014 a small selected scope that generates execution
+   items from roadmap rows, scoped gaps, pages, answer cells, or decision
+   candidates.
+6. **Authored plans** \u2014 when the harness can synthesize the right
+   strategic shape better than the built-in generator, it may write the
+   staging plan artifact directly into HG via the authored-plan API,
+   using HG signals as evidence.
 
 Rank by **leverage, evidence, and executability**, not raw opportunity count.
 Never create work orders directly from imagination candidates. Promote
 good imagination candidates into decision candidates first, then plan.
+Roadmap rows do not need promotion: use them directly when the user's
+intent is to execute a topic roadmap. Authored plans do not bypass
+review or execution approval: they create/edit staging plan artifacts.
 
 ## The conversation
 
@@ -818,6 +831,31 @@ If answer-map compute still returns little or no signal, say so. The
 right prerequisite may be a scan, GSC/GA connection, KB population, or
 pillar analysis. Do not fabricate a strategic plan from thin data.
 
+Also check the topic roadmap when the user asks about a topic, gaps,
+new content, content updates, or comprehensiveness:
+
+\`\`\`ts
+const roadmap = topicId
+  ? await api.get(\`/api/topics/\${topicId}/roadmap\`)
+  : null;
+const openRoadmapItems =
+  roadmap?.items?.filter(item => item.status === 'open') ?? [];
+
+console.log(openRoadmapItems.map(item => ({
+  id: item.id,
+  actionType: item.actionType,
+  title: item.title,
+  targetPageUrl: item.targetPageUrl,
+  queries: item.queries?.slice(0, 5) ?? [],
+  existingCoverage: item.coverage?.length ?? 0,
+})));
+\`\`\`
+
+Roadmap rows answer: what new pages to create, which pages to update,
+what to consolidate or remove, where internal links are missing, and
+what measurement/setup work blocks confidence. Treat open roadmap rows
+as source evidence, not as loose suggestions.
+
 ### Step 4 \u2014 Use imagination only when useful
 
 When the user asks "what else could we do here?", "what are we missing?",
@@ -857,6 +895,97 @@ with observed-gap candidates.
 
 ### Step 5 \u2014 Choose a bounded scope
 
+If the user explicitly asked to execute a topic roadmap, prefer a
+roadmap-derived scope over a generic candidate. The open roadmap rows
+are the scope thesis.
+
+\`\`\`ts
+function compactRoadmapSourceId(topicId, items) {
+  const key = (items ?? [])
+    .map(item => item.id)
+    .sort()
+    .join('_')
+    .replace(/[^a-zA-Z0-9_-]/g, '')
+    .slice(0, 96) || 'open';
+  return \`roadmap_topic_v6_\${topicId}_\${key}\`;
+}
+
+function analysisTypesFromRoadmap(items) {
+  const types = new Set(['supply_tactical']);
+  for (const item of items ?? []) {
+    if (item.actionType === 'new_content') types.add('demand_pull');
+    if (item.actionType === 'internal_linking') types.add('structural');
+    if (item.actionType === 'page_refresh') types.add('positioning');
+    if (item.actionType === 'measurement') types.add('conversion');
+  }
+  return [...types];
+}
+
+function roadmapScope(topicId, topicName, entityId, openItems) {
+  const analysisTypes = analysisTypesFromRoadmap(openItems);
+  return {
+    version: 1,
+    selectedAt: new Date().toISOString(),
+    selectedBy: 'agent',
+    sourceCandidateId: compactRoadmapSourceId(topicId, openItems),
+    entityId,
+    label: \`\${topicName ?? 'Topic'} roadmap execution scope\`,
+    scopeType: 'subtopic',
+    topicId,
+    subtopicIds: [],
+    pageIds: [],
+    gapIds: [],
+    answerCellIds: [],
+    decisionCandidateIds: [],
+    primaryPersonaIds: [],
+    decisionStages: [],
+    scopeThesis: [
+      \`Use the \${topicName ?? 'selected topic'} roadmap as the execution source of truth.\`,
+      ...openItems.slice(0, 8).map((item, index) =>
+        [
+          \`\${index + 1}. \${item.title}\`,
+          \`Action: \${item.actionType} (\${item.priority} priority).\`,
+          item.recommendedAction ? \`Recommended move: \${item.recommendedAction}\` : null,
+          item.targetPageUrl ? \`Target page: \${item.targetPageUrl}\` : null,
+          item.queries?.length ? \`Queries/questions: \${item.queries.join('; ')}\` : null,
+          item.why ? \`Why: \${item.why}\` : null,
+        ].filter(Boolean).join(' ')
+      ),
+    ].join('\\n'),
+    analysisTypes,
+    includedSignals: [
+      'topic_roadmap',
+      'gap_inventory',
+      'question_pool',
+      'page_summaries',
+      'serp_opportunities',
+      ...analysisTypes,
+    ],
+    excludedAdjacentScopes: [],
+    reasonForScope:
+      'The user requested a plan that executes the currently open roadmap gaps for this topic.',
+    expectedOutcome:
+      'Generate concrete plan items to create, refresh, consolidate, remove, link, or measure the pages called out by the open roadmap rows without cannibalizing existing topic coverage.',
+  };
+}
+
+const useRoadmapScope = topicId && openRoadmapItems.length > 0 &&
+  /roadmap|gaps|gap|new pages|new content|updates|refresh|comprehensive/i.test(userIntent ?? '');
+
+let selected = null;
+let preview = null;
+if (useRoadmapScope) {
+  const scope = roadmapScope(topicId, topicName, entityId, openRoadmapItems);
+  preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
+    selectedBy: 'agent',
+    userIntent: q,
+    scope,
+  });
+}
+\`\`\`
+
+If you are not in roadmap mode, use ranked scoped candidates:
+
 \`\`\`ts
 const candidates = await api.get(
   \`/api/entities/\${entityId}/plan-scopes/candidates?q=\${encodeURIComponent(q)}&limit=8&maxItems=8\`
@@ -866,14 +995,14 @@ const candidates = await api.get(
 Show the top 3 candidates with:
 - label
 - scope type
-- pages, gaps, answer cells, and decision candidates included
+- pages, gaps, answer cells, roadmap rows, and decision candidates included
 - personas and decision stages if present
 - expected outcome
 - conflict state and warnings
 - why you prefer one
 
 Prefer scopes that are:
-- decision-backed
+- roadmap-backed or decision-backed
 - page-bounded or small topic-bounded
 - clear about persona x decision stage x question
 - conflict-clear
@@ -881,17 +1010,18 @@ Prefer scopes that are:
 
 If every candidate is weak, broaden the query once. If candidates are
 still thin, say the source data is missing and suggest the prerequisite
-connection, scan, or KB work.
+connection, scan, KB work, or roadmap generation.
 
 ### Step 6 \u2014 Inspect conflicts before committing
 
 Never stage a scope blindly. Use preview when the user is leaning toward
 a candidate or asks why it is safe.
 
-Convert the candidate to a full scope without dropping the evidence
-bindings:
+For non-roadmap scopes, convert the candidate to a full scope without
+dropping the evidence bindings:
 
 \`\`\`ts
+selected = candidates.candidates[0];
 function toScope(selected) {
   return {
     version: 1,
@@ -923,12 +1053,13 @@ function toScope(selected) {
   };
 }
 
-const selected = candidates.candidates[0];
-const preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
-  selectedBy: 'agent',
-  userIntent: q,
-  scope: toScope(selected),
-});
+if (!preview) {
+  preview = await api.post(\`/api/entities/\${entityId}/plan-scopes/preview\`, {
+    selectedBy: 'agent',
+    userIntent: q,
+    scope: toScope(selected),
+  });
+}
 \`\`\`
 
 If preview returns blocked conflicts, do not create the plan. Explain
@@ -956,9 +1087,11 @@ Create from the selected scope. Do not use legacy topic-plan or
 opportunity-basket endpoints.
 
 \`\`\`ts
+const planLabel = selected?.label ?? preview.scope.label;
+const planDescription = selected?.expectedOutcome ?? preview.scope.expectedOutcome;
 const plan = await api.post(\`/api/entities/\${entityId}/plans/from-scope\`, {
-  name: selected.label,
-  description: selected.expectedOutcome,
+  name: planLabel,
+  description: planDescription,
   scope: preview.scope,
   conflictOverride:
     preview.conflicts.some(c => c.severity === 'warn')
@@ -975,9 +1108,11 @@ console.log(generation);
 \`\`\`
 
 Generation must stay inside the selected scope. It should claim only
-the gaps and pages in the scope, cite \`decisionCandidateIds\`, carry
-conflict warnings into the audit, and return deferred or not-recommended
-items instead of stretching the scope to look productive.
+the gaps and pages in the scope, cite the selected evidence spine
+(\`topic_roadmap\` rows, scoped gaps, pages, answer cells, or
+\`decisionCandidateIds\`), carry conflict warnings into the audit, and
+return deferred or not-recommended items instead of stretching the scope
+to look productive.
 
 After generation, read the plan and verify it stayed grounded:
 
@@ -992,7 +1127,155 @@ console.log(detail.items.map(i => ({
 Explain what to review and which first 1-3 items are safest to move into
 execution.
 
-### Step 10 \u2014 Set expectations
+### Step 10 \u2014 Or hand-author the plan when the harness can do better
+
+If the user wants a specific strategic outcome and the built-in plan
+generator is producing the wrong shape, the harness may directly author
+the plan into HG. This is allowed. Do it only after reading enough HG
+context to make the plan useful: diagnostic narrative, topic/pillar ids,
+topic roadmap rows, decision candidates, gaps, page signals,
+strategy/KB facts, and user constraints from the conversation.
+
+Use this path when the outcome is "get the right plan artifact into HG"
+rather than "let HG generate whatever it thinks is next." The import
+creates a staging plan with provenance; it does not dispatch work.
+
+\`\`\`ts
+const imported = await api.post(\`/api/entities/\${entityId}/plans/import\`, {
+  source: 'codex-harness',
+  name: 'Decision-stage proof sprint',
+  description: 'Tighten evaluation pages around buyer objections and proof gaps.',
+  narrative: [
+    'The strategic bet is...',
+    'The evidence says...',
+    'The execution risk is...',
+    'The expected outcome is...',
+  ].join('
+
+'),
+  kind: 'scoped_plan',
+  topicId,
+  mode: 'grow',
+  contextManifest: {
+    diagnosticId,
+    topicId,
+    roadmapItemIds: openRoadmapItems.map(item => item.id),
+    decisionCandidateIds: selected?.decisionCandidateIds ?? [],
+    gapIds: selected?.gapIds ?? [],
+    pageIds: selected?.pageIds ?? [],
+  },
+  inputSnapshot: {
+    userIntent: q,
+    selectedScope: selected ?? null,
+    preview: preview ?? null,
+    openRoadmapItems,
+    topDecisionCandidates: decisions.candidates.slice(0, 10),
+  },
+  items: [
+    {
+      type: 'manual',
+      kind: 'page_overhaul',
+      title: 'Rewrite the comparison proof section',
+      description: 'Make the evaluation page answer the buyer objection directly.',
+      rationale: 'Grounded in the decision-stage answer gap and weak proof coverage.',
+      pillarId: topicId,
+      pillarName: topicName,
+      targetPageUrl: 'https://example.com/product/comparison',
+      sequence: 1,
+      addressesLenses: ['conversion', 'supply'],
+      brief: {
+        objective: 'Win evaluation-stage trust for the selected persona.',
+        acceptance: [
+          'Lead with a direct answer in the first 100 words',
+          'Add proof points tied to the named persona',
+        ],
+        evidence: {
+          roadmapItemIds: openRoadmapItems.map(item => item.id),
+          decisionCandidateIds: selected?.decisionCandidateIds ?? [],
+          gapIds: selected?.gapIds ?? [],
+        },
+      },
+    },
+  ],
+});
+
+console.log(imported.plan.id, imported.itemIds);
+\`\`\`
+
+If the user has delegated the strategy call and the imported plan is
+ready for the team to use, inspect it and accept it:
+
+\`\`\`ts
+const accepted = await api.post(\`/api/plans/\${imported.plan.id}/accept\`, {});
+
+console.log(accepted.plan.id, accepted.plan.status);
+\`\`\`
+
+Accepting promotes the plan artifact to \`active\`. It still does not
+dispatch work orders; item execution remains on the normal review/status
+path.
+
+Use follow-up authoring endpoints when the user wants refinement:
+
+\`\`\`ts
+await api.patch(\`/api/plans/\${planId}/authoring\`, {
+  narrative: revisedNarrative,
+  mode: 'defend',
+});
+
+await api.patch(\`/api/plans/\${planId}/items/\${itemId}/authoring\`, {
+  title: revisedTitle,
+  rationale: revisedRationale,
+  addressesLenses: ['conversion'],
+});
+
+await api.put(\`/api/plans/\${planId}/items/\${itemId}/brief\`, {
+  brief: revisedBrief,
+});
+\`\`\`
+
+Important boundaries:
+- Direct-authored plans are imported as \`staging\`. Accept them only when
+  the user has delegated that decision or after the user reviews the
+  artifact.
+- Only edit/delete authored items while they are \`todo\` or \`review\`.
+  Once an item is in progress, treat it as execution state.
+- Do not bypass conflict thinking. If you skipped scoped generation
+  because the harness authored the strategy, still read existing plans
+  and explain overlap risks.
+- Do not create work orders directly from the authored plan. Work orders
+  are projected by HG when plan items move through the normal approval path.
+
+### Step 11 \u2014 Generate content briefs when the plan item is ready
+
+For roadmap new-page rows or plan items that need a writer-ready brief,
+use the brief generator only when you can resolve a source question id
+from the roadmap row or its covered opportunity keys. Let the user add a
+thesis, proof point, competitor angle, product workflow, related product,
+use case, benefit, or unique take as \`guidance\`.
+
+\`\`\`ts
+const brief = await api.post(
+  \`/api/diagnostics/\${diagnosticId}/questions/\${questionId}/generate-brief\`,
+  {
+    targetPlanItemId: planItemId ?? null,
+    guidance: userBriefGuidance ?? null,
+    previousFailure: previousBriefFailure ?? null,
+  }
+);
+console.log(brief);
+\`\`\`
+
+A useful brief should cover focus keyword, secondary keywords, target
+questions, competitor/SERP and AEO shape, related products, use cases,
+benefits to include, the company's unique angle or thesis, outline, and
+key facts/proof the writer can cite.
+
+If the generator asks for missing inputs, do not invent them. Surface the
+open questions to the user and use the brief chat/context flow to fill
+only those blanks. Then regenerate with the user's guidance.
+
+### Step 12 \u2014 Set expectations
 
 End with reality:
 
@@ -1004,7 +1287,11 @@ End with reality:
 
 - **One bounded scope per plan.** Always.
 - **Decision candidates are the execution menu.** If a plan ignores them,
-  stop and investigate.
+  stop and investigate, unless this is a roadmap-derived scope whose
+  execution menu is the open roadmap rows.
+- **Topic roadmap rows are execution evidence.** Use them directly for
+  topic-gap, new-page, page-refresh, consolidation, internal-link, and
+  measurement planning.
 - **Imagination is hypothesis generation.** Promote it before planning;
   never execute it directly.
 - **Prefer conflict-clear scopes.** Warning scopes require explicit user acceptance.
@@ -1019,13 +1306,18 @@ End with reality:
 ## What success looks like
 
 - Source signal checked
+- Topic roadmap checked when the user asks about topic gaps, new pages,
+  updates, or comprehensiveness
 - Decision candidates refreshed
 - Imagination candidates reviewed when useful
 - One bounded scope picked
 - Conflicts reviewed
 - One scoped plan created
-- Scoped generation run
-- Generated items cite decision candidates
+- Scoped generation run, or a hand-authored staging plan imported when
+  the harness can produce the better strategic shape
+- Generated or authored items cite the selected evidence spine
+- Content briefs generated only from resolvable roadmap/plan-item source
+  questions, with user guidance captured when needed
 - First execution items are obvious
 - User knows when to come back: 14 days for outcomes, sooner for approvals
 
@@ -1037,10 +1329,22 @@ End with reality:
   or \`POST /api/plans/:id/generate-topic\`.
 - Don't sort opportunities by score and list the top 10. That's not strategy.
 - Don't let URLs alone classify scope. Use the evidence Higrowth gathered.
+- Don't ignore open topic roadmap rows when the user asks for topic gaps,
+  comprehensiveness, new pages, or content updates.
 - Don't drop \`answerCellIds\`, \`decisionCandidateIds\`, \`primaryPersonaIds\`,
   \`decisionStages\`, or \`scopeThesis\` when previewing or creating a scope.
+  For roadmap scopes, preserve the roadmap rows in \`scopeThesis\` and
+  include \`topic_roadmap\` in \`includedSignals\`.
 - Don't create a plan that overlaps blocked active work.
 - Don't create work orders from imagination candidates.
+- Don't use the authored-plan API as a shortcut around evidence. It is
+  for writing a better plan artifact into HG after reading HG context,
+  not for making up work.
+- Don't edit in-progress/published/verified plan items through authoring
+  endpoints. Those are execution state.
+- Don't hand-write content briefs when the brief generator has a source
+  question. Generate, inspect open questions, collect guidance, then
+  regenerate.
 - Don't run a new scan by default. Check answer map, decision candidates,
   GSC, GA, and KB first; scan only when source signal is missing or stale.
 - Don't gloss over the KB. If the KB is empty, stop and run the
@@ -1228,7 +1532,7 @@ var SKILLS = [
   {
     slug: "higrowth-marketing-strategy",
     title: "Marketing strategy chat",
-    description: "Walk a diagnostic, pick a pillar, build the sprint plan.",
+    description: "Walk a diagnostic, pick a scoped topic or roadmap, generate or hand-author the staging plan.",
     body: MARKETING_STRATEGY
   },
   {
@@ -1473,7 +1777,7 @@ function beginUpdateCheck(currentVersion) {
 // package.json
 var package_default = {
   name: "@higrowth/cli",
-  version: "0.3.3",
+  version: "0.3.5",
   description: "Higrowth CLI \u2014 log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   type: "module",
   license: "Apache-2.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@higrowth/cli",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Higrowth CLI — log in via browser, install Claude Code / Codex skills, manage the MCP connection.",
   "type": "module",
   "license": "Apache-2.0",