myaidev-method 0.3.4 → 0.3.5

package/skills/myai-content-ideation/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: myai-content-ideation
+description: Researches a topic area, discovers strategic Themes, and creates ideation briefs and article plans. Internal agent — dispatched by content-writer and production-coordinator.
+user-invocable: false
+allowed-tools: [Read, Write, WebSearch, WebFetch, Glob, Bash]
+---
+
+# Content Ideation + Planning
+
+Given a topic (or a broad area), audience, and content type, discover **Themes**, research supporting material, and produce four outputs:
+
+1. `content-themes.json` - persistent file of discovered Themes (appended across runs)
+2. `.content-session/ideation.md` - per-session ideation brief for the next pipeline phase
+3. `.content-session/plan.md` - actionable article structure and keyword placement plan for the writer
+4. `content-queue/{jobDir}/` - content stubs (one per Theme) ready for the production coordinator
+
+## What Is a Theme?
+
+A **Theme** is a strategic content grouping: a title, a description, and reference URLs that demonstrate the kind of content belonging to it. Themes ensure content variety, strategic coverage, and topical authority.
+
+A Theme contains exactly four fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Short, descriptive name for the editorial grouping |
+| `description` | string | 1-3 sentences explaining the angle, why it matters, and who it is for |
+| `strategy` | string | The ideation approach used to develop content under this Theme (see **Strategies** below) |
+| `referenceUrls` | string[] | 2-5 URLs of existing published content (yours or competitors') that exemplify this Theme |
+
+### Strategies
+
+A strategy is the ideation lens through which a Theme's content is approached. When discovering Themes, propose a strategy for each one. During interactive sessions, discuss strategy options with the user to find the best fit for the topic and audience.
+
+| Strategy | When to use |
+|----------|-------------|
+| **Gap Analysis** | There is a clear gap in existing coverage — missing subtopics, unanswered questions, or underserved audiences that your content can fill |
+| **Current Trends** | The topic intersects with recent developments, emerging technology, industry shifts, or timely events worth capitalizing on |
+| **Related Subject** | The core topic connects to an adjacent domain; bridging the two creates unique cross-disciplinary value |
+| **Hub and Spoke** | The Theme is broad enough to warrant a pillar piece with multiple supporting articles linking back to it for topical authority |
+| **Unique Angle** | You have proprietary data, original research, contrarian takes, or first-hand experience that no competitor can replicate |
+| **Venn Diagram** | Two or more distinct audiences or subject areas overlap; the content targets the intersection to capture a niche |
+
+These are starting points — new strategies can emerge during ideation. If a Theme doesn't fit neatly into one, propose and name a new strategy with a short rationale.
+
+Example:
+
+```json
+{
+  "title": "Big Data on Bare Metal",
+  "description": "Articles exploring how big data workloads like OLAP, stream processing, and high-volume data collection benefit from dedicated bare metal infrastructure versus shared cloud environments.",
+  "strategy": "Gap Analysis",
+  "referenceUrls": [
+    "https://example.com/olap-databases-bare-metal-dedicated-servers",
+    "https://example.com/single-tenant-private-cloud-high-volume-data-collection",
+    "https://example.com/real-time-data-processing-apache-storm-flink"
+  ]
+}
+```
+
+Themes are **not** article outlines. They are a strategic grouping that multiple articles can be written under.
+
+## Process
+
+1. **Parse the Brief**: Extract topic, audience, and content type from the task prompt
+2. **Search**: Use `WebSearch` to find 5-10 authoritative, recent sources on the topic area (prioritize last 12 months)
+3. **Discover Themes**: Identify 2-4 distinct Themes by grouping findings into strategic angles; collect reference URLs for each Theme
+4. **Write Themes**: Save Themes. If the task prompt specifies a path (e.g. `.content-session/{slug}/themes.json`), write there — no merge, coordinator will merge after batch. Otherwise write to `content-themes.json` at project root; if it exists, read and merge (add new Themes, skip duplicates by title, update URLs for existing Themes)
+5. **Write Content Stubs**: For each Theme, generate a content stub markdown file and write it to `content-queue/{jobDir}/` (see Output 4 below)
+6. **Research Selected Theme**: Do deeper research on the most promising Theme (or user-specified one)
+7. **Write ideation brief**: Save per-session research to `.content-session/ideation.md`
+8. **Create article plan**: Use ideation findings to create a detailed structure in `.content-session/plan.md`
+
+## Output 1: Themes (content-themes.json or task-specified path)
+
+Default path: `content-themes.json` at project root. In batch mode, the coordinator may specify `.content-session/{slug}/themes.json` to avoid race conditions.
+
+```json
+{
+  "lastUpdated": "{YYYY-MM-DD}",
+  "themes": [
+    {
+      "title": "{Theme title}",
+      "description": "{1-3 sentence description of the angle and audience}",
+      "strategy": "{Gap Analysis | Current Trends | Related Subject | Hub and Spoke | Unique Angle | Venn Diagram | custom}",
+      "referenceUrls": [
+        "{url1}",
+        "{url2}",
+        "{url3}"
+      ]
+    }
+  ]
+}
+```
+
+### Merge Rules (only when writing to content-themes.json)
+
+When writing to `content-themes.json` and it already exists:
+- Read the existing file first
+- Add new Themes (no existing Theme has the same or very similar title)
+- For existing Themes, append newly found reference URLs (no duplicates)
+- Update `lastUpdated` to today's date
+- Preserve all existing Themes; never remove them
+
+## Output 2: `.content-session/ideation.md`
+
+Per-session ideation brief consumed by planner/writer phases:
+
+```markdown
+# Ideation: {topic}
+
+## Selected Theme
+**{Theme title}** - {Theme description}
+**Strategy**: {strategy} — [1 sentence explaining why this strategy fits]
+
+## Key Facts & Statistics
+- [Fact 1] - Source: [attribution + URL]
+- [Fact 2] - Source: [attribution + URL]
+
+## Expert Perspectives
+- [Expert/Org]: "[Quote or paraphrased insight]" - [Context]
+
+## Content Gaps
+- [Gap 1] - Why it matters
+- [Gap 2] - Why it matters
+
+## Current Landscape
+[2-3 paragraph summary of what is currently known/published in this Theme area]
+
+## Trends & Recent Developments
+- [Trend 1] - [Date/Timeframe]
+- [Trend 2] - [Date/Timeframe]
+
+## Recommended Article
+**{Title idea}** - [1-2 paragraph recommendation for the best article to write within this Theme, given audience, existing coverage, and available unique value. Explain the angle and why it is high-value.]
+
+## Sources
+1. [Title] - [URL] - [Relevance note]
+2. ...
+```
+
+## Output 4: Content Stubs (`content-queue/{jobDir}/`)
+
+After discovering Themes, generate a content stub for each Theme. Stubs are markdown files with frontmatter that the content-production-coordinator consumes in batch mode.
+
+### Job Directory
+
+Create a job directory inside `content-queue/` named with a date and sequential counter:
+
+```
+content-queue/jobYYYYMMDD_NN/
+```
+
+Where `NN` is a zero-padded sequential number starting at `01`. If `content-queue/` already contains a directory for today's date (e.g. `job20260223_01`), increment the counter (e.g. `job20260223_02`).
+
+Example: `content-queue/job20260223_01/`
+
+If the task prompt specifies a job directory path, use that instead.
+
+### Stub Files
+
+Each stub is named with a URL-friendly slug derived from the Theme title:
+
+```
+content-queue/job20260223_01/kubernetes_application_performance.md
+content-queue/job20260223_01/big_data_on_bare_metal.md
+```
+
+Slug rules: lowercase, replace spaces and hyphens with underscores, strip non-alphanumeric characters (except underscores), collapse multiple underscores.
+
+### Stub Format
+
+Each stub contains frontmatter describing the content piece. The `strategy` field comes from the Theme (not "theme"). All other fields use values from the task prompt or sensible defaults:
+
+```markdown
+---
+title: "{Theme title — used as the article topic}"
+mode: new
+content_type: blog-post
+status: pending
+priority: normal
+tone: professional
+word_count: 1500
+audience: "{audience from task prompt}"
+strategy: "{Theme strategy — e.g. Gap Analysis, Current Trends}"
+keywords:
+  - "{primary keyword derived from Theme}"
+  - "{secondary keyword}"
+references:
+  - "{referenceUrl1 from Theme}"
+  - "{referenceUrl2 from Theme}"
+goals:
+  - "{1-sentence goal derived from Theme description}"
+visuals: true
+publish: wordpress
+publish_status: draft
+---
+
+## Theme Context
+
+{Theme description — 1-3 sentences explaining the angle, why it matters, and who it is for}
+
+## Reference Material
+
+{Bullet list of reference URLs with brief annotation of what each covers}
+```
+
+Field mapping from Theme to stub:
+
+| Theme Field | Stub Field | Notes |
+|-------------|------------|-------|
+| `title` | `title` | Used as the article topic |
+| `strategy` | `strategy` | Ideation strategy, NOT placed in a "theme" field |
+| `referenceUrls` | `references` | Carried over as-is |
+| `description` | Body: Theme Context | Placed in the markdown body, not frontmatter |
+
+Override defaults with values from the task prompt when available (e.g. `audience`, `tone`, `word_count`, `content_type`, `publish`, `publish_status`).
+
+## Constraints
+
+- Do not write the full article draft
+- Keep Output 2 under 1000 words
+- Every fact must include source attribution
+- Include at least one contrarian or alternative viewpoint
+- Identify at least 2 genuine content gaps
+- Produce at least 2 Themes in `content-themes.json`, ideally 3-4
+- Ensure Themes are meaningfully different from each other
+- Reference URLs must be real, publicly accessible URLs found during research
+- Every Theme must have a corresponding stub in the job directory
+
+## Output 3: `.content-session/plan.md`
+
+After ideation, create the article plan using this template:
+
+```markdown
+# Article Plan
+
+## Title Options
+1. **[Recommended Title]** <- Primary choice
+2. [Alternative 1]
+3. [Alternative 2]
+
+## Article Brief
+- **Type**: {content_type}
+- **Target Words**: {word_count}
+- **Tone**: {tone}
+- **Theme**: {Theme title}
+- **Strategy**: {strategy}
+- **Primary Keyword**: {keyword}
+- **Secondary Keywords**: {keyword2, keyword3}
+
+## Structure
+
+### Introduction (~{X} words)
+- **Hook Strategy**: [Specific hook approach]
+- **Hook Content**: [The actual hook sentence/concept]
+- **Bridge**: [How to connect hook to article topic]
+- **Promise**: [What the reader will learn/gain]
+- **Keywords**: Use primary keyword in first paragraph
+
+### {Section 1 Title} (~{X} words)
+- **Key Points**:
+  - [Point 1 with research reference]
+  - [Point 2 with supporting data]
+  - [Point 3]
+- **Keywords**: Use secondary keyword in heading or first paragraph
+- **Evidence**: [Specific stat/quote from research to include]
+
+[Continue for all sections...]
+
+### Conclusion (~{X} words)
+- **Summary Approach**: [Recap key insights, do not repeat verbatim]
+- **CTA**: [Specific call to action]
+- **Next Steps**: [What the reader should do next]
+
+## Keyword Placement Map
+
+| Keyword | Location | Context |
+|---------|----------|---------|
+| {primary} | Title, Intro para 1, H2-1, Conclusion | Natural integration |
+| {secondary1} | H2-2, Body section 3 | Supporting context |
+```
+
+### Planning Constraints
+
+- Word count allocations must sum to the target (+/-5%)
+- Every section must have at least 2 key points
+- Keywords cannot be forced; place only where natural
+- Plan must clearly derive from the selected Theme and ideation findings

package/skills/myai-content-ideation/evals/evals.json

@@ -0,0 +1,182 @@
+{
+  "skill_name": "myai-content-ideation",
+  "evals": [
+    {
+      "id": 0,
+      "name": "enterprise-saas",
+      "prompt": "Research the topic of AI-powered customer support automation for B2B SaaS companies. Audience: CTOs and VP Engineering at mid-market SaaS companies (100-500 employees). Content type: blog-post. Word count: 2000.",
+      "expected_output": "Themes JSON with 2-4 themes, ideation.md with research, plan.md with article structure, content stubs in content-queue/",
+      "files": [],
+      "assertions": [
+        {
+          "id": "themes-file-exists",
+          "text": "content-themes.json exists and is valid JSON",
+          "type": "file_check"
+        },
+        {
+          "id": "themes-count",
+          "text": "content-themes.json contains 2-4 themes",
+          "type": "content_check"
+        },
+        {
+          "id": "themes-have-required-fields",
+          "text": "Each theme has title, description, strategy, and referenceUrls fields",
+          "type": "content_check"
+        },
+        {
+          "id": "themes-valid-strategies",
+          "text": "Each theme strategy is one of: Gap Analysis, Current Trends, Related Subject, Hub and Spoke, Unique Angle, Venn Diagram, or a custom strategy with rationale",
+          "type": "content_check"
+        },
+        {
+          "id": "ideation-file-exists",
+          "text": ".content-session/ideation.md exists and follows the template structure",
+          "type": "file_check"
+        },
+        {
+          "id": "ideation-has-sources",
+          "text": "ideation.md contains at least 3 sourced facts with URLs",
+          "type": "content_check"
+        },
+        {
+          "id": "ideation-has-content-gaps",
+          "text": "ideation.md identifies at least 2 content gaps",
+          "type": "content_check"
+        },
+        {
+          "id": "plan-file-exists",
+          "text": ".content-session/plan.md exists and follows the plan template",
+          "type": "file_check"
+        },
+        {
+          "id": "plan-word-counts",
+          "text": "plan.md section word counts sum to approximately 2000 words (+/-5%)",
+          "type": "content_check"
+        },
+        {
+          "id": "stubs-created",
+          "text": "Content stubs exist in content-queue/ with one stub per theme",
+          "type": "file_check"
+        },
+        {
+          "id": "stubs-have-frontmatter",
+          "text": "Each content stub has valid YAML frontmatter with required fields (title, mode, content_type, status, strategy, audience, keywords, references)",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 1,
+      "name": "edge-computing",
+      "prompt": "Research edge computing and WebAssembly for IoT applications. Audience: backend developers and DevOps engineers building IoT platforms. Content type: technical tutorial. Tone: conversational. Word count: 2500.",
+      "expected_output": "Themes JSON, ideation.md, plan.md with tutorial structure, content stubs reflecting technical tutorial type and conversational tone",
+      "files": [],
+      "assertions": [
+        {
+          "id": "themes-file-exists",
+          "text": "content-themes.json exists and is valid JSON",
+          "type": "file_check"
+        },
+        {
+          "id": "themes-count",
+          "text": "content-themes.json contains 2-4 themes",
+          "type": "content_check"
+        },
+        {
+          "id": "themes-distinct",
+          "text": "Themes are meaningfully different from each other (not just variations of the same angle)",
+          "type": "content_check"
+        },
+        {
+          "id": "ideation-file-exists",
+          "text": ".content-session/ideation.md exists with research findings",
+          "type": "file_check"
+        },
+        {
+          "id": "ideation-contrarian-viewpoint",
+          "text": "ideation.md includes at least one contrarian or alternative viewpoint",
+          "type": "content_check"
+        },
+        {
+          "id": "plan-content-type",
+          "text": "plan.md reflects technical tutorial content type (not generic blog post)",
+          "type": "content_check"
+        },
+        {
+          "id": "plan-tone",
+          "text": "plan.md specifies conversational tone",
+          "type": "content_check"
+        },
+        {
+          "id": "plan-word-count-target",
+          "text": "plan.md targets 2500 words total across sections",
+          "type": "content_check"
+        },
+        {
+          "id": "stubs-created",
+          "text": "Content stubs exist in content-queue/ with correct content_type and tone",
+          "type": "file_check"
+        },
+        {
+          "id": "reference-urls-real",
+          "text": "Theme referenceUrls are plausible real URLs (not example.com placeholders)",
+          "type": "content_check"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "green-cloud",
+      "prompt": "Research sustainable cloud infrastructure and green computing practices. Audience: infrastructure architects and sustainability officers at enterprise companies. Content type: blog-post. Write themes to .content-session/green-cloud/themes.json. Job directory: content-queue/job20260311_01/",
+      "expected_output": "Themes written to custom path, ideation.md, plan.md, stubs in specified job directory",
+      "files": [],
+      "assertions": [
+        {
+          "id": "themes-custom-path",
+          "text": "Themes written to .content-session/green-cloud/themes.json (NOT content-themes.json)",
+          "type": "file_check"
+        },
+        {
+          "id": "themes-valid-json",
+          "text": "themes.json is valid JSON with lastUpdated and themes array",
+          "type": "content_check"
+        },
+        {
+          "id": "themes-count",
+          "text": "themes.json contains 2-4 themes",
+          "type": "content_check"
+        },
+        {
+          "id": "ideation-file-exists",
+          "text": ".content-session/ideation.md exists",
+          "type": "file_check"
+        },
+        {
+          "id": "plan-file-exists",
+          "text": ".content-session/plan.md exists",
+          "type": "file_check"
+        },
+        {
+          "id": "stubs-in-specified-dir",
+          "text": "Content stubs are in content-queue/job20260311_01/ (the specified job directory)",
+          "type": "file_check"
+        },
+        {
+          "id": "stubs-match-themes",
+          "text": "Number of stubs matches number of themes (one stub per theme)",
+          "type": "content_check"
+        },
+        {
+          "id": "no-root-themes-file",
+          "text": "No content-themes.json created at project root (should use custom path only)",
+          "type": "file_check"
+        },
+        {
+          "id": "stubs-audience-correct",
+          "text": "Stub frontmatter audience field references infrastructure architects and sustainability officers",
+          "type": "content_check"
+        }
+      ]
+    }
+  ]
+}