conectese 0.1.14 → 0.2.0

package/_conectese/core/best-practices/_catalog.yaml

@@ -1,116 +0,0 @@
-# Best Practices Catalog
-# The Architect reads this file to discover which best-practices are available.
-# Read the full file only for best-practices relevant to the squad being created.
-
-catalog:
-  # === Discipline Best Practices ===
-  - id: copywriting
-    name: "Copywriting & Persuasive Writing"
-    whenToUse: "Creating agents that write persuasive copy, hooks, CTAs, social media captions, sales content, or viral angles."
-    file: copywriting.md
-
-  - id: researching
-    name: "Research & Data Collection"
-    whenToUse: "Creating agents that research topics, collect data from the web, verify facts, or produce structured research briefs."
-    file: researching.md
-
-  - id: review
-    name: "Content Review & Quality Control"
-    whenToUse: "Creating agents that evaluate content quality, score against criteria, or produce structured APPROVE/REJECT verdicts."
-    file: review.md
-
-  - id: image-design
-    name: "Visual Design & Image Creation"
-    whenToUse: "Creating agents that design graphics, carousel slides, social media visuals, or HTML/CSS templates for rendering."
-    file: image-design.md
-
-  - id: social-networks-publishing
-    name: "Social Networks Publishing"
-    whenToUse: "Creating agents that publish content to Instagram, LinkedIn, X/Twitter, YouTube, or other social platforms."
-    file: social-networks-publishing.md
-
-  - id: strategist
-    name: "Strategy & Editorial Planning"
-    whenToUse: "Creating agents that plan content strategy, editorial calendars, competitive positioning, or audience segmentation."
-    file: strategist.md
-
-  - id: technical-writing
-    name: "Technical & Long-Form Writing"
-    whenToUse: "Creating agents that write articles, blog posts, documentation, tutorials, white papers, or educational content."
-    file: technical-writing.md
-
-  - id: data-analysis
-    name: "Data Analysis & Interpretation"
-    whenToUse: "Creating agents that interpret metrics, extract insights, benchmark performance, or produce analytical reports."
-    file: data-analysis.md
-
-  # === Platform Best Practices ===
-  - id: instagram-feed
-    name: "Instagram Feed & Carousels"
-    whenToUse: "Creating agents that produce Instagram feed posts, carousels, or static image content for Instagram."
-    file: instagram-feed.md
-
-  - id: instagram-reels
-    name: "Instagram Reels"
-    whenToUse: "Creating agents that produce Instagram Reels or short-form vertical video for Instagram."
-    file: instagram-reels.md
-
-  - id: instagram-stories
-    name: "Instagram Stories"
-    whenToUse: "Creating agents that produce Instagram Stories or ephemeral 24-hour content."
-    file: instagram-stories.md
-
-  - id: linkedin-post
-    name: "LinkedIn Post"
-    whenToUse: "Creating agents that produce LinkedIn posts, text updates, or document carousels for LinkedIn."
-    file: linkedin-post.md
-
-  - id: linkedin-article
-    name: "LinkedIn Article"
-    whenToUse: "Creating agents that produce LinkedIn articles or long-form professional content."
-    file: linkedin-article.md
-
-  - id: twitter-post
-    name: "Twitter/X Post"
-    whenToUse: "Creating agents that produce tweets, quote tweets, or single posts for X/Twitter."
-    file: twitter-post.md
-
-  - id: twitter-thread
-    name: "Twitter/X Thread"
-    whenToUse: "Creating agents that produce Twitter/X threads or multi-tweet narratives."
-    file: twitter-thread.md
-
-  - id: youtube-script
-    name: "YouTube Video Script"
-    whenToUse: "Creating agents that produce YouTube video scripts or long-form video content."
-    file: youtube-script.md
-
-  - id: youtube-shorts
-    name: "YouTube Shorts"
-    whenToUse: "Creating agents that produce YouTube Shorts or short-form vertical video for YouTube."
-    file: youtube-shorts.md
-
-  - id: email-newsletter
-    name: "Email Newsletter"
-    whenToUse: "Creating agents that produce email newsletters or recurring subscriber content."
-    file: email-newsletter.md
-
-  - id: email-sales
-    name: "Sales Email"
-    whenToUse: "Creating agents that produce sales emails, cold outreach, or direct response email campaigns."
-    file: email-sales.md
-
-  - id: blog-post
-    name: "Blog Post"
-    whenToUse: "Creating agents that produce blog posts, articles, or long-form content marketing."
-    file: blog-post.md
-
-  - id: blog-seo
-    name: "Blog Post (SEO)"
-    whenToUse: "Creating agents that produce SEO-optimized blog posts or search-targeted content."
-    file: blog-seo.md
-
-  - id: whatsapp-broadcast
-    name: "WhatsApp Broadcast"
-    whenToUse: "Creating agents that produce WhatsApp broadcast messages or conversational marketing content."
-    file: whatsapp-broadcast.md

package/_conectese/core/best-practices/blog-post.md

@@ -1,132 +0,0 @@
----
-name: "Blog Post"
-platform: "blog"
-content_type: "post"
-description: "Long-form blog posts optimized for readability, engagement, and clear value delivery with structured subheadings"
-whenToUse: |
-  Creating agents that produce blog posts, articles, or long-form content marketing.
-constraints:
-  optimal_word_count: "1500-2500"
-  title_max_chars: 70
-  meta_description_chars: 160
-  subheading_frequency: "every 200-300 words"
-version: "1.0.0"
----
-
-## Platform Rules
-
-- Average time on page is the strongest engagement signal. Blog posts that keep readers scrolling for 3-5 minutes outperform those that get abandoned in the first 30 seconds. Structure and readability directly determine this metric.
-- Posts between 1,500-2,500 words hit the optimal balance of depth and retention. Below 800 words, content is perceived as thin and struggles to rank. Above 3,000 words, completion rates drop unless the topic demands exhaustive coverage.
-- Mobile readability is non-negotiable. Over 60% of blog traffic comes from mobile devices. Long paragraphs, wide images, and dense formatting that work on desktop become unreadable walls on small screens.
-- Subheadings serve as a scannable table of contents. Studies show 73% of readers scan blog posts rather than reading word by word. If the subheadings alone do not convey the article's value, the structure needs reworking.
-- Internal linking keeps readers on site and distributes page authority. Posts with 3+ internal links to related content have higher average session duration and lower bounce rates.
-- External links to authoritative sources (research, industry leaders, official documentation) increase credibility and can positively impact search ranking when linking to genuinely relevant resources.
-- Publishing consistency builds audience expectation and return visits. A regular cadence (1-2 posts per week) outperforms sporadic publishing bursts followed by silence.
-- Visual breaks every 300 words prevent fatigue: images, callout boxes, bullet lists, or blockquotes. Unbroken text spanning more than 300 words causes readers to disengage.
-
-## Content Structure
-
-### Blog Post Architecture
-
-1. **Title** — Under 70 characters. Clearly communicates what the reader will learn or gain. Front-load the key topic. Avoid vague or overly clever titles that sacrifice clarity for creativity.
-2. **Meta description** — 150-160 characters. Summarizes the post's value proposition in one sentence. This appears in search results and social shares — it is a second headline.
-3. **Intro hook (2-3 sentences)** — Open with a surprising stat, bold claim, relatable problem, or a story that places the reader in a scenario. Then state exactly what the post will deliver.
-4. **Body sections (3-6 H2 sections)** — Each section covers one major point with its own H2 subheading. Sections are 200-300 words each with H3 sub-sections for deeper breakdowns.
-5. **Conclusion (3-5 sentences)** — Summarize the key takeaways in 1-2 sentences, then deliver a clear CTA: read a related post, download a resource, leave a comment, or try a specific action.
-
-### Section-Level Structure
-
-- **H2 subheading** — Descriptive, scannable, and self-contained. A reader should understand the section's value from the heading alone.
-- **Opening sentence** — State the section's key point immediately. Do not build up to the insight.
-- **Supporting content** — Evidence, examples, data, or step-by-step instructions. Use bullet points for lists of 3+ items.
-- **Transition** — Final sentence bridges to the next section or reinforces the section's takeaway.
-
-### Effective Post Formats
-
-- **How-to guide**: "How to [achieve X]: A Step-by-Step Guide"
-- **Listicle**: "7 [Things] That [Outcome] (and How to Use Them)"
-- **Problem/Solution**: "Why [Problem Exists] and What to Do About It"
-- **Lessons learned**: "What I Learned From [Experience]: [N] Key Takeaways"
-- **Comparison**: "[Option A] vs. [Option B]: Which Is Right for [Audience]?"
-
-## Writing Guidelines
-
-- **Hook the reader in the first 2-3 sentences or lose them.** Open with a stat, question, bold claim, or relatable scenario. Never start with a dictionary definition or generic background. "Content marketing is important" loses readers. "87% of blog posts get zero organic traffic" keeps them.
-- Write in short paragraphs: 3-4 lines maximum on desktop, which translates to 2-3 lines on mobile. Single-sentence paragraphs are powerful for emphasis.
-- Bold key phrases and takeaways within paragraphs so scanners can extract value without reading every word.
-- Use bullet points and numbered lists for any sequence of 3+ items. Lists are easier to scan than inline comma-separated items.
-- Subheadings every 200-300 words. Each H2 should read like a mini-headline that a scanner would click on if presented independently.
-- Write in second person ("you") to create direct connection with the reader. First person ("I/we") works for personal stories and experience-based authority.
-- Include at least one visual break (image, callout box, blockquote, or list) every 300 words. Continuous text blocks cause reader fatigue and increase bounce rate.
-- End with a specific, actionable CTA. "What do you think?" is weak. "Try implementing [technique] this week and comment below with your results" is strong.
-- Include 3+ internal links to related content on your site and 2+ external links to authoritative sources. Link naturally within context, not in a dumped list at the end.
-- Write the title last, after you know what the post delivers. Front-load the most important keyword or concept in the first 40 characters.
-
-## Output Format
-
-```
-=== TITLE ===
-[Under 70 characters — clear, specific, keyword front-loaded]
-
-=== META DESCRIPTION ===
-[150-160 characters — summarizes the post's value proposition in one sentence]
-
-=== INTRO ===
-[Hook — surprising stat, bold claim, relatable problem, or opening story. 1-2 sentences.]
-
-[Promise — exactly what the reader will learn or gain from this post. 1 sentence.]
-
-=== BODY ===
-## [H2 Section 1 Title]
-[200-300 words — one major point with evidence, examples, or steps. Include bullet points or visuals where appropriate.]
-
-## [H2 Section 2 Title]
-[200-300 words — one major point with evidence, examples, or steps.]
-
-### [H3 Subsection if needed]
-[Deeper breakdown of a specific aspect — 100-150 words.]
-
-## [H2 Section 3 Title]
-[200-300 words — one major point with evidence, examples, or steps.]
-
-## [H2 Section 4 Title]
-[200-300 words — one major point with evidence, examples, or steps.]
-
-[Continue for 3-6 H2 sections total]
-
-=== CONCLUSION ===
-[Key takeaway summary — 1-2 sentences.]
-
-[CTA — specific, actionable ask. 1-2 sentences.]
-
-=== POST NOTES ===
-Target word count: [1500-2500]
-Internal links needed: [3+ with suggested anchor text]
-External links needed: [2+ to authoritative sources]
-Visual breaks: [List of suggested image/callout placements]
-```
-
-## Quality Criteria
-
-- [ ] Title is under 70 characters and clearly communicates the post's value
-- [ ] Meta description is 150-160 characters and serves as a compelling second headline
-- [ ] Intro hooks the reader in the first 2-3 sentences with a stat, bold claim, or relatable scenario
-- [ ] Post contains 3-6 H2 sections, each covering one major point
-- [ ] Subheadings appear every 200-300 words and are scannable as a standalone outline
-- [ ] Paragraphs are 3-4 lines maximum with key phrases bolded
-- [ ] At least one visual break (image, callout, list, or blockquote) every 300 words
-- [ ] 3+ internal links and 2+ external links are included with natural anchor text
-- [ ] Total word count is between 1,500-2,500 words
-- [ ] Conclusion ends with a specific, actionable CTA (not generic "What do you think?")
-
-## Anti-Patterns
-
-- **Walls of text** — Paragraphs exceeding 5-6 lines on desktop become impenetrable on mobile. Readers bounce rather than parse dense blocks. Short paragraphs and visual breaks are not optional — they are structural requirements for retention.
-- **No subheadings** — A 2,000-word post without H2/H3 subheadings is functionally a wall of text. Scanners (73% of readers) cannot extract value and leave. Subheadings serve as both navigation and content promises.
-- **Clickbait titles that do not deliver** — "This One Trick Changed Everything" followed by generic advice destroys trust. The reader feels deceived, bounces quickly, and never returns. High bounce rates also signal low quality to search engines.
-- **Thin content under 800 words** — Short posts struggle to provide sufficient depth, rank poorly for competitive keywords, and signal low effort. If the topic can be covered in 500 words, it may be better as a social post than a blog article.
-- **No conclusion or CTA** — Posts that simply stop after the last body section feel incomplete. The reader has invested 3-5 minutes and receives no guidance on what to do next. Every post needs a clear ending and next step.
-- **Dictionary definition openings** — Starting with "[Topic] is defined as..." is the most common sign of filler content. It adds no value, wastes the most important real estate in the post, and signals that the writer has nothing original to say.
-- **Link dumping** — Placing all internal and external links in a list at the bottom of the post rather than weaving them naturally into the content. Contextual links are clicked more and provide more value to the reader.
-- **No visual breaks** — Continuous text for 500+ words without an image, list, callout, or blockquote causes reading fatigue. Even well-written content gets abandoned when it is visually monotonous.
-- **Writing for search engines instead of humans** — Unnaturally forcing keywords into every sentence makes content awkward and unpleasant to read. Write for clarity first; optimize for search second.

package/_conectese/core/best-practices/blog-seo.md

@@ -1,127 +0,0 @@
----
-name: "Blog Post (SEO)"
-platform: "blog"
-content_type: "seo"
-description: "SEO-optimized blog posts designed for organic search traffic, featured snippets, and topical authority"
-whenToUse: |
-  Creating agents that produce SEO-optimized blog posts or search-targeted content.
-constraints:
-  optimal_word_count: "2000-3000"
-  title_max_chars: 60
-  meta_description_chars: 160
-  keyword_density: "1-2%"
-  subheading_frequency: "every 200-300 words"
-  min_internal_links: 3
-  min_external_links: 2
-version: "1.0.0"
----
-
-## Platform Rules
-
-- Search intent is the single most important ranking factor. Google categorizes queries into four intent types: informational ("how to"), navigational ("brand + feature"), commercial ("best X for Y"), and transactional ("buy X"). Content that mismatches intent will not rank regardless of quality.
-- Comprehensive content outranks shallow content. Posts that thoroughly cover a topic, address related questions, and satisfy the searcher's full information need earn longer dwell times and higher rankings.
-- Keyword placement follows a hierarchy of impact: title tag (front-loaded) > H1 > first 100 words > H2 subheadings > body text > meta description > image alt text. Distribute the primary keyword naturally across these locations.
-- Keyword density should stay between 1-2% of total word count. Below 1%, the content may not signal topical relevance clearly enough. Above 2-3%, it reads as stuffing and risks algorithmic penalties.
-- Featured snippets (position zero) are triggered by content that directly answers a specific question in paragraph (40-60 words), list (5-8 items), or table format immediately after an H2 that contains the question.
-- Internal linking distributes page authority and signals content relationships to search engines. Every SEO post should link to 3+ related pages on the same domain with descriptive anchor text (not "click here").
-- External links to authoritative sources (research papers, official docs, industry leaders) signal content credibility. Posts with 2+ quality external links tend to rank higher than those with none.
-- Core Web Vitals affect rankings. Heavy images without compression, excessive scripts, and layout shifts hurt performance. Optimize images (WebP format, compressed, with width/height attributes) and keep the page lightweight.
-- AI Overviews are increasingly replacing traditional featured snippets for complex queries. Structured, well-cited content is more likely to be referenced as a source in AI-generated summaries.
-
-## Content Structure
-
-### SEO Blog Post Architecture
-
-1. **Title tag** — Under 60 characters. Primary keyword front-loaded within the first 40 characters. Clearly communicates the post's value. Must match search intent.
-2. **Meta description** — 150-160 characters. Includes the primary keyword naturally. Functions as ad copy for the search result — must compel the click.
-3. **H1 heading** — Contains the primary keyword. Can be slightly longer than the title tag since it is not character-limited by search results.
-4. **Intro (first 100 words)** — Include the primary keyword within the first 100 words. Open with the searcher's problem or question, then promise a comprehensive answer.
-5. **Body sections (5-8 H2 sections)** — Each H2 targets a related subtopic or question. Include the primary keyword in 2-3 H2 subheadings naturally. Use H3 subheadings for deeper breakdowns within sections.
-6. **FAQ section** — 3-5 questions from "People Also Ask" for the target keyword. Answer each in 40-60 words to target featured snippets and AI Overviews.
-7. **Conclusion** — Summarize key takeaways. Include the primary keyword one final time. End with a CTA (related post, resource download, or action prompt).
-
-### Featured Snippet Optimization
-
-- **Paragraph snippets**: Place a concise 40-60 word answer immediately after an H2 that phrases the question. Follow with expanded detail.
-- **List snippets**: Use ordered or unordered lists with 5-8 items. The H2 should frame the list ("X Ways to..." or "Steps to...").
-- **Table snippets**: Use HTML tables for comparative data. Include clear column headers and 3-5 rows of structured data.
-
-Cover the topic comprehensively enough that the reader does not need to return to search results. Address related questions from "People Also Ask" and include original data or analysis not found in competing articles.
-
-## Writing Guidelines
-
-- **Match search intent before writing a single word.** Search the target keyword, analyze the top 5 results, and understand what format (guide, list, comparison, tutorial) and depth Google is rewarding. Then match or exceed it.
-- Front-load the primary keyword in the title tag, ideally within the first 40 characters. "Email Marketing Guide: 10 Strategies for 2026" outranks "The Ultimate Guide to Everything About Email Marketing."
-- Include the primary keyword in the first 100 words naturally. Forced insertion ("In this article about [keyword], we will discuss [keyword]...") reads awkwardly and signals low-quality content.
-- Use the primary keyword in 2-3 H2 subheadings, but not all of them. Vary with synonyms, related terms, and natural language variations. This captures long-tail queries and avoids over-optimization.
-- Write for a Flesch-Kincaid readability score of 60+ (approximately 8th grade reading level). Short sentences, common words, and active voice. Technical topics can go slightly lower, but clarity is always the goal.
-- Use descriptive anchor text for internal links. "Learn more about email subject line formulas" outperforms "click here" for both user experience and search engine context.
-- Add alt text to every image that describes the image content and includes the keyword where relevant. Alt text like "email-marketing-guide.jpg" is useless. "Bar chart showing email open rates by industry in 2026" provides value.
-- Include an FAQ section targeting "People Also Ask" queries. Answer each question concisely (40-60 words) in the paragraph immediately following the question heading. This is the primary format for featured snippet capture.
-- Write 2,000-3,000 words for competitive keywords. Longer content correlates with higher rankings, but only when every section adds genuine value. Padding word count with filler actively harms rankings through reduced dwell time.
-- Update published content quarterly. Refreshing data, adding new sections, and updating examples signals freshness to search engines and can recover declining rankings.
-
-## Output Format
-
-```
-=== TARGET KEYWORD ===
-Primary: [Exact phrase to rank for] | Secondary: [2-3 long-tail variations]
-Search intent: [Informational / Navigational / Commercial / Transactional]
-
-=== TITLE TAG ===
-[Under 60 characters — primary keyword front-loaded in first 40 chars]
-
-=== META DESCRIPTION ===
-[150-160 characters — includes primary keyword, compelling click copy]
-
-=== INTRO ===
-[First 100 words — keyword included naturally. Opens with problem/question, promises comprehensive answer.]
-
-=== BODY ===
-## [H2 Section 1 — contains primary or secondary keyword]
-[200-300 words — one subtopic with evidence, examples, or steps.]
-
-## [H2 Section 2 — natural language variation]
-[200-300 words — related subtopic or question. Continue for 5-8 H2 sections total.]
-
-=== FAQ SECTION ===
-### [Question from "People Also Ask" 1]
-[40-60 word direct answer optimized for featured snippet capture.]
-
-### [Question from "People Also Ask" 2]
-[40-60 word direct answer.]
-
-=== CONCLUSION ===
-[Key takeaway with primary keyword. CTA to related post or resource. 2-3 sentences.]
-
-=== SEO CHECKLIST ===
-Internal links: [3+] | External links: [2+] | Word count: [2000-3000] | Keyword density: [1-2%]
-```
-
-## Quality Criteria
-
-- [ ] Title tag is under 60 characters with the primary keyword in the first 40 characters
-- [ ] Meta description is 150-160 characters, includes the primary keyword, and compels the click
-- [ ] Primary keyword appears in the first 100 words naturally
-- [ ] Primary keyword is in 2-3 H2 subheadings without forcing it into all of them
-- [ ] Keyword density is between 1-2% (not below, not above)
-- [ ] 5-8 H2 sections with subheadings every 200-300 words
-- [ ] FAQ section contains 3-5 questions with 40-60 word answers targeting featured snippets
-- [ ] 3+ internal links with descriptive anchor text (not "click here")
-- [ ] 2+ external links to authoritative, relevant sources
-- [ ] Every image has descriptive alt text that includes the keyword where naturally appropriate
-- [ ] Content satisfies the target search intent fully (reader does not need to return to search results)
-- [ ] Total word count is between 2,000-3,000 words
-
-## Anti-Patterns
-
-- **Keyword stuffing (above 3% density)** — Repeating the keyword in every sentence triggers Google's spam detection. Over-optimized content is actively penalized with ranking demotions.
-- **Thin content under 1,500 words** — For competitive keywords, thin content cannot outrank comprehensive competitors. Google associates depth with topical authority for informational queries.
-- **Ignoring search intent** — Writing a comparison when Google ranks how-to guides, or an informational piece when the SERP shows commercial pages. Mismatched intent means zero ranking potential regardless of quality.
-- **Duplicate or near-duplicate content** — Substantially similar content across multiple URLs cannibalizes your own rankings. Google suppresses duplicates, splitting your authority.
-- **No meta description** — Google auto-generates one from page content when left blank. The result is almost always less compelling, reducing click-through rates from search results.
-- **Orphan pages with no internal links** — Pages with no inbound internal links are hard for search engines to discover and receive no transferred authority, making ranking significantly harder.
-- **"Click here" anchor text** — Generic anchors provide no topical context to search engines. Descriptive anchors ("email subject line best practices") pass relevance and improve linked page rankings.
-- **Forcing keywords into every heading** — Every H2 containing the exact keyword reads as robotic and over-optimized. Use natural variations and related terms across headings.
-- **Publishing and forgetting** — Content not updated degrades in rankings as competitors publish fresher coverage. Quarterly reviews maintain positions.
-- **Skipping the FAQ section** — "People Also Ask" appears for 60%+ of queries. Missing the FAQ section forfeits a high-probability featured snippet opportunity.