greprag 0.9.1 → 0.11.0

package/skill/content-advisor/docs/handoff-contract.md

@@ -0,0 +1,91 @@
+# Handoff Contract
+
+The content-advisor's output ends at a brief. The writer master takes it from there. Source of truth: `C:/openwriter/skills/WRITER-CONVENTION.md` — read it before changing anything in this doc.
+
+## v1 mode: list-only
+
+Advisor produces the opportunity list with the exact slash-command in each item's `Handoff` field. User reads, picks, runs the command manually.
+
+**Why list-only:** auto-invocation creates two problems early: (1) the user can't review the angle before the writer commits to it, and (2) if the writer needs clarifying input, the advisor isn't in the call to provide it. List-only keeps the human in the loop where judgment matters most — angle selection.
+
+Future v2: when the user picks an opportunity by number ("do #3"), advisor invokes the chosen writer with the brief.
+
+## Brief shape (per WRITER-CONVENTION.md §4)
+
+The slash-command serializes a brief object:
+
+| Field | Required | Where it comes from in advisor |
+|---|---|---|
+| `source_material` | yes | `--source memory:<uuid>` for ship-event / daily / weekly OR `--source doc:<id>` for OpenWriter draft OR `--source inline:"topic phrase"` as last resort |
+| `angle` | no but advisor always provides | `--angle "<phrase>"` derived from source content's first informative clause |
+| `sub_form` | yes | Positional arg per writer (`/x-writer thread`, `/blog-writer long`, `/newsletter-writer issue`) |
+| `venture` | yes when relevant | `--venture <slug>` matches the venture in `docs/ventures.md` |
+| `voice` | no | Defaults to venture's authors-voice profile; advisor doesn't override |
+
+## Per-writer command shape
+
+### `/x-writer`
+
+```
+/x-writer <sub_form> --source <ref> --venture <slug> --angle "<phrase>"
+```
+
+Sub-forms: `thread` | `single` | `article` | `comic` | `reply` | `quote`.
+
+Advisor picks sub-form by:
+- Source is a fresh ship-event with rich content → `thread` or `article`
+- Source is a pattern across 3+ dailies → `thread`
+- Source is a single sharp observation → `single`
+- Visual narrative or comparative → `comic`
+- `reply` / `quote` are out of scope for the advisor (those belong to `/x-strategy`)
+
+### `/blog-writer`
+
+```
+/blog-writer <sub_form> --source <ref> --venture <slug> --angle "<phrase>"
+```
+
+Sub-forms: `long` | `short` | `tutorial` | `announcement`.
+
+Advisor picks:
+- Source is a ship-event with code-level detail → `announcement` or `tutorial`
+- Source is a weekly through-line → `long`
+- Source is one focused topic → `short`
+
+### `/newsletter-writer`
+
+```
+/newsletter-writer <sub_form> --source <ref> --venture <slug> --angle "<phrase>"
+```
+
+Sub-forms: `issue` | `supplemental` | `archive`.
+
+Default for cadence-floor opportunities: `issue`. Use `supplemental` only when an issue already shipped this week but a hot ship-event landed after.
+
+## Return contract (what the writer reports back)
+
+Per WRITER-CONVENTION.md §5:
+
+```json
+{
+  "status": "draft-ready" | "needs-input" | "blocked",
+  "artifact": { "doc_id": "...", "workspace_id": "..." },
+  "next_steps": ["/polish", "/schedule", "/announce"],
+  "notes": "..."
+}
+```
+
+In v1 the advisor doesn't observe this directly (user invokes the writer themselves). When v2 lands, the advisor will pass `notes` back to the user verbatim and the suggested `next_steps` become the next round of advisor proposals.
+
+## What the advisor does NOT do
+
+- **Generate the slash-command on behalf of the user and run it.** v1 prints; user runs.
+- **Pick voice profile.** Default is venture's profile per `/authors-voice`.
+- **Schedule or polish.** Those are downstream skills (`/schedule`, `/polish`); writer's `next_steps` surfaces them; user chains.
+- **Fall back to inline-topic.** Always prefer `memory:<uuid>` or `doc:<id>`. Only use `inline:` for cadence-floor opportunities where no specific memory row drives the pitch.
+
+## Anti-patterns
+
+- Calling a writer for a venture not in `channels_per_venture` for that channel. Setup config guards this; if a venture has only `["x"]`, do not propose blog or newsletter opportunities for it.
+- Stuffing multiple ships into one brief. One brief = one source. If three ships cluster on a theme, that's a weekly-pattern opportunity, not a multi-source brief.
+- Inventing a sub-form not in the writer's enum. Per WRITER-CONVENTION.md §4: if a needed sub-form doesn't exist, that's a signal to propose adding it to the writer — don't improvise on the advisor side.

package/skill/content-advisor/docs/output-format.md

@@ -0,0 +1,89 @@
+# Output Format
+
+What the user sees when `/content-advisor` finishes. Plain English. Top-line first, then ranked list, then optional "consider later" tier.
+
+## Structure
+
+```
+# Content Advisor — <YYYY-MM-DD>
+
+**Top of the queue:** <one-sentence pitch for #1 with the venture and channel>
+
+## Act now (final_rank ≥ 6)
+
+### 1. <Channel> — <Venture> — <short angle>
+- **Why now:** <one sentence>
+- **Source:** <memory_id excerpt | doc_id title | "recombine: <topic>">
+- **Handoff:** `/<channel>-writer <sub_form> --source <source_ref> --venture <venture> --angle "<angle>"`
+
+### 2. ...
+
+## Consider later (final_rank 3–5)
+
+### N. ...
+
+## Notes
+
+- <warnings: missing focus.md, X data unavailable, fallback turns used for venture Y, etc.>
+- <ventures excluded as backburner>
+- <ships that triggered an opportunity already in flight as an OpenWriter draft — listed here so the user knows the system noticed>
+```
+
+## Per-entry fields (rendered, not raw JSON in v1)
+
+| Field | Source | Example |
+|---|---|---|
+| Channel | candidate.channel | `x: thread`, `blog: long`, `newsletter: issue` |
+| Venture | candidate.venture | `paybot`, `tournament-male`, `personal` |
+| Angle | derived from source content (first informative phrase) | "Upgrade-flow rebuild lessons" |
+| Why now | rule_triggered + tier | "Shipped 9d ago, no content yet · Tier 1 venture" |
+| Source | memory_id (preferred) / doc_id / "cadence-recombine" | `memory:7f3a...` |
+| Handoff | slash-command per WRITER-CONVENTION.md | `/x-writer thread --source memory:7f3a-... --venture paybot --angle "..."` |
+
+## Ranking display
+
+Items are numbered globally (1-N), not per-tier. The "Act now" / "Consider later" split is a cut on `final_rank ≥ 6`. Cap total at 10 items in v1.
+
+## When the list is empty
+
+```
+# Content Advisor — <date>
+
+No opportunities surfaced.
+
+This usually means one of:
+- All recent ships are already covered (good — you're caught up)
+- All channels are within their cadence floor (good — you're current)
+- GrepRAG has no recent activity (write something, ship something)
+
+Specific signal:
+- Ventures scanned: <N>
+- Ships in window: <N>
+- Open in-flight drafts: <N>
+- Channels within cadence: <list>
+```
+
+Empty is a valid state — surface why explicitly so the user knows the advisor ran cleanly.
+
+## When data is degraded
+
+Lead with a Notes block at the top before the queue, naming exactly what's missing:
+
+```
+**Degraded run** — operating with partial data:
+- focus.md missing → tier prioritization disabled
+- X recent posts unavailable → X cadence-floor rule skipped
+- Project `xyz` returned 5xx → excluded this pass
+```
+
+Then the list as normal. The user makes a judgment call on whether to act on a degraded ranking.
+
+## What we deliberately don't include in v1
+
+- Engagement predictions ("this will get N views")
+- Auto-scheduling slot picks
+- Image suggestions
+- Polishing scores
+- Multi-step plans ("first do A, then B, then C")
+
+The advisor proposes the next thing. The writer ships it. The user decides which one.

package/skill/content-advisor/docs/setup.md

@@ -0,0 +1,125 @@
+# Setup — First-Run Gateway
+
+The advisor's first invocation enters bootstrap. Setup runs once, written to a config file, then subsequent invocations skip directly to the standard protocol.
+
+## Portfolio root resolution
+
+Resolution order:
+
+1. Env var `CONTENT_ADVISOR_ROOT`
+2. Config file `~/.claude/content-advisor.json` with `{ "portfolio_root": "/abs/path" }`
+3. Marker file scan up the cwd tree — looks for `docs/ventures.md` and `docs/strategy/focus.md`
+4. Fallback default: `C:/orchestrator`
+5. None applicable → ask user, save to config
+
+The advisor never operates against an unresolved portfolio root.
+
+## Setup flow
+
+```
+/content-advisor (no config detected)
+  ↓
+[Step 1] Locate portfolio root
+  → default C:/orchestrator; confirm or override
+  → save to ~/.claude/content-advisor.json
+  ↓
+[Step 2] Check GrepRAG
+  → command -v greprag → exits 0?
+  → test -n "$GREPRAG_API_KEY"? (source ~/.env if missing)
+  → greprag discover --json → returns ≥1 project?
+  → any failure → walk user through /greprag setup
+  ↓
+[Step 3] Verify writer skills present
+  → ~/.claude/skills/x-writer/SKILL.md exists?
+  → ~/.claude/skills/blog-writer/SKILL.md exists?
+  → ~/.claude/skills/newsletter-writer/SKILL.md exists?
+  → any missing → "Run /skill-publish from C:/openwriter to install the writer masters."
+  ↓
+[Step 4] Read WRITER-CONVENTION.md
+  → C:/openwriter/skills/WRITER-CONVENTION.md (source of truth for handoff brief shape)
+  → if absent, advisor still works but warns the contract is unverified
+  ↓
+[Step 4.5] Per-venture ICP (Ideal Customer Profile) derivation
+  → For each venture in `project_to_venture`:
+    a) Search for an existing avatar / audience doc:
+       - OpenWriter workspaces with titles like "Audience", "Audience & Reader Journey", "Avatar", "ICP"
+       - The venture's marketing-site repo for `content/audience.md` or similar
+       - If found → store pointer in config under `icp_per_venture[venture]` as
+         `"openwriter:<docId>"` or `"file:<absolute-path>"`
+    b) If no doc exists, conduct a short interview (5-7 questions max):
+       - Who is the buyer? (one sentence)
+       - What's their current state? (the pain that brings them in)
+       - What do they pick up your content hoping for?
+       - What's the recognition shock they want? (their life mirrored back)
+       - What do they walk away with that's actionable this week?
+       - What's the failure mode of content that doesn't land?
+       - Optional: who do they trust today that you're competing with?
+    c) Write the interview output to `docs/icp/<venture>.md` in the portfolio
+       root and store the pointer in config.
+  → Per-venture ICP is the demand-side spec the advisor reads at rank time
+    (see Rule 5 in `decision-rules.md`).
+  ↓
+[Step 5] Verify portfolio docs
+  → docs/ventures.md, docs/strategy/focus.md present?
+  → each missing → "Run /business-advisor to scaffold portfolio docs."
+  ↓
+[Step 6] Project ↔ venture mapping
+  → greprag discover --json lists project names
+  → match each to a venture umbrella (often 1:1; some ventures span multiple repos)
+  → save to ~/.claude/content-advisor.json under `project_to_venture`
+  ↓
+[Step 7] Optional: per-venture cadence overrides
+  → defaults in docs/decision-rules.md (X daily, newsletter weekly, blog 2×/mo)
+  → user can override per venture in config under `cadence_overrides`
+  ↓
+[Step 8] Lock in
+  → run one full pass, present opportunity list as the first output
+  → confirm config persisted
+```
+
+## Config file format
+
+`~/.claude/content-advisor.json`:
+
+```json
+{
+  "portfolio_root": "C:/orchestrator",
+  "greprag_api_url": "https://api.greprag.com",
+  "project_to_venture": {
+    "openwriter": "openwriter",
+    "openwriter-site": "openwriter",
+    "openwriter-publish": "openwriter",
+    "paybot": "paybot",
+    "paybot-portal": "paybot",
+    "tournamentmale": "tournament-male",
+    "tm-book": "tournament-male",
+    "orchestrator": "personal"
+  },
+  "cadence_overrides": {
+    "openwriter": { "blog": "weekly" }
+  },
+  "icp_per_venture": {
+    "your-venture-here": "openwriter:doc_abc123",
+    "another-venture": "file:C:/path/to/portfolio/docs/icp/another-venture.md"
+  },
+  "channels_per_venture": {
+    "tournament-male": ["x", "newsletter", "blog"],
+    "paybot": ["x", "blog"],
+    "openwriter": ["x", "blog"],
+    "personal": ["x", "newsletter"]
+  }
+}
+```
+
+`channels_per_venture` is the gate that prevents the advisor from proposing a blog post for a venture that has no blog. Default behavior when a venture is missing from this map: assume all three channels eligible.
+
+## Re-running setup
+
+Delete `~/.claude/content-advisor.json` and re-invoke. Or invoke with "redo setup step N" to re-enter one sub-flow.
+
+## Failure modes
+
+- **GrepRAG unreachable** → advisor cannot run. Setup blocks. Source-farmer rule needs ship-events; nothing else compensates.
+- **Writer skills missing** → advisor still produces the list but flags handoff commands as unverified.
+- **Portfolio docs missing** → tier prioritization disabled (all opportunities treated equal). Surface a warning.
+- **No projects in greprag discover** → no source material. Advisor exits with "no episodic memory yet — write code, ship something, then check back."

package/skill/content-advisor/docs/writing-activity.md

@@ -0,0 +1,89 @@
+# Writing Activity
+
+The "what have we already written" stream. Pairs with episodic memory to drive the anti-duplication and cadence-floor rules.
+
+## What we want to know per channel per venture
+
+| Channel | The question | Source |
+|---|---|---|
+| X | When was the last post? What topics in last 7d? | x-strategy cache, or fxtwitter recent timeline |
+| Blog | When was the last post? What topics in last 30d? | git log on the venture's marketing-site repo + frontmatter scan |
+| Newsletter | When was the last issue sent? What was its through-line? | `mcp__openwriter__list_newsletter_issues` |
+| OpenWriter drafts | What's in flight right now (un-shipped drafts touched in last 14d)? | `mcp__openwriter__list_documents` filtered by recency |
+
+## Per-source procedure
+
+### OpenWriter drafts (in-flight)
+
+```
+list_workspaces → for each workspace:
+  list_documents → filter where updatedAt > now-14d AND not in trash
+  → for each doc: extract { id, title, workspace_name, updatedAt, tags }
+  → infer channel from workspace name conventions (blog/newsletter/x/scratch)
+    OR from tags if present
+  → infer venture from workspace name OR explicit metadata
+```
+
+These are CRUCIAL — an in-flight draft on topic X means "don't propose another piece on X." Surface them as "in progress" markers, not opportunities.
+
+### Newsletter sends
+
+```
+list_newsletter_issues → sort desc by sentAt → take top 4
+  → for each: { id, subject, sentAt, doc_id }
+  → most recent sentAt → "newsletter last sent N days ago"
+  → if N > cadence floor (default 7d): cadence-floor opportunity for newsletter
+```
+
+### Blog history
+
+For each venture with a marketing-site repo (path resolved via `project_to_venture` config + scanning `ventures.md` for repo paths):
+
+```
+git -C <repo> log --since="30 days ago" --name-only --pretty=format:'%h|%ci|%s'
+  → filter file changes to blog content paths (src/content/blog/**, content/posts/**, etc.)
+  → group commits by post file → { post_file, first_commit_date, latest_commit_date }
+  → most recent → "blog last shipped N days ago"
+```
+
+The blog-content path convention varies per site; try common patterns:
+- `src/content/blog/**` (Astro)
+- `content/posts/**` (Hugo)
+- `_posts/**` (Jekyll)
+- `app/blog/**/page.mdx` (Next.js)
+
+If no match, fall back to scanning frontmatter (`---\npubDate:`) in any `.md`/`.mdx` file modified in window.
+
+### X activity
+
+Three options, in preference order:
+
+1. **`/x-strategy` cache** — if present at a known path, parse the latest cached export.
+2. **`mcp__x__*` tools** — if the X MCP is connected, query recent tweets for @Meta_Trav.
+3. **fxtwitter timeline** — public, free; parse the user's recent posts.
+
+What we want: list of `{ posted_at, text, type: thread|single|article|comic, topic_inferred }`. Topic inference is best-effort — a 30-word excerpt is enough to dedupe against memory rows.
+
+## Output of this stream
+
+A per-venture-per-channel activity map:
+
+```json
+{
+  "tournament-male": {
+    "x":          { "last_at": "2026-05-24T...", "topics_7d": ["six-week challenge", "kettlebell program"] },
+    "newsletter": { "last_at": "2026-05-19T...", "subject": "Week of May 19" },
+    "blog":       { "last_at": "2026-04-30T...", "recent_topics": ["bible study cohort"] }
+  },
+  "paybot": {
+    "x":          { "last_at": "2026-05-23T...", "topics_7d": ["upgrade flow ship"] },
+    "blog":       { "last_at": "2026-05-10T...", "recent_topics": ["new pricing"] }
+  }
+}
+```
+
+Plus a separate "in-flight drafts" list across all ventures (the OpenWriter list_documents output, filtered by recency).
+
+## Failure tolerance
+
+Any one of these sources can be down without breaking the advisor — they're enrichment. The minimum viable run is: greprag memory + ventures.md + focus.md. Everything else just sharpens ranking.