taketomarket 2.2.0 → 2.3.0

package/workflows/site/pseo.md

@@ -0,0 +1,96 @@
+# pSEO Workflow
+
+## Step 0: First-run inline education
+
+Read `.taketomarket/CONFIG.md`. Parse `first_run_seen` (object) and `inline_education` (boolean, default true).
+
+If `inline_education` is false: skip this step. Else if `first_run_seen.ttm-pseo` is not `true`, print the explainer below verbatim, then mark this skill as seen:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-pseo
+```
+
+Use this exact check (bash) to decide whether to print: `node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-pseo --raw` -- the JSON `seen` field is `true` once the explainer has run before.
+
+### Explainer for `/ttm-pseo`
+
+`/ttm-pseo` is programmatic SEO: given a template and a dataset
+(competitors-vs-you, alternatives, integrations, etc.), it generates
+N landing pages with consistent positioning across all of them. Each
+page passes the same gate wall as a single landing page, but in bulk.
+
+Why it matters: pSEO is one of the few SEO plays still worth running
+in the AI-search era because the long tail of "X vs Y" queries doesn't
+get cannibalized as quickly. The catch is that ungoverned pSEO produces
+thousands of near-duplicate, positioning-drifted pages. The gate wall
+is what makes pSEO defensible at scale.
+
+(Canonical source: `references/inline-education-blurbs.md`. Embedded verbatim because workflows do not @-resolve files at runtime.)
+
+---
+
+**Required reading:**
+- `${CLAUDE_PLUGIN_ROOT}/references/pseo-page-anatomy.md`
+- `${CLAUDE_PLUGIN_ROOT}/references/pseo-templates/[template]-anatomy.md`
+- `${CLAUDE_PLUGIN_ROOT}/references/pseo-templates/[template]-content-playbook.md`
+- `${CLAUDE_PLUGIN_ROOT}/templates/pseo/[template]-cms-schema.json`
+- `${CLAUDE_PLUGIN_ROOT}/playbooks/pseo.md` (delivered in P6)
+- `.taketomarket/POSITIONING.md`, `BRAND.md`, `PRODUCT-DNA.md`, `ICP.md`
+
+---
+
+## Step 1: Verify /ttm-landing is run
+
+Read `.taketomarket/CONFIG.md` for `landing_path`. If not set: print "Run /ttm-landing first" and exit.
+
+## Step 2: Parse args
+
+`<template>` must be one of: blog, use-case, comparison, alternative.
+`<sub>` is either `new`, `from-json`, or `list`.
+
+## Step 3 (new): Generate one page
+
+Read appropriate anatomy + content playbook + CMS schema.
+
+AskUserQuestion to gather CMS-schema-required fields, or:
+- For blog: title, tldr, key sections (h2 list), takeaways, FAQ.
+- For use-case: useCase name, problem, feature pillars, walkthrough steps.
+- For comparison: competitor, comparison table rows, when-we-win, when-they-win.
+- For alternative: competitor, why-people-leave, why-we-are-alternative, migration steps.
+
+Validate against CMS schema. If invalid: prompt to fix.
+
+Generate page using content playbook guidance.
+
+Render as Next.js page at `[landing_path]/app/[route]/[slug]/page.tsx`:
+- `/blog/[slug]` for blog
+- `/use-cases/[slug]` for use-case
+- `/vs/[slug]` for comparison
+- `/alternatives/[slug]` for alternative
+
+Include Schema.org markup (Article + FAQPage + BreadcrumbList).
+
+Mandatory humanize step on the generated copy.
+
+Update `sitemap.ts` and `public/llms.txt` to include new route.
+
+## Step 4 (from-json): Batch generate
+
+Parse JSON file. Validate each entry against schema. For each: same as Step 3 but skip user-question phase.
+
+## Step 5 (list): Just enumerate
+
+List all existing pSEO routes by scanning `[landing_path]/app/{blog,use-cases,vs,alternatives}/`.
+
+## Step 6: Quality gates
+
+Run gates from quality-gates.md on each new page.
+
+## Step 7: Print next steps
+
+## What if this doesn't fit?
+
+Looks like /ttm-pseo can't do that yet.
+
+- Want a new skill? /ttm-request-skill
+- Existing skill needs work? /ttm-improve-skill

package/workflows/site/quality-gates.md

@@ -0,0 +1,88 @@
+# Landing Quality Gates
+
+Called by `/ttm-landing`, `/ttm-pseo`, `/ttm-review`, `/ttm-verify` for landing/pSEO assets.
+
+## Gate 1: Positioning integrity
+
+For each generated HTML/TSX file:
+1. Extract visible text (strip tags).
+2. Confirm POSITIONING.md primary differentiator is present (or its key phrasing).
+3. Confirm no banned words from BRAND.md `## Banned words`.
+4. Confirm no must-not-say from POSITIONING.md.
+
+Fail any file that violates.
+
+## Gate 2: Schema.org markup
+
+For each page file:
+1. Confirm a `<script type="application/ld+json">` block exists.
+2. Parse the JSON-LD.
+3. Validate against expected schema type (Article, Product, FAQPage, etc.).
+
+## Gate 3: Performance budget (Playwright)
+
+Requires Playwright MCP. Check before running:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs playwright-check --raw
+```
+
+If not detected: skip with WARN (don't fail). Otherwise:
+
+For each deployed landing/pSEO URL (from CONFIG.md `last_deploy_url`):
+1. Use Playwright MCP to run a Lighthouse audit at the URL.
+2. Extract LCP, CLS, INP from the report.
+3. Compare against budget:
+   - LCP < 2.5s → PASS, else FAIL.
+   - CLS < 0.1 → PASS, else FAIL.
+   - INP < 200ms → PASS, else FAIL.
+
+Output:
+```
+[PASS|FAIL] Gate 3: Performance
+  LCP: 1.8s [PASS]
+  CLS: 0.05 [PASS]
+  INP: 150ms [PASS]
+```
+
+## Gate 4: Mobile responsiveness (Playwright)
+
+Requires Playwright MCP. If not detected: skip with WARN.
+
+For each deployed URL:
+1. Take screenshots at 375px (mobile), 768px (tablet), 1024px (laptop), 1440px (desktop).
+2. AI vision review each screenshot:
+   - No horizontal scroll on mobile.
+   - All CTAs visible without scroll on desktop above-fold.
+   - Text legible at smallest viewport.
+   - No clipped images or overflowing buttons.
+3. Score each viewport PASS/FAIL.
+
+Output:
+```
+[PASS|FAIL] Gate 4: Mobile responsiveness
+  375px: PASS
+  768px: PASS
+  1024px: PASS
+  1440px: PASS
+```
+
+## Gate 5: Internal linking
+
+For each pSEO page:
+- Confirm at least 3 internal links to other pSEO or top-level pages.
+- Confirm at least 1-2 external links to authoritative sources.
+
+## Gate 6: llms.txt
+
+Confirm `public/llms.txt` has been updated to reflect the new route(s).
+
+## Gate result format
+
+For each gate, output:
+```
+[PASS|FAIL] Gate N: <name>
+  Details: <message>
+```
+
+If any FAIL: route caller to /ttm-fix with the gate output as context.

package/workflows/utility/archive.md

@@ -1,3 +1,32 @@
+## Step 0: First-run inline education
+
+Read `.taketomarket/CONFIG.md`. Parse `first_run_seen` (object) and `inline_education` (boolean, default true).
+
+If `inline_education` is false: skip this step. Else if `first_run_seen.ttm-archive` is not `true`, print the explainer below verbatim, then mark this skill as seen:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-archive
+```
+
+Use this exact check (bash) to decide whether to print: `node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-archive --raw` -- the JSON `seen` field is `true` once the explainer has run before.
+
+### Explainer for `/ttm-archive`
+
+`/ttm-archive` moves a finished campaign out of the active set into
+`.taketomarket/archive/`. It freezes STATE.md, preserves the gate
+results and ship records, and removes the campaign from the
+`/ttm-next` queue. Archived campaigns still feed `/ttm-learn`.
+
+Why it matters: campaigns that should be done but stay marked active
+pollute scheduling and waste cognitive budget every time you run
+`/ttm-state`. Archive is the marketing equivalent of merging and
+deleting a branch -- the work is preserved, but it's out of your
+active workspace.
+
+(Canonical source: `references/inline-education-blurbs.md`. Embedded verbatim because workflows do not @-resolve files at runtime.)
+
+---
+
 <purpose>
 Archive workflow for /ttm-archive. Validates campaign is shipped or learned (only
 shipped or learned campaigns can be archived per D-08), extracts structured learnings from campaign
@@ -17,7 +46,7 @@ as cautionary records (D-08).
 <constraints>
 ## POSITIONING.md is READ-ONLY
 
-**Do NOT modify `.marketing/POSITIONING.md` during this workflow.**
+**Do NOT modify `.taketomarket/POSITIONING.md` during this workflow.**
 
 POSITIONING.md is an architectural invariant. If you detect positioning drift:
 - In verify: use the Escalate option to launch /ttm-positioning-shift
@@ -124,9 +153,9 @@ Following the learnings-extraction.md reference guide, scan campaign artifacts.
 
 **Read these files from the campaign directory:**
 
-1. `.marketing/CAMPAIGNS/${SLUG}/STATE.md` (full file -- frontmatter and body)
-2. `.marketing/CAMPAIGNS/${SLUG}/MANIFEST.json` (if exists -- per-asset gate results)
-3. `.marketing/CAMPAIGNS/${SLUG}/BRIEF.md` (if exists -- original strategy)
+1. `.taketomarket/CAMPAIGNS/${SLUG}/STATE.md` (full file -- frontmatter and body)
+2. `.taketomarket/CAMPAIGNS/${SLUG}/MANIFEST.json` (if exists -- per-asset gate results)
+3. `.taketomarket/CAMPAIGNS/${SLUG}/BRIEF.md` (if exists -- original strategy)
 4. `VERIFICATION.md` in the campaign directory (gate details)
 5. Any `FIX-BRIEF-*.md` files (fix attempts and outcomes)
 6. Any `REVIEW-FEEDBACK-*.md` files (human review feedback)
@@ -242,7 +271,7 @@ If the command returns an error:
 - Exit with the error context
 
 The CLI command handles:
-- Moving the campaign directory to `.marketing/CAMPAIGNS/ARCHIVE/${SLUG}/`
+- Moving the campaign directory to `.taketomarket/CAMPAIGNS/ARCHIVE/${SLUG}/`
 - Updating the campaign state to "archived"
 - Validating the campaign is in "shipped" or "learned" phase before allowing archive
 
@@ -258,7 +287,7 @@ takeToMarket > UPDATING LEARNINGS
 The campaign is now in ARCHIVE/ with phase set to "archived". Writing learnings after
 archive confirmation prevents data-loss on retry (duplicate rows) if archive were to fail.
 
-Read `.marketing/LEARNINGS.md`.
+Read `.taketomarket/LEARNINGS.md`.
 
 **Duplicate guard:** Before inserting rows, scan existing LEARNINGS.md content for
 any row containing `| ${SLUG} |` with today's date. If matching rows already exist
@@ -305,7 +334,7 @@ Display completion summary:
 |------|----------|----------|--------|-------------|
 ${extracted_rows}
 
-Campaign directory moved to `.marketing/CAMPAIGNS/ARCHIVE/${SLUG}/`
+Campaign directory moved to `.taketomarket/CAMPAIGNS/ARCHIVE/${SLUG}/`
 
 ### Next Steps
 - Lessons are now available in LEARNINGS.md for future campaigns
@@ -329,6 +358,13 @@ Campaign directory moved to `.marketing/CAMPAIGNS/ARCHIVE/${SLUG}/`
 </success_criteria>
 
 <output>
-- `.marketing/LEARNINGS.md` (updated with extracted lessons)
-- `.marketing/CAMPAIGNS/ARCHIVE/${SLUG}/STATE.md` (phase set to archived, via CLI)
+- `.taketomarket/LEARNINGS.md` (updated with extracted lessons)
+- `.taketomarket/CAMPAIGNS/ARCHIVE/${SLUG}/STATE.md` (phase set to archived, via CLI)
 </output>
+
+## What if this doesn't fit?
+
+Looks like /ttm-archive can't do that yet.
+
+- Want a new skill? /ttm-request-skill
+- Existing skill needs work? /ttm-improve-skill

package/workflows/utility/health.md

@@ -1,5 +1,35 @@
+## Step 0: First-run inline education
+
+Read `.taketomarket/CONFIG.md`. Parse `first_run_seen` (object) and `inline_education` (boolean, default true).
+
+If `inline_education` is false: skip this step. Else if `first_run_seen.ttm-health` is not `true`, print the explainer below verbatim, then mark this skill as seen:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-health
+```
+
+Use this exact check (bash) to decide whether to print: `node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-health --raw` -- the JSON `seen` field is `true` once the explainer has run before.
+
+### Explainer for `/ttm-health`
+
+`/ttm-health` audits the integrity of your `.taketomarket/` directory.
+It checks that reference files exist and aren't suspiciously empty,
+flags stale references, validates per-campaign STATE.md against the
+file system, surfaces DRIFT-LOG anomalies, and reports gate-result
+inconsistencies. It only reports -- it does not self-heal.
+
+Why it matters: state corruption in a long-running multi-campaign
+project is silent until something breaks. Running health periodically
+(or letting it auto-trigger on detected issues) catches drift like a
+filesystem fsck -- before it forces a manual rebuild of a campaign's
+state.
+
+(Canonical source: `references/inline-education-blurbs.md`. Embedded verbatim because workflows do not @-resolve files at runtime.)
+
+---
+
 <purpose>
-Health audit workflow for /ttm-health. Validates .marketing/ directory integrity,
+Health audit workflow for /ttm-health. Validates .taketomarket/ directory integrity,
 reference file completeness, per-campaign state consistency, reference file staleness,
 campaign velocity, DRIFT-LOG integrity, and gate result consistency. Reports text
 output with pass/warn/fail per check category. Does NOT self-heal -- only reports.
@@ -12,7 +42,7 @@ output with pass/warn/fail per check category. Does NOT self-heal -- only report
 <constraints>
 ## POSITIONING.md is READ-ONLY
 
-**Do NOT modify `.marketing/POSITIONING.md` during this workflow.**
+**Do NOT modify `.taketomarket/POSITIONING.md` during this workflow.**
 
 POSITIONING.md is an architectural invariant. If you detect positioning drift:
 - In verify: use the Escalate option to launch /ttm-positioning-shift
@@ -29,6 +59,43 @@ commands or manual actions the user should take.
 
 <process>
 
+## Step: Legacy folder check
+
+Before running the main audit, detect whether the project still uses the legacy
+`.marketing/` state directory and offer migration to the canonical `.taketomarket/`.
+
+Run the legacy-folder check:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" legacy-folder check --raw
+```
+
+Parse the JSON `state` field:
+
+- **legacy**: print `WARN: Legacy '.marketing/' folder detected. Migration will rename it to '.taketomarket/'. Recommend committing or backing up first (the rename is fast but not reversible from inside the workflow).` Then use `AskUserQuestion`:
+  - question: "Migrate `.marketing/` to `.taketomarket/` now?"
+  - options: "Yes, migrate now" / "Skip for now"
+  - On Yes:
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" legacy-folder migrate --raw
+    ```
+    Then verify `.taketomarket/` exists.
+  - On Skip: continue to Step 1 with a note that the audit will report `.marketing/` paths.
+- **conflict**: print the error below, then halt the workflow:
+  ```
+  ERROR: Both .marketing/ and .taketomarket/ exist. Manual resolution required.
+
+  To resolve:
+    1. Compare contents:  diff -r .marketing .taketomarket
+    2. Merge any unique files from .marketing/ into .taketomarket/.
+    3. Once .taketomarket/ has everything you need, remove the legacy folder:
+       rm -rf .marketing
+    4. Re-run /ttm-health to confirm.
+  ```
+- **current** or **none**: continue silently to Step 1.
+
+---
+
 ## Step 1: Run Health Audit
 
 ```
@@ -80,7 +147,7 @@ Group checks by category based on their `name` prefix or type:
 ## Health Report
 
 ### Structural Integrity
-  [PASS] .marketing/ directory exists
+  [PASS] .taketomarket/ directory exists
   [PASS] CAMPAIGNS/ directory exists
   [PASS] Required subdirectories present
 
@@ -164,3 +231,10 @@ All systems healthy. No action needed.
 <output>
 No files modified (diagnostic command).
 </output>
+
+## What if this doesn't fit?
+
+Looks like /ttm-health can't do that yet.
+
+- Want a new skill? /ttm-request-skill
+- Existing skill needs work? /ttm-improve-skill

package/workflows/utility/improve-skill.md

@@ -0,0 +1,233 @@
+## Step 0: First-run inline education
+
+Read `.taketomarket/CONFIG.md`. Parse `first_run_seen` (object) and `inline_education` (boolean, default true).
+
+If `inline_education` is false: skip this step. Else if `first_run_seen.ttm-improve-skill` is not `true`, print the explainer below verbatim, then mark this skill as seen:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-improve-skill
+```
+
+Use this exact check (bash) to decide whether to print: `node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-improve-skill --raw` -- the JSON `seen` field is `true` once the explainer has run before.
+
+### Explainer for `/ttm-improve-skill`
+
+`/ttm-improve-skill` opens a feedback loop on a specific takeToMarket
+skill. It diffs your last few invocations of a skill, asks what felt
+wrong or missing, and either drafts a local skill override or files a
+structured issue against the takeToMarket repo so the change can land
+upstream.
+
+Why it matters: takeToMarket is opinionated, which means it'll be
+wrong about your context sometimes. This skill is the structured
+escape hatch -- instead of fighting the skill in-conversation, you
+record the friction, get a fix, and avoid that friction permanently.
+Treat it like filing a linter rule exemption.
+
+(Canonical source: `references/inline-education-blurbs.md`. Embedded verbatim because workflows do not @-resolve files at runtime.)
+
+---
+
+<purpose>
+Skill improvement workflow for /ttm-improve-skill. Gathers details about an
+EXISTING skill that needs changes and files a GitHub issue at
+ranjanrishikesh/taketomarket. Prefers the `gh` CLI when installed and
+authenticated; falls back to opening a pre-filled GitHub issue URL in the
+browser.
+</purpose>
+
+<constraints>
+## Read-Only on the Local Project
+
+This workflow does NOT modify any files in the user's project. It only creates
+a remote GitHub issue (via `gh`) or prints a URL for the user to open.
+
+## Repo Identity
+
+Always file issues at `ranjanrishikesh/taketomarket` (lowercase). Do not infer
+a different repo from local git remotes.
+
+## No Secrets in Issue Body
+
+Do NOT include API keys, tokens, file paths containing credentials, or any
+content from `.taketomarket/` reference files in the issue body. Only echo the
+user's freeform answers verbatim.
+</constraints>
+
+<process>
+
+## Step 1: Enumerate existing skills
+
+```
+takeToMarket > REPORT A SKILL IMPROVEMENT
+```
+
+List installed ttm-* skills so the user can pick one:
+
+```bash
+ls -1 "${CLAUDE_PLUGIN_ROOT}/skills" | grep '^ttm-' | sort
+```
+
+Present the list to the user.
+
+---
+
+## Step 2: Gather details
+
+Use `AskUserQuestion` (priority: critical) to collect:
+
+1. **Which skill?** — "Which skill needs improvement?"
+   - `multiSelect` from the enumerated `ttm-*` skill list.
+   - Allow a freeform fallback in case the user wants to name a skill not yet
+     visible locally.
+2. **What's not working?** — "What's not working with this skill?"
+   - Freeform, multi-line allowed.
+3. **Expected behavior** — "What's the expected behavior?"
+   - Freeform, multi-line allowed.
+4. **Steps to reproduce** — "Steps to reproduce (if a bug)."
+   - Freeform, multi-line allowed. Optional — accept an empty answer.
+
+Store the answers as `WHICH_SKILL`, `NOT_WORKING`, `EXPECTED`, `REPRO_STEPS`.
+
+If the user selected multiple skills, join them with `, ` for the issue title
+and body.
+
+---
+
+## Step 3: Detect gh CLI
+
+```bash
+GH_STATE="no-gh"
+if command -v gh >/dev/null 2>&1; then
+  if gh auth status >/dev/null 2>&1; then
+    GH_STATE="gh-ready"
+  fi
+fi
+echo "$GH_STATE"
+```
+
+If `GH_STATE` is `gh-ready`, proceed to Step 4.
+Otherwise, proceed to Step 5.
+
+---
+
+## Step 4: If gh-ready, file issue via gh CLI
+
+Build the issue body from the gathered answers, then run:
+
+```bash
+gh issue create \
+  --repo ranjanrishikesh/taketomarket \
+  --title "[Skill improvement] ${WHICH_SKILL}" \
+  --body "$(cat <<'EOF'
+**Which skill:** ${WHICH_SKILL}
+**What's not working:** ${NOT_WORKING}
+**Expected behavior:** ${EXPECTED}
+**Steps to reproduce:** ${REPRO_STEPS}
+
+---
+Filed via /ttm-improve-skill
+EOF
+)"
+```
+
+(Substitute the variables before passing to the heredoc — the heredoc above is
+quoted to prevent shell expansion of literal `${...}` placeholders. Build the
+body string first and pass the resolved text via `--body`.)
+
+Capture the resulting issue URL printed by `gh issue create`. Display it to
+the user:
+
+```
+takeToMarket > SKILL IMPROVEMENT FILED
+
+Issue: <issue-url>
+
+Thanks for the report. You can track it at the URL above.
+```
+
+Done — exit successfully.
+
+---
+
+## Step 5: If no-gh, generate pre-filled URL
+
+When `gh` is not installed or not authenticated, build a pre-filled GitHub
+issue URL pointing at the `skill-improvement.yml` template.
+
+URL-encode the title and body. The body fields map to template field IDs:
+`which-skill`, `not-working`, `expected`, `repro-steps`.
+
+Construct (conceptually):
+
+```
+https://github.com/ranjanrishikesh/taketomarket/issues/new
+  ?template=skill-improvement.yml
+  &title=<urlencoded "[Skill improvement] WHICH_SKILL">
+  &which-skill=<urlencoded WHICH_SKILL>
+  &not-working=<urlencoded NOT_WORKING>
+  &expected=<urlencoded EXPECTED>
+  &repro-steps=<urlencoded REPRO_STEPS>
+```
+
+You can generate the encoded URL with:
+
+```bash
+python3 - <<'PY'
+import urllib.parse
+import os
+title = f"[Skill improvement] {os.environ['WHICH_SKILL']}"
+params = {
+    "template": "skill-improvement.yml",
+    "title": title,
+    "which-skill": os.environ["WHICH_SKILL"],
+    "not-working": os.environ["NOT_WORKING"],
+    "expected": os.environ["EXPECTED"],
+    "repro-steps": os.environ.get("REPRO_STEPS", ""),
+}
+qs = urllib.parse.urlencode(params)
+print(f"https://github.com/ranjanrishikesh/taketomarket/issues/new?{qs}")
+PY
+```
+
+(Export `WHICH_SKILL`, `NOT_WORKING`, `EXPECTED`, `REPRO_STEPS` to the
+environment before running the snippet.)
+
+Print the URL and instruct the user:
+
+```
+takeToMarket > OPEN IN BROWSER
+
+gh CLI not detected (or not authenticated). Open this URL to file the issue:
+
+<url>
+
+Tip: install `gh` (https://cli.github.com) and run `gh auth login` to file
+issues directly next time.
+```
+
+Done — exit successfully.
+
+</process>
+
+<success_criteria>
+- [ ] Installed ttm-* skills listed for user selection
+- [ ] Four questions asked via AskUserQuestion (which-skill, not-working, expected, repro)
+- [ ] gh CLI detection performed (command + auth status)
+- [ ] If gh ready: issue created at ranjanrishikesh/taketomarket with `[Skill improvement]` prefix
+- [ ] If no gh: pre-filled URL printed with template=skill-improvement.yml and encoded title/body fields
+- [ ] No local files modified
+</success_criteria>
+
+<output>
+No local files modified. Either a GitHub issue is created remotely (gh path)
+or a URL is printed for the user to open (browser path).
+</output>
+
+## What if this doesn't fit?
+
+Looks like /ttm-improve-skill can't do that yet. Try one of:
+
+- Want a brand-new skill instead? /ttm-request-skill
+- Need an overview of the system first? /ttm-101
+- Otherwise file a free-form issue: https://github.com/ranjanrishikesh/taketomarket/issues/new

package/workflows/utility/next.md

@@ -1,3 +1,32 @@
+## Step 0: First-run inline education
+
+Read `.taketomarket/CONFIG.md`. Parse `first_run_seen` (object) and `inline_education` (boolean, default true).
+
+If `inline_education` is false: skip this step. Else if `first_run_seen.ttm-next` is not `true`, print the explainer below verbatim, then mark this skill as seen:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run mark ttm-next
+```
+
+Use this exact check (bash) to decide whether to print: `node "${CLAUDE_PLUGIN_ROOT}/bin/ttm-tools.cjs" first-run check ttm-next --raw` -- the JSON `seen` field is `true` once the explainer has run before.
+
+### Explainer for `/ttm-next`
+
+`/ttm-next` scans every active campaign in the project and proposes
+the single highest-priority next move across the whole portfolio.
+Output is a ranked list with one top recommendation plus up to
+three alternatives, each as a runnable `/ttm-*` command.
+
+Why it matters: when more than two campaigns are active, "what
+should I do next" becomes a meaningful decision that depends on
+which campaigns are stuck, which are about to lose momentum, and
+which have the soonest measurable outcome. This skill is the
+scheduler for your marketing pipeline.
+
+(Canonical source: `references/inline-education-blurbs.md`. Embedded verbatim because workflows do not @-resolve files at runtime.)
+
+---
+
 <purpose>
 Next-command routing workflow for /ttm-next. Looks across ALL active campaigns,
 prioritizes which needs attention most, and suggests the specific /ttm-* command
@@ -13,7 +42,7 @@ in created and researched phases.
 <constraints>
 ## POSITIONING.md is READ-ONLY
 
-**Do NOT modify `.marketing/POSITIONING.md` during this workflow.**
+**Do NOT modify `.taketomarket/POSITIONING.md` during this workflow.**
 
 POSITIONING.md is an architectural invariant. If you detect positioning drift:
 - In verify: use the Escalate option to launch /ttm-positioning-shift
@@ -67,7 +96,7 @@ the phase-to-command mapping:
 
 | Current Phase | Next Command | Notes |
 |---------------|--------------|-------|
-| `created` | `/ttm-research <slug>` | New campaign needs research |
+| `created` | `/ttm-discover <slug>` | New campaign needs research |
 | `researched` | `/ttm-brief <slug>` | Research done, needs brief |
 | `briefed` | `/ttm-produce <slug>` | Brief ready, produce content |
 | `produced` | `/ttm-verify <slug>` | Content ready, verify quality |
@@ -185,3 +214,10 @@ append a note: "(Note: this command is not yet available -- coming in Phase 9)"
 <output>
 No files modified (read-only command).
 </output>
+
+## What if this doesn't fit?
+
+Looks like /ttm-next can't do that yet.
+
+- Want a new skill? /ttm-request-skill
+- Existing skill needs work? /ttm-improve-skill