@aksp/opencrew 1.2.2 → 1.3.0

package/templates/_opencrew/core/prompts/repair.prompt.md

@@ -1,119 +1,119 @@
-# Repair — Fix Crew Agent Names / Manifest
-
-You are the opencrew Repair agent. Your job is to fix an **already-created** crew whose
-agents show their function/role but not their persona names (e.g. the dashboard and the
-Pipeline Runner announce "Pesquisador" instead of "Pedro Pesquisa").
-
-This is a known defect in crews built by older versions: the `crew-party.csv` manifest was
-generated without a `displayName` column (or with the role/title in it instead of the
-persona name), while the correct two-word names already live in each agent's `.agent.md`
-`name:` frontmatter. This repair is **deterministic** — you pull names from the `.agent.md`
-files and rewrite the manifest. You do NOT re-generate agent personas, re-run research, or
-re-run the Build phase.
-
-## Scope
-
-You may ONLY touch files under `crews/{code}/`:
-- `crews/{code}/crew-party.csv`
-- `crews/{code}/agents/*.agent.md` (only in the fallback case — see Step 4)
-- `crews/{code}/state.json` (only if it exists)
-
-Never modify `_opencrew/`, `templates/`, or any other crew. Use the Write tool for all file
-writes (never Bash `mkdir`).
-
----
-
-## Step 1: Identify the crew
-
-- If the user passed a crew code (`/opencrew repair <name>`), use it.
-- Otherwise, list the directories under `crews/` and ask which crew to repair.
-  - If exactly 1 crew exists, offer it plus a "Cancel" option.
-  - If 0 crews exist, tell the user there is nothing to repair and stop.
-
-Verify `crews/{code}/crew.yaml` and `crews/{code}/agents/` exist. If not, report and stop.
-
-## Step 2: Read the source of truth (the agent files)
-
-For EACH `crews/{code}/agents/*.agent.md`, read the YAML frontmatter and extract:
-- `id` (or derive it from the filename: `researcher.agent.md` → `researcher`)
-- `name` — the persona name (expected: two words, "FirstName LastName")
-- `title` — the role/function label
-- `icon` — the emoji
-- `execution` — `inline` or `subagent`
-
-Also read the current `crews/{code}/crew-party.csv` (if present) to preserve any
-`execution`/`title` values that are correct there but missing from a `.agent.md`.
-
-## Step 3: Rebuild `crew-party.csv`
-
-Write `crews/{code}/crew-party.csv` with the canonical header and one row per agent:
-
-```
-id,displayName,title,icon,path,execution
-```
-
-- `displayName` = the agent's `name:` from its `.agent.md` (the two-word persona name).
-- `title` = the agent's `title:`.
-- `icon` = the agent's `icon:`.
-- `path` = `./agents/{id}.agent.md`.
-- `execution` = the agent's `execution:` (default `inline` if absent).
-- Quote any field containing a space or comma with double quotes.
-- Preserve the original agent order (match the previous CSV order if it existed).
-
-## Step 4: Fallback — agent whose `.agent.md` name is itself broken
-
-If an agent's `.agent.md` `name:` is empty or has only ONE word, the persona name never
-existed and must be generated now, following the **Agent Naming Convention** from
-`_opencrew/core/prompts/design.prompt.md`:
-
-1. Read the user's Output Language from `_opencrew/_memory/preferences.md`.
-2. Generate a two-word name: "FirstName LastName" — both words start with the SAME letter
-   (alliteration); the first name is common in the user's language; the last name is a
-   playful reference to the agent's function (from its `title:`). Each agent in the crew
-   must use a DIFFERENT initial letter.
-3. Update BOTH the `.agent.md` `name:` frontmatter AND the `# {Name}` heading in that file.
-4. Use the new name as the `displayName` in the rebuilt CSV.
-
-Only do this for agents that are actually broken. Agents that already have a valid two-word
-`name:` are left untouched (only the CSV is rewritten to carry it).
-
-## Step 5: Refresh `state.json` (only if it exists)
-
-If `crews/{code}/state.json` exists, update each agent entry's `name` field to the repaired
-`displayName`. Do not change any other field. If the file does not exist, skip — the
-Pipeline Runner recreates it from the CSV on the next run.
-
-## Step 6: Report
-
-Present a summary table of what changed:
-
-```
-Crew "{name}" repaired.
-
-| Agent id    | Before        | After            | Source        |
-|-------------|---------------|------------------|---------------|
-| researcher  | (role only)   | 🔎 Pedro Pesquisa | .agent.md     |
-| copywriter  | Guilherme     | ✍️ Guilherme Gancho | generated   |
-
-crew-party.csv: rewritten with displayName column
-state.json: {updated | not present}
-
-Run it: /opencrew run {code}
-```
-
-If nothing was broken (CSV already had a valid `displayName` for every agent), say so
-plainly instead of inventing changes: "This crew's manifest is already correct — no repair
-needed."
-
----
-
-## Rules
-
-- **DO** pull names from `.agent.md` `name:` — that is the source of truth.
-- **DO** rewrite the whole `crew-party.csv` with the canonical header.
-- **DO** limit persona generation to agents whose own `.agent.md` name is missing/one-word.
-- **DO NOT** re-run Discovery, Design, Build, research, or investigations.
-- **DO NOT** modify agent personas, principles, or any section other than the `name:` line
-  and `# {Name}` heading (and only in the fallback case).
-- **DO NOT** touch any file outside `crews/{code}/`.
-- **DO NOT** fabricate a summary — report only what you actually changed.
+# Repair — Fix Crew Agent Names / Manifest
+
+You are the opencrew Repair agent. Your job is to fix an **already-created** crew whose
+agents show their function/role but not their persona names (e.g. the dashboard and the
+Pipeline Runner announce "Pesquisador" instead of "Pedro Pesquisa").
+
+This is a known defect in crews built by older versions: the `crew-party.csv` manifest was
+generated without a `displayName` column (or with the role/title in it instead of the
+persona name), while the correct two-word names already live in each agent's `.agent.md`
+`name:` frontmatter. This repair is **deterministic** — you pull names from the `.agent.md`
+files and rewrite the manifest. You do NOT re-generate agent personas, re-run research, or
+re-run the Build phase.
+
+## Scope
+
+You may ONLY touch files under `crews/{code}/`:
+- `crews/{code}/crew-party.csv`
+- `crews/{code}/agents/*.agent.md` (only in the fallback case — see Step 4)
+- `crews/{code}/state.json` (only if it exists)
+
+Never modify `_opencrew/`, `templates/`, or any other crew. Use the Write tool for all file
+writes (never Bash `mkdir`).
+
+---
+
+## Step 1: Identify the crew
+
+- If the user passed a crew code (`/opencrew repair <name>`), use it.
+- Otherwise, list the directories under `crews/` and ask which crew to repair.
+  - If exactly 1 crew exists, offer it plus a "Cancel" option.
+  - If 0 crews exist, tell the user there is nothing to repair and stop.
+
+Verify `crews/{code}/crew.yaml` and `crews/{code}/agents/` exist. If not, report and stop.
+
+## Step 2: Read the source of truth (the agent files)
+
+For EACH `crews/{code}/agents/*.agent.md`, read the YAML frontmatter and extract:
+- `id` (or derive it from the filename: `researcher.agent.md` → `researcher`)
+- `name` — the persona name (expected: two words, "FirstName LastName")
+- `title` — the role/function label
+- `icon` — the emoji
+- `execution` — `inline` or `subagent`
+
+Also read the current `crews/{code}/crew-party.csv` (if present) to preserve any
+`execution`/`title` values that are correct there but missing from a `.agent.md`.
+
+## Step 3: Rebuild `crew-party.csv`
+
+Write `crews/{code}/crew-party.csv` with the canonical header and one row per agent:
+
+```
+id,displayName,title,icon,path,execution
+```
+
+- `displayName` = the agent's `name:` from its `.agent.md` (the two-word persona name).
+- `title` = the agent's `title:`.
+- `icon` = the agent's `icon:`.
+- `path` = `./agents/{id}.agent.md`.
+- `execution` = the agent's `execution:` (default `inline` if absent).
+- Quote any field containing a space or comma with double quotes.
+- Preserve the original agent order (match the previous CSV order if it existed).
+
+## Step 4: Fallback — agent whose `.agent.md` name is itself broken
+
+If an agent's `.agent.md` `name:` is empty or has only ONE word, the persona name never
+existed and must be generated now, following the **Agent Naming Convention** from
+`_opencrew/core/prompts/design.prompt.md`:
+
+1. Read the user's Output Language from `_opencrew/_memory/preferences.md`.
+2. Generate a two-word name: "FirstName LastName" — both words start with the SAME letter
+   (alliteration); the first name is common in the user's language; the last name is a
+   playful reference to the agent's function (from its `title:`). Each agent in the crew
+   must use a DIFFERENT initial letter.
+3. Update BOTH the `.agent.md` `name:` frontmatter AND the `# {Name}` heading in that file.
+4. Use the new name as the `displayName` in the rebuilt CSV.
+
+Only do this for agents that are actually broken. Agents that already have a valid two-word
+`name:` are left untouched (only the CSV is rewritten to carry it).
+
+## Step 5: Refresh `state.json` (only if it exists)
+
+If `crews/{code}/state.json` exists, update each agent entry's `name` field to the repaired
+`displayName`. Do not change any other field. If the file does not exist, skip — the
+Pipeline Runner recreates it from the CSV on the next run.
+
+## Step 6: Report
+
+Present a summary table of what changed:
+
+```
+Crew "{name}" repaired.
+
+| Agent id    | Before        | After            | Source        |
+|-------------|---------------|------------------|---------------|
+| researcher  | (role only)   | 🔎 Pedro Pesquisa | .agent.md     |
+| copywriter  | Guilherme     | ✍️ Guilherme Gancho | generated   |
+
+crew-party.csv: rewritten with displayName column
+state.json: {updated | not present}
+
+Run it: /opencrew run {code}
+```
+
+If nothing was broken (CSV already had a valid `displayName` for every agent), say so
+plainly instead of inventing changes: "This crew's manifest is already correct — no repair
+needed."
+
+---
+
+## Rules
+
+- **DO** pull names from `.agent.md` `name:` — that is the source of truth.
+- **DO** rewrite the whole `crew-party.csv` with the canonical header.
+- **DO** limit persona generation to agents whose own `.agent.md` name is missing/one-word.
+- **DO NOT** re-run Discovery, Design, Build, research, or investigations.
+- **DO NOT** modify agent personas, principles, or any section other than the `name:` line
+  and `# {Name}` heading (and only in the fallback case).
+- **DO NOT** touch any file outside `crews/{code}/`.
+- **DO NOT** fabricate a summary — report only what you actually changed.

package/templates/_opencrew/core/prompts/sherlock-seo.md

@@ -0,0 +1,216 @@
+# Sherlock — SEO / Keywords Extractor
+
+Load `sherlock-shared.md` before using this extractor.
+
+This file contains the SEO and keyword research extraction process. The Architect loads this file (alongside `sherlock-shared.md`) when the investigation requires search trend analysis, keyword discovery, or content-gap identification.
+
+This extractor uses `web_search` native tool — no browser automation needed. For Google Trends data specifically, it fetches trend pages; for keyword volume estimation, it searches for public keyword data and industry reports.
+
+---
+
+## When to Use
+
+The Architect dispatches Sherlock-SEO when:
+
+- The crew's purpose involves content marketing, SEO, or organic growth
+- The briefing mentions search visibility, keyword targeting, or content optimization
+- The crew needs to understand what people are searching for in a given domain
+- The user wants data-driven content planning (not just creative intuition)
+- A content crew needs topic clusters and keyword maps for editorial planning
+
+---
+
+## Extraction Process
+
+### Step 1: Keyword Discovery
+
+Based on the crew's domain (from `discovery.yaml`), generate seed keywords and expand:
+
+1. **Seed keywords** — Extract from crew briefing: what product/service/topic is the content about?
+   - Example: crew for "SaaS onboarding" → seeds: "user onboarding", "SaaS retention", "product adoption"
+
+2. **Search expansion** — For each seed, run `web_search` with discovery queries:
+   - `"{seed}" related topics`
+   - `"{seed}" trends 2026`
+   - `"{seed}" questions people ask`
+   - `"what is {seed}"` (triggers "People Also Ask" results)
+
+3. **Collect related terms** — From search results, extract:
+   - Related keywords mentioned in titles and meta descriptions
+   - Question patterns (how to X, why is Y, what is Z)
+   - Long-tail variations (specific, multi-word phrases)
+
+### Step 2: Search Intent Analysis
+
+For the top 5-8 keywords discovered, classify search intent:
+
+| Keyword | Intent | Volume Signal | Competition Signal |
+|---------|--------|---------------|-------------------|
+| "{keyword}" | Informational | High — appears in multiple sources | Medium — 3 competitors targeting it |
+| "{keyword}" | Commercial | Medium | High — 8+ competitors |
+| "{keyword}" | Transactional | Low | Low — underserved |
+
+**Intent types:**
+- **Informational**: User wants to learn something ("how to", "what is", "guide")
+- **Commercial**: User is comparing options ("best", "vs", "review")
+- **Transactional**: User wants to take action ("buy", "sign up", "download", "pricing")
+- **Navigational**: User wants to find a specific site/brand
+
+### Step 3: Content Gap Analysis
+
+Identify topics with high search interest but weak existing content:
+
+1. **Search for major topics** in the domain: `"{topic}" guide` and `"{topic}" best practices`
+2. **Assess top results** — are they comprehensive? recent? well-structured?
+3. **Identify gaps**:
+   - Topics with only thin/outdated content (opportunity: create the definitive guide)
+   - Topics with content but no clear structure (opportunity: create the framework)
+   - Topics with content but no visual/examples (opportunity: create the visual guide)
+   - Questions with no single authoritative answer (opportunity: own the answer)
+
+### Step 4: Trend Detection
+
+Search for signals that indicate rising or falling interest:
+
+1. **Rising trends** — `"{domain}" growing trend` or `"{domain}" 2026 predictions`
+2. **Seasonal patterns** — `"{domain}" {month}` or `"when do people search for {domain}"`
+3. **Technology shifts** — `"{domain}" AI` or `"{domain}" automation` (what's changing the field)
+4. **Platform migration** — `"{domain}" moving from X to Y` (where is the audience going)
+
+### Step 5: Competitive Keyword Landscape
+
+When the crew has identified competitors (from discovery or web research):
+
+1. Search for competitor content: `site:{competitor.com} {topic}`
+2. Identify keywords they rank for (visible from search result snippets)
+3. Find keywords they DON'T target → these are the crew's opportunities
+4. Map their content structure: what formats do they use? how deep do they go?
+
+---
+
+## Output
+
+### `raw-content.md`
+
+```markdown
+# Raw Content: SEO Research — {domain/topic}
+
+Investigated: {YYYY-MM-DD}
+Seed keywords: {list}
+Keywords discovered: {N total}
+Search engines used: web_search (native)
+
+---
+
+## Keyword Map
+
+### Primary Keywords (high volume, high relevance)
+| Keyword | Intent | Volume Signal | Competition | Opportunity Score |
+|---------|--------|---------------|-------------|-------------------|
+| {keyword} | {intent type} | {high/medium/low} | {high/medium/low} | {★-★★★★★} |
+
+### Long-Tail Keywords
+| Keyword | Intent | Notes |
+|---------|--------|-------|
+| {long-tail phrase} | {intent type} | {why this matters} |
+
+### Question Keywords
+| Question | Search Context | Content Opportunity |
+|----------|---------------|-------------------|
+| "{question}?" | {when would someone search this} | {what content would answer it} |
+
+---
+
+## Content Gap Analysis
+
+### Underserved Topics
+1. **{topic}**: Current coverage is {thin/outdated/nonexistent}. Top results: {URLs}. Gap: {description}.
+2. **{topic}**: Current coverage is {thin/outdated/nonexistent}. Top results: {URLs}. Gap: {description}.
+
+### Over-Served Topics (avoid or differentiate)
+1. **{topic}**: {N} strong results already. To compete: {what unique angle would be needed}.
+
+---
+
+## Trend Signals
+
+| Trend | Direction | Evidence | Relevance to Crew |
+|-------|-----------|----------|-------------------|
+| {trend name} | ↗️ Rising / ↘️ Declining / → Stable | {source or signal} | {why this matters for the crew} |
+```
+
+### `pattern-analysis.md`
+
+```markdown
+# Pattern Analysis: SEO Research — {domain/topic}
+
+Analyzed: {YYYY-MM-DD}
+Keywords analyzed: {N}
+Content gaps identified: {N}
+Trends detected: {N}
+
+## Executive Summary
+{3-5 sentences on the search landscape — what people are looking for, what's
+missing, and where the crew should focus}
+
+## Search Demand Pattern
+- Total addressable search volume: {estimate — high/medium/low}
+- Intent distribution: {X}% informational, {Y}% commercial, {Z}% transactional
+- Seasonality: {present/absent, with patterns if any}
+- Trend direction: {rising/stable/declining} for core topics
+
+## Content Opportunity Matrix
+
+| Topic | Demand | Current Supply | Opportunity |
+|-------|--------|---------------|-------------|
+| {topic} | High | Weak | 🔴 Build now — own this space |
+| {topic} | High | Strong | 🟡 Differentiate with unique angle |
+| {topic} | Medium | Weak | 🟢 Good supplemental content |
+| {topic} | Low | Strong | ⚪ Skip |
+
+## Keyword-to-Content Mapping
+
+For each primary keyword, the recommended content format:
+
+1. **"{keyword}"** → {blog post / guide / comparison / tool / landing page}
+   - Angle: {suggested angle}
+   - Supporting keywords: {related terms to include}
+   - Estimated depth: {word count or scope}
+
+2. **"{keyword}"** → {format}
+   - Angle: {suggested angle}
+   - Supporting keywords: {related terms}
+   - Estimated depth: {word count or scope}
+
+## Recommendations for Crew
+
+Five SEO-informed content recommendations:
+
+1. **[Recommendation]**: {Details — what to create, why, expected impact}
+2. **[Recommendation]**: {Details}
+3. **[Recommendation]**: {Details}
+4. **[Recommendation]**: {Details}
+5. **[Recommendation]**: {Details}
+```
+
+---
+
+## Smart Recommendations
+
+- **Blog/SEO crews**: Full extraction — keyword map + content gaps + competitive landscape. 10+ keywords.
+- **Social media crews**: Light extraction — trending topics and question patterns only. Skip competitive keyword analysis.
+- **Strategy crews**: Focus on content gaps and trend signals. Use as input for editorial planning.
+- **General crews**: Top 5 keywords + main content gaps only. Keep it focused.
+
+## Limitations
+
+- This extractor uses `web_search`, not direct API access to Google Trends, SEMrush, or Ahrefs. Volume and competition signals are estimates based on visible search result patterns — they are directional, not precise.
+- For exact search volumes, the user would need API access to a keyword tool (can be added as a skill later).
+- Google Trends data is fetched from publicly visible trend pages — availability varies by region and topic.
+
+## Timeout and Error Handling
+
+- Maximum time: 15 minutes
+- If a keyword returns no useful results, mark as "insufficient data" and move on
+- If trend data is unavailable for a topic, note the gap
+- **Never fabricate search volumes or trend data.**

package/templates/_opencrew/core/prompts/sherlock-shared.md

@@ -31,6 +31,66 @@ This notice is mandatory for every investigation run, even if sessions already e
 
 ---
 
+## Multi-Source Orchestration
+
+Sherlock is not a single agent — it's an orchestration layer that dispatches specialized extractors based on the crew's domain and research needs. The Architect decides which sources to activate before launching any subagents.
+
+### Available Sources
+
+| Source | Extractor File | Method | Best For |
+|--------|---------------|--------|----------|
+| **Social** | `sherlock-instagram.md`, `sherlock-linkedin.md`, `sherlock-twitter.md`, `sherlock-youtube.md` | Browser automation (Playwright) | Reference profiles, content style analysis, competitor social audit |
+| **Web** | `sherlock-web.md` | `web_search` + `web_fetch` (native) | Industry research, competitive analysis, blog/news content, technical docs |
+| **SEO** | `sherlock-seo.md` | `web_search` (native) | Keyword discovery, content gap analysis, search intent mapping, trend volume |
+| **Trends** | `sherlock-trends.md` | `web_search` + `web_fetch` (native) | Trending topics, cultural moments, viral patterns, audience conversations |
+
+### Source Selection Logic
+
+The Architect selects sources based on the crew's purpose and domains (from `discovery.yaml`):
+
+| Crew Type | Sources to Activate | Rationale |
+|-----------|-------------------|-----------|
+| **Social media content** (Instagram, LinkedIn, Twitter, YouTube) | Social + Trends | Reference profiles for style + trending topics for relevance |
+| **Blog / SEO content** | Web + SEO + Trends | Web for research depth, SEO for keyword targeting, Trends for timeliness |
+| **News / current events** | Web + Trends | Web for source material, Trends for what's breaking now |
+| **Product launch / marketing** | Web + SEO + Trends | Web for competitive intel, SEO for positioning, Trends for cultural timing |
+| **Technical / documentation** | Web | Web research is sufficient — SEO and Trends add noise for technical content |
+| **Strategy / consulting** | Social + Web + Trends | Full spectrum: what competitors do (Social), what the market says (Web), what's changing (Trends) |
+| **General / unspecified** | Web | Default to web — broadest coverage, no browser setup needed |
+
+### Dispatch Rules
+
+1. **Social sources require user-provided URLs** — only activate `sherlock-social` extractors when the user gave reference profile URLs during discovery. Never search for social profiles speculatively.
+
+2. **All other sources can be activated automatically** — the Architect decides which extractors to dispatch based on the crew's domains. No user input needed beyond the initial crew briefing.
+
+3. **Subagents run in parallel** — all activated extractors dispatch simultaneously as background subagents. Social extractors each get ONE subagent per profile URL. Web, SEO, and Trends get ONE subagent each (they handle multiple queries internally).
+
+4. **Native tools only for non-social extractors** — Web, SEO, and Trends extractors use `web_search` and `web_fetch` native tools. They do NOT need Playwright, sessions, or browser automation. This makes them faster and more reliable than social extractors.
+
+5. **Minimum viable dispatch** — at least one source must be activated. If the user provided no social URLs and the crew has no research domain, default to Web extractor.
+
+### Cross-Source Deduplication
+
+When multiple extractors find the same content or insight:
+
+1. **Same URL found by Web + SEO** → Web extractor's deep analysis takes priority. SEO extractor references it for keyword data only.
+2. **Same trend found by Trends + Social** → Trends extractor's analysis takes priority (broader context). Social extractor provides the concrete example.
+3. **Same competitor found by Web + Social** → Social extractor's pattern analysis takes priority (real content). Web extractor provides market positioning context.
+4. **The consolidated analysis explicitly calls out** which findings come from which source, using the format: `[Source: {extractor} — {detail}]`
+
+### Consolidated Analysis Enrichment
+
+When multiple sources are activated, the consolidated analysis gains additional dimensions:
+
+- **Cross-source validation**: Findings confirmed by 2+ sources carry more weight
+- **Source-specific patterns**: Social reveals execution patterns; Web reveals market positioning; SEO reveals demand signals; Trends reveals timing opportunities
+- **Contradictions**: When sources disagree (e.g., Social shows competitors doing X, but SEO shows no one searches for X), flag as a strategic insight — the crew may have found a gap or a trap
+
+These enrichments are applied during the Design phase when the Architect produces `consolidated-analysis.md`.
+
+---
+
 ## Browser Automation
 
 Sherlock uses Playwright CLI for browser automation. Use `npx playwright` commands to:
@@ -626,8 +686,20 @@ Sherlock detects the platform from the URL to apply the correct extractor:
 | `youtube.com` or `youtu.be` | YouTube | `sherlock-youtube.md` |
 | `x.com` or `twitter.com` | Twitter/X | `sherlock-twitter.md` |
 | `linkedin.com` | LinkedIn | `sherlock-linkedin.md` |
+| Any other URL | Web | `sherlock-web.md` |
+
+If the URL does not match any social platform, it is routed to the Web extractor — no platform-specific logic applies.
+
+### Non-URL Sources
+
+Sherlock also activates extractors that do NOT require user-provided URLs:
+
+| Source | Activated By | Extractor File |
+|--------|-------------|----------------|
+| SEO / Keywords | Crew domain involves content marketing, SEO, or organic growth | `sherlock-seo.md` |
+| Trends / Culture | Crew domain involves social media, news, or current-events content | `sherlock-trends.md` |
 
-If the URL does not match any known pattern, inform the user: "I don't recognize this platform. Supported platforms: Instagram, YouTube, Twitter/X, LinkedIn."
+These extractors are dispatched automatically by the Architect based on the crew type — see Multi-Source Orchestration above for the full selection matrix.
 
 ### Configuration Prompts