@aksp/opencrew 1.0.0

package/templates/_opencrew/core/best-practices/technical-writing.md

@@ -0,0 +1,382 @@
+---
+id: technical-writing
+name: "Technical & Long-Form Writing"
+whenToUse: |
+  Creating agents that write articles, blog posts, documentation, tutorials,
+  white papers, case studies, or educational content.
+  NOT for: short-form persuasive copy, research, data analysis, strategic planning.
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Prioritize clarity over cleverness; use simple, direct language accessible to the target audience.
+2. Always construct and secure approval for an outline before drafting the full piece.
+3. Support every claim with concrete evidence, citations, or data; never fabricate statistics.
+4. Define all technical terms, acronyms, and jargon on their first use.
+5. Employ progressive disclosure: start with accessible concepts and layer complexity gradually.
+6. Use subheadings, bullet points, and short paragraphs to make the content highly scannable.
+7. Include at least one concrete example or code snippet in every major section.
+8. Conclude with actionable takeaways or specific next steps for the reader.
+9. Ensure the introduction explicitly promises what the piece will deliver, and fulfill it.
+10. Adjust vocabulary and depth to match the specific expertise level of the target audience.
+11. Provide complete metadata: title, meta description, estimated reading time, and tags.
+12. Never use em dashes; use commas, periods, colons, or parentheses instead.
+
+<!-- End Compact Rules. Full reference below. -->
+
+# Technical & Long-Form Writing — Best Practices
+
+## Core Principles
+
+1. **Clarity over cleverness.** Use simple, direct language. Choose concrete examples over abstract explanations. If a twelve-year-old cannot understand your sentence structure, rewrite it. Technical content does not require complicated prose.
+
+2. **Structure first, always.** Never write without an outline. The outline is the skeleton that holds everything together. Define your sections, their order, and their purpose before drafting a single paragraph. Share the outline for approval before proceeding to the full draft.
+
+3. **Evidence-based arguments.** Every claim needs support. Cite sources, reference data, quote experts, or provide concrete examples. Unsupported assertions undermine credibility. When exact data is unavailable, say so explicitly rather than fabricating statistics.
+
+4. **Progressive disclosure.** Start simple, build complexity. Introduce concepts in layers so readers can follow regardless of their starting knowledge level. The first paragraph of each section should be accessible; depth increases as the section progresses.
+
+5. **Accessibility without compromise.** Never use jargon without defining it on first use. Acronyms get spelled out the first time. Technical terms receive inline definitions or parenthetical explanations. Accessibility does not mean dumbing down; it means removing unnecessary barriers.
+
+6. **Completeness within scope.** Cover the topic thoroughly within the defined boundaries. If a topic requires more depth than the current format allows, flag it and recommend a follow-up piece or a series. Never leave obvious questions unanswered.
+
+7. **Audience-appropriate depth.** A tutorial for beginners requires different depth than a white paper for CTOs. Assess the audience before writing and calibrate vocabulary, example complexity, and assumed knowledge accordingly. When in doubt, err on the side of more explanation, not less.
+
+8. **Scannable structure.** Use subheadings, bullet points, numbered lists, bold key terms, and short paragraphs. Readers scan before they read. Make scanning productive by ensuring subheadings communicate the key point of each section.
+
+9. **Actionable takeaways.** Every piece should leave the reader with something they can do. A blog post should end with next steps. A tutorial should produce a working result. A white paper should inform a decision. Content without action is content without purpose.
+
+## Writing Methodology
+
+### Step 1: Load Context
+
+Gather all inputs before writing anything. Required context includes:
+- Topic definition and scope boundaries
+- Target audience (role, expertise level, goals)
+- Brand voice guidelines (if available)
+- Research brief or source materials (from researcher agent)
+- Content format (blog post, tutorial, documentation, white paper)
+- Target word count or depth expectations
+- Any existing content on the topic to avoid duplication
+
+### Step 2: Create Outline
+
+Build a detailed outline that maps the argument or teaching progression:
+- Define the hook (why should the reader care right now?)
+- Map sections to a logical flow (chronological, problem-solution, simple-to-complex)
+- Assign approximate word counts per section
+- Identify where evidence, examples, and visuals are needed
+- Mark sections that may need additional research
+- Present the outline for approval before proceeding
+
+### Step 3: Draft Introduction
+
+Write the introduction with three components:
+- **Hook:** A concrete scenario, surprising statistic, or relatable problem that pulls the reader in
+- **Promise:** A clear statement of what the reader will learn or gain
+- **Roadmap:** A brief preview of the article structure so the reader knows what to expect
+
+### Step 4: Write Body Sections
+
+Draft one section at a time, following the approved outline:
+- Open each section with a clear topic sentence
+- Support claims with evidence (data, citations, examples)
+- Include at least one concrete example per section
+- Use transitional phrases between paragraphs and sections
+- Add subheadings every 200-300 words
+- Keep paragraphs under 4-5 sentences
+
+### Step 5: Draft Conclusion
+
+Write a conclusion that delivers on the introduction's promise:
+- Summarize key points without repeating them verbatim
+- Provide an actionable takeaway the reader can implement immediately
+- If appropriate, point to next steps or related resources
+- End on a forward-looking or motivating note, not a summary rehash
+
+### Step 6: Self-Review
+
+Review the complete draft against quality criteria:
+- Read the full piece for flow and coherence
+- Check that every section delivers on its outline promise
+- Verify all claims have supporting evidence
+- Confirm no jargon is used without definition
+- Validate subheading frequency and readability
+- Ensure the introduction's promise matches the conclusion's delivery
+- Check reading level appropriateness for the target audience
+
+### Step 7: Compile with Metadata
+
+Prepare the final output with all required metadata:
+- Title (compelling, specific, keyword-aware)
+- Subtitle or deck (one-sentence summary)
+- Meta description (for SEO, 150-160 characters)
+- Suggested tags or categories
+- Estimated reading time
+- The complete article body
+
+## Decision Criteria
+
+- **When to add examples vs. move on:** Add an example whenever a concept is abstract, counterintuitive, or new to the target audience. Move on when the point is concrete and self-evident.
+- **When depth is sufficient:** Depth is sufficient when a reader at the target expertise level can act on the information without needing to consult another source for the same concept.
+- **When to recommend splitting into a series:** If the outline exceeds the target word count by more than 30%, or if two or more sections could stand alone as complete articles, recommend a series.
+- **When to use lists vs. prose:** Use lists for sequential steps, parallel items, or scannable reference material. Use prose for narrative flow, argumentation, and context-setting.
+- **When to recommend visuals:** Recommend a diagram, screenshot, or illustration whenever a concept involves spatial relationships, multi-step processes, or comparisons across three or more items.
+
+## Quality Criteria
+
+Before delivering any piece of content, verify the following:
+
+- [ ] **Clear structure.** The piece has a defined introduction, body sections, and conclusion. The reader can predict the flow from the introduction.
+- [ ] **Examples in every section.** Each body section contains at least one concrete example, code snippet, scenario, or case reference.
+- [ ] **No undefined jargon.** Every technical term, acronym, or domain-specific phrase is defined on first use.
+- [ ] **Appropriate subheading frequency.** No section runs longer than 300 words without a subheading or visual break.
+- [ ] **Evidence-backed claims.** Quantitative claims reference a source. Qualitative claims are supported by examples or expert references.
+- [ ] **Actionable takeaway present.** The piece ends with specific next steps, recommendations, or actions the reader can take.
+- [ ] **Reading level matches audience.** A beginner tutorial reads at a lower complexity than a white paper for senior engineers. Vocabulary and assumed knowledge align with the target audience.
+- [ ] **Word count matches format.** Blog posts: 800-2,000 words. Tutorials: 1,500-3,000 words. White papers: 3,000-6,000 words. Documentation pages: 500-1,500 words.
+- [ ] **No em dashes.** The entire output has been checked for em dashes and none are present.
+- [ ] **Introduction promise matches conclusion delivery.** Whatever the introduction says the reader will learn, the conclusion confirms they learned it.
+- [ ] **Transitions between sections.** Each section connects logically to the next. The reader never wonders "why am I reading this now?"
+- [ ] **Metadata complete.** Title, meta description, tags, and estimated reading time are all provided with the final draft.
+
+## Output Examples
+
+### Example 1: Blog Post Introduction + Outline + First Section
+
+**Title:** How Connection Pooling Cuts Your Database Latency in Half
+
+**Meta description:** Learn how connection pooling works, why it reduces database latency, and how to implement it in Node.js with practical code examples.
+
+**Estimated reading time:** 8 minutes
+
+---
+
+**Introduction:**
+
+Every time your application opens a new database connection, it pays a tax. The TCP handshake, authentication, SSL negotiation, and protocol setup add 20-50 milliseconds per connection. For a single request, that is negligible. For an application handling 1,000 requests per second, that is 20-50 seconds of cumulative overhead every second, just from connection setup.
+
+Connection pooling eliminates this tax by maintaining a set of pre-established connections that your application reuses. Instead of opening and closing connections per request, your app borrows a connection from the pool, uses it, and returns it. The result: database latency drops by 40-60% in most production workloads.
+
+This article covers three things. First, you will understand how connection pooling works under the hood. Second, you will see benchmark data comparing pooled and unpooled connections. Third, you will implement a production-ready connection pool in Node.js with proper error handling and monitoring.
+
+---
+
+**Outline:**
+
+1. The cost of a database connection (what happens during setup, measured latency)
+2. How connection pooling works (pool lifecycle, borrow/return model, idle management)
+3. Benchmark results (pooled vs. unpooled across load levels)
+4. Implementation in Node.js (code walkthrough with pg-pool)
+5. Production considerations (pool sizing, error handling, monitoring)
+6. Common pitfalls (connection leaks, pool exhaustion, stale connections)
+7. Key takeaways and next steps
+
+---
+
+**Section 1: The Cost of a Database Connection**
+
+When your application calls `db.connect()`, the following sequence executes before a single query can run:
+
+1. **DNS resolution** resolves the database hostname to an IP address (1-10ms)
+2. **TCP handshake** establishes the network connection with a three-way SYN/SYN-ACK/ACK exchange (1-5ms locally, 10-50ms cross-region)
+3. **TLS negotiation** sets up encrypted communication if SSL is enabled (5-15ms)
+4. **Authentication** sends credentials and receives confirmation (2-10ms)
+5. **Protocol initialization** configures session parameters like character set and timezone (1-5ms)
+
+Total setup cost per connection: **10-90ms** depending on network topology and security configuration.
+
+For a simple SELECT query that takes 2ms to execute, the connection setup can represent 80-97% of the total request time. That ratio gets worse with geographic distance between your application server and database server.
+
+To put this in context, consider an e-commerce application that runs 5 database queries per page load. If each query opens a new connection, the user pays 50-450ms in connection overhead alone, before any actual data retrieval. On a page that otherwise loads in 200ms, connection setup could triple the total response time.
+
+This overhead is entirely avoidable. The connections themselves are reusable. Once established, a database connection can handle thousands of queries sequentially. The only reason to close and reopen connections is resource management, which is exactly what connection pooling automates.
+
+### Example 2: Tutorial Section with Step-by-Step Instructions
+
+**Section: Setting Up Automated Backups with Cron and Restic**
+
+Before you begin, make sure you have the following prerequisites installed on your server:
+
+- **Restic** (version 0.14 or later): the backup tool that handles deduplication and encryption
+- **Cron**: the standard Unix job scheduler (pre-installed on most Linux distributions)
+- **An S3-compatible storage bucket**: where your encrypted backups will be stored (AWS S3, MinIO, or Backblaze B2 all work)
+
+If you do not have Restic installed, run the following command on Ubuntu/Debian:
+
+```bash
+sudo apt update && sudo apt install restic
+```
+
+Verify the installation by checking the version:
+
+```bash
+restic version
+# Expected output: restic 0.16.2 (or later)
+```
+
+**Step 1: Initialize the backup repository.**
+
+A Restic repository is the destination where your backup data lives. You initialize it once, and all future backups write to the same repository. Run this command, replacing the bucket name and path with your own:
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+
+restic -r s3:s3.amazonaws.com/your-bucket-name/backups init
+```
+
+Restic will prompt you for a repository password. Choose a strong password and store it in a password manager. You will need this password for every backup and restore operation. Without it, your backups are permanently inaccessible (this is a security feature, not a limitation).
+
+**Step 2: Create the backup script.**
+
+Rather than typing the full Restic command every time, create a shell script that handles environment variables, paths, and error reporting. Save this file as `/opt/scripts/backup.sh`:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+# Configuration
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+export RESTIC_REPOSITORY="s3:s3.amazonaws.com/your-bucket-name/backups"
+export RESTIC_PASSWORD_FILE="/etc/restic/password.txt"
+
+# Directories to back up
+BACKUP_PATHS="/var/www /etc/nginx /home"
+
+# Directories to exclude
+EXCLUDE_PATTERNS="--exclude='*.tmp' --exclude='node_modules' --exclude='.cache'"
+
+# Run the backup
+restic backup $BACKUP_PATHS $EXCLUDE_PATTERNS \
+  --tag "automated" \
+  --tag "$(hostname)" \
+  2>&1 | logger -t restic-backup
+
+# Prune old snapshots: keep 7 daily, 4 weekly, 6 monthly
+restic forget \
+  --keep-daily 7 \
+  --keep-weekly 4 \
+  --keep-monthly 6 \
+  --prune \
+  2>&1 | logger -t restic-prune
+
+echo "Backup completed at $(date)" | logger -t restic-backup
+```
+
+Two things to note about this script. First, the `set -euo pipefail` line at the top ensures the script stops immediately if any command fails, rather than silently continuing with partial backups. Second, the output pipes to `logger`, which writes to your system's syslog. This means you can review backup logs with `journalctl -t restic-backup` without managing separate log files.
+
+**Step 3: Set file permissions.**
+
+Your backup script contains storage credentials, so restrict its permissions to root only:
+
+```bash
+sudo chmod 700 /opt/scripts/backup.sh
+sudo chown root:root /opt/scripts/backup.sh
+```
+
+Store the repository password in a separate file with equally restrictive permissions:
+
+```bash
+echo "your-repository-password" | sudo tee /etc/restic/password.txt > /dev/null
+sudo chmod 600 /etc/restic/password.txt
+sudo chown root:root /etc/restic/password.txt
+```
+
+**Step 4: Schedule the backup with Cron.**
+
+Open the root crontab and add a daily backup schedule:
+
+```bash
+sudo crontab -e
+```
+
+Add this line to run backups every day at 2:00 AM server time:
+
+```cron
+0 2 * * * /opt/scripts/backup.sh
+```
+
+The five fields represent minute (0), hour (2), day of month (any), month (any), and day of week (any). This schedule avoids peak usage hours while running frequently enough to limit data loss to a maximum of 24 hours.
+
+**Step 5: Verify the setup.**
+
+Run the backup script manually to confirm everything works before relying on the cron schedule:
+
+```bash
+sudo /opt/scripts/backup.sh
+```
+
+After the script completes, verify that snapshots appear in your repository:
+
+```bash
+restic -r s3:s3.amazonaws.com/your-bucket-name/backups snapshots
+```
+
+You should see one snapshot listed with the current timestamp and the tags "automated" and your hostname. If you see errors instead, check that your AWS credentials are correct and that the S3 bucket exists and is accessible from your server.
+
+## Anti-Patterns
+
+### Never Do
+
+1. **Write without an outline.** Drafting without structure leads to meandering content, redundant sections, and missing coverage. Always outline first, get approval, then write.
+
+2. **Use jargon without definition.** Every undefined technical term is a potential exit point for the reader. Define terms inline on first use, even if you think the audience "should know."
+
+3. **Exceed scope without flagging.** If writing reveals that the topic needs more coverage than planned, stop and flag it. Recommend a follow-up piece or series rather than inflating the current piece beyond its intended scope.
+
+4. **Write walls of text without subheadings.** More than 300 words without a visual break (subheading, list, code block, or image) signals that the content needs restructuring. Scan-friendliness is not optional.
+
+5. **Make claims without evidence.** Statements like "most developers prefer" or "this approach is faster" require supporting data, a citation, or at minimum a concrete example. Unsupported claims erode trust.
+
+6. **Use em dashes anywhere in the output.** Replace every em dash with a comma, period, colon, or parenthetical. This is a non-negotiable formatting rule.
+
+7. **Start sections with definitions.** "Authentication is the process of..." is the weakest possible opening. Start with a problem, scenario, or consequence, then introduce the concept as the solution.
+
+8. **Repeat the same point in different words.** If you have said it clearly once, move forward. Repetition for emphasis works in speeches, not in written content. Readers can re-read; they should not have to.
+
+### Always Do
+
+1. **Include at least one concrete example in every section.** Abstract explanations without examples leave readers uncertain about practical application. Examples bridge the gap between theory and practice.
+
+2. **Define technical terms on first use.** Use inline definitions (parenthetical or appositive) to keep the reader moving without requiring them to look things up externally.
+
+3. **Use subheadings every 200-300 words.** Subheadings serve two purposes: they help scanners find relevant sections, and they help readers track their progress through the piece.
+
+4. **Provide actionable takeaways.** Every article, tutorial, or guide should end with something the reader can do next. If your content does not change behavior or inform a decision, reconsider its purpose.
+
+5. **Front-load key information.** Put the most important point of each section in the first sentence. Readers who scan will still absorb the core message.
+
+6. **Use parallel structure in lists.** Every item in a list should follow the same grammatical pattern. Mixing verb forms, sentence fragments, and complete sentences within a single list creates cognitive friction.
+
+## Vocabulary Guidance
+
+### Use
+
+- **Concrete examples** to anchor abstract concepts: "For instance, if your API returns a 429 status code, that means..."
+- **Scenario-based framing** to build relevance: "Consider this scenario: your team just shipped a feature and usage spikes overnight..."
+- **Transitional phrases** to maintain flow between paragraphs and sections: "Building on this foundation...", "With that context in mind...", "This brings us to..."
+- **Active voice** as the default for direct, clear communication: "The function validates the input" not "The input is validated by the function."
+- **Specific numbers and data** over vague qualifiers: "Reduced load time by 40%" not "Significantly improved performance."
+- **Reader-addressing language** to maintain engagement: "You will notice...", "At this point, you have...", "Your next step is..."
+- **Short sentences for key points.** When stating something important, keep it brief. Let the sentence stand alone.
+
+### Avoid
+
+- **Jargon without definition.** If a term requires domain knowledge, define it inline on first use. No exceptions.
+- **Em dashes.** Do not use em dashes in any output. They are the most recognizable marker of AI-generated text. Use commas, periods, parentheses, or colons instead.
+- **Filler phrases.** Remove "It's important to note that...", "It goes without saying...", "Needless to say...", "At the end of the day...", "In today's world..." These add no information.
+- **Passive voice without reason.** Use passive voice only when the actor is genuinely unknown or irrelevant. Otherwise, name the subject.
+- **"In conclusion" or "To summarize."** The conclusion should feel like a natural landing, not an announcement. Show the ending through content, not labels.
+- **Walls of text.** Never write more than 300 words without a subheading, list, or visual break. Dense paragraphs lose readers.
+- **Rhetorical questions as filler.** Only use a question when you immediately answer it and the answer drives the narrative forward.
+- **Exclamation marks.** Professional content earns enthusiasm through substance, not punctuation.
+
+### Tone Rules
+
+1. **Authoritative but approachable.** Write like a senior colleague explaining something to a motivated junior, not like a professor lecturing a class. Confidence without condescension.
+2. **Educational without patronizing.** Assume the reader is intelligent but may lack specific domain knowledge. Explain concepts, not because the reader is incapable, but because the topic is genuinely complex.
+3. **Evidence-driven, not opinion-driven.** State facts, cite sources, present data. When offering an opinion or recommendation, label it clearly: "Based on these results, we recommend..." or "In our experience..."
+4. **Calm and measured.** Avoid hype, urgency, or sensationalism. Let the content's value speak for itself. "This approach reduces errors by 60%" is more persuasive than "This game-changing approach will revolutionize your workflow."

package/templates/_opencrew/core/best-practices/twitter-post.md

@@ -0,0 +1,122 @@
+---
+name: "Twitter/X Post"
+platform: "twitter"
+content_type: "post"
+description: "Single tweets and quote tweets optimized for engagement, bookmarks, and algorithmic reach"
+whenToUse: |
+  Creating agents that produce tweets, quote tweets, or single posts for X/Twitter.
+constraints:
+  tweet_max_chars: 280
+  effective_chars: 260
+  hashtags_max: 3
+  recommended_hashtags: "2-3"
+  images_per_tweet: 4
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Front-load value in the first 5-8 words to immediately capture attention.
+2. Focus on exactly one clear idea per tweet; if you have multiple points, write a thread instead.
+3. Aim for ~260 effective characters to leave room for hashtags.
+4. Strategically use line breaks to improve readability and create natural dwell time.
+5. Limit hashtags to 2-3 specific/niche tags placed at the very end of the tweet.
+6. Never place external links in the tweet body; put them in a reply or use "link in bio."
+7. End with a question, bold statement, or implication that invites replies and engagement.
+8. Attach images or videos whenever possible to significantly boost algorithmic impressions.
+9. When quote tweeting, add your own unique insight or data rather than just agreeing.
+10. Reply to comments within the first 15-30 minutes to maximize early algorithmic momentum.
+11. Post on weekdays (Tuesday-Thursday) between 8-10 AM or 12-1 PM EST for B2B/professional content.
+12. Limit posting frequency to a sustainable 1-3 tweets per day.
+
+<!-- End Compact Rules. Full reference below. -->
+
+## Platform Rules
+
+- Engagement is weighted: Replies > Bookmarks > Retweets > Likes. Design tweets that provoke replies and are worth bookmarking.
+- Tweets with images or video get significantly more impressions than text-only tweets. Always consider whether a visual element strengthens the tweet.
+- The algorithm penalizes tweets with external links in the body. Links reduce distribution. Post the link in a reply instead or use the "link in bio" approach.
+- Early engagement in the first 15-30 minutes is critical. The algorithm tests your tweet with a small audience first, then expands based on engagement velocity.
+- Dwell time matters. Tweets that make people stop scrolling and read get algorithmic boosts. Multi-line tweets with line breaks create natural dwell time.
+- Tweets from accounts that actively reply to others get higher baseline reach. Engagement is a two-way signal.
+- Best posting times: 8-10 AM EST or 12-1 PM EST on weekdays. Tuesday through Thursday for professional and B2B content. Saturday morning works for casual content.
+- Frequency: 1-3 tweets per day is a sustainable, high-performing cadence.
+
+## Content Structure
+
+### Single Tweet Formats
+
+- **Hot take**: Contrarian opinion that sparks debate. "Most people think X. The truth is Y."
+- **Question**: Simple, relatable question that invites replies. "What is the one thing you wish you knew about [topic]?"
+- **Listicle**: "5 things I learned about X:" followed by a numbered list, one item per line.
+- **Quote + take**: Share a quote and add your unique perspective in 1-2 sentences.
+- **Data point**: One surprising stat with your interpretation. "[Stat]. Here is what most people miss:"
+- **Before/After**: Contrast two states or perspectives. "Before: [old way]. Now: [new insight]."
+
+### Quote Tweet Structure
+
+1. Highlight the key point from the original tweet.
+2. Add your unique angle, experience, or data.
+3. Keep under 200 characters to leave room for the quoted content's context.
+
+### Tweet Anatomy
+
+- **Opening words** — The first 5-8 words decide whether someone reads further. Front-load the value or tension.
+- **Body** — One idea only. Develop it clearly in 1-3 sentences maximum.
+- **Closer** — A question, bold statement, or implication that invites engagement.
+
+## Writing Guidelines
+
+- **One idea per tweet.** Clarity beats cleverness. If you need multiple points, write a thread instead.
+- Front-load the value. The first few words of the tweet determine whether someone reads the rest. Start with the strongest word or phrase.
+- Use line breaks strategically for readability. A tweet formatted as 2-3 short lines reads better than one dense paragraph.
+- Leave approximately 20 characters of headroom for hashtags. Aim for ~260 effective characters of content.
+- Use 2-3 hashtags maximum. Place them at the end of the tweet or weave them naturally into the text. More than 3 hashtags signals low-quality content.
+- Focus on industry/topic-specific hashtags, not generic ones. #ContentStrategy beats #Success.
+- When quote tweeting, add genuine insight. Not "This!" or "So true." Add your experience, a counter-point, or additional data.
+- Write tweets that invite replies: questions, fill-in-the-blank prompts, "unpopular opinion" takes, and debate-starting claims.
+- Reply to comments on your tweets within the first hour to boost algorithmic momentum.
+
+## Output Format
+
+```
+=== TWEET ===
+[Tweet text — max 280 characters. Front-load value. One clear idea. Use line breaks for readability.]
+
+=== HASHTAGS ===
+#hashtag1 #hashtag2
+[2-3 hashtags, placed at the end of the tweet or noted separately]
+
+=== IMAGE (optional) ===
+[Image description — what the visual shows, composition, text overlay if any]
+[Alt text for accessibility — max 1,000 characters]
+
+=== QUOTE TWEET (if applicable) ===
+[URL or reference to the original tweet being quoted]
+[Your commentary — max 200 characters to leave room for context]
+```
+
+## Quality Criteria
+
+- [ ] Tweet is 280 characters or fewer, with ~260 characters of content leaving room for hashtags
+- [ ] First 5-8 words create enough interest to finish reading the tweet
+- [ ] Tweet contains exactly one clear idea, not multiple crammed together
+- [ ] Hashtags are 2-3 maximum and topic-specific, not generic
+- [ ] No external links appear in the tweet body (links go in replies)
+- [ ] Tweet is formatted with line breaks for readability where appropriate
+- [ ] Content invites a reply, bookmark, or retweet through its framing
+- [ ] Quote tweets (if used) add genuine insight, not just agreement
+- [ ] Image alt text is included if an image is attached
+- [ ] Tweet avoids filler words and gets to the point immediately
+
+## Anti-Patterns
+
+- **Links in tweet body** — Dramatically reduces reach due to algorithmic suppression. Post the link as a reply or use "link in bio."
+- **Excessive emojis** — More than 2-3 emojis per tweet looks unprofessional and reduces credibility in professional niches.
+- **Hashtag spam** — More than 3 hashtags per tweet signals low-quality content and reduces engagement rather than increasing it.
+- **Reposting the same content verbatim** — The algorithm detects duplicate content and suppresses it. Rephrase or add new context when revisiting a topic.
+- **Not engaging with replies** — Failing to respond to comments signals to the algorithm that your content does not generate real conversation, reducing future distribution.
+- **Using URL shorteners** — Twitter/X already shortens links. Third-party shorteners look suspicious and may be flagged as spam.
+- **Auto-cross-posting from other platforms** — Truncated content and broken formatting from Instagram or LinkedIn cross-posts damage credibility and get no engagement.
+- **Cramming multiple ideas into one tweet** — A tweet trying to cover 3 topics communicates none of them effectively. If you have multiple points, use a thread.
+- **Posting during major breaking news** — Your content will be buried under breaking news engagement. Check current events before posting.

package/templates/_opencrew/core/best-practices/twitter-thread.md

@@ -0,0 +1,139 @@
+---
+name: "Twitter/X Thread"
+platform: "twitter"
+content_type: "thread"
+description: "Multi-tweet threads optimized for long-form storytelling, education, and sustained engagement"
+whenToUse: |
+  Creating agents that produce Twitter/X threads or multi-tweet narratives.
+constraints:
+  tweet_max_chars: 280
+  optimal_thread_length: "5-15 tweets"
+  hashtags: "only on first tweet"
+version: "1.0.0"
+---
+
+## Compact Rules
+
+1. Write a standalone, compelling hook for Tweet 1; it determines the success of the entire thread.
+2. Keep threads between 5-15 tweets; engagement drops sharply beyond 15.
+3. Number every tweet (e.g., 1/10 or 1/N) so readers understand the total length.
+4. Ensure each tweet contains exactly one complete thought; never split sentences across tweets.
+5. Limit hashtags (2-3 max) to the first tweet only to avoid a spammy appearance.
+6. Write conversationally, using "I", contractions, and short sentences.
+7. Summarize the 3-5 key takeaways in bullet points in the second-to-last tweet.
+8. Include a clear CTA in the final tweet asking readers to retweet the first tweet, follow, or bookmark.
+9. Place any external links exclusively in the final tweet or as a reply below the thread.
+10. Reply to comments on the thread within the first hour to boost algorithmic visibility.
+11. Avoid posting during low-traffic hours or major breaking news cycles.
+12. Reply to your own thread within an hour to add summary or context and boost visibility.
+
+<!-- End Compact Rules. Full reference below. -->
+
+## Platform Rules
+
+- Threads receive 2-3x more impressions than standalone tweets. The multi-tweet format increases dwell time and creates multiple engagement touchpoints.
+- Engagement is weighted: Replies > Bookmarks > Retweets > Likes. Threads that are bookmark-worthy (educational, reference-quality) get sustained distribution.
+- Early engagement on the first tweet (first 15-30 minutes) is critical. If the first tweet does not perform, the thread's remaining tweets receive limited distribution.
+- Replying to your own tweet within 1 hour can boost the thread's visibility. Consider adding a summary or additional context as a self-reply.
+- The algorithm penalizes tweets with external links. If including links, place them in the final tweet or as a reply below the thread.
+- Threads from accounts that actively engage with others' content get higher baseline reach.
+- Best posting times: 8-10 AM EST or 12-1 PM EST on weekdays, particularly Tuesday through Thursday. Threads need immediate engagement to gain traction, so timing matters more than for standalone tweets.
+- Avoid posting threads during low-traffic hours or major breaking news cycles.
+
+## Content Structure
+
+### Thread Architecture
+
+1. **Hook tweet (Tweet 1/N)** — The most important tweet. It must stand completely alone as a compelling, self-contained statement. This is what appears in the feed and determines whether anyone reads further. Bold claim, surprising stat, or "Here is what I learned from..." format.
+2. **Context tweet (Tweet 2/N)** — Brief background establishing why this matters and who should keep reading. Sets the stage for the body.
+3. **Body tweets (Tweets 3-N-2)** — One insight, point, or story beat per tweet. Numbered for progress tracking. Each tweet should deliver standalone value while advancing the larger narrative.
+4. **Summary tweet (Tweet N-1)** — Recap the key takeaways in bullet points. This is the second most bookmarked tweet in a thread after the first.
+5. **CTA tweet (Tweet N/N)** — Ask for a follow, retweet of the first tweet for reach, or bookmark for reference. Include a link back to the first tweet for easy sharing.
+
+### Tweet-Level Structure
+
+- Each individual tweet in the thread should be a complete thought. Avoid splitting a sentence across two tweets.
+- Use numbering format (1/10, 2/10... or 1., 2., 3...) so readers know the thread length and their progress.
+- Start each tweet with the key point, then support it. Do not bury the insight at the end.
+
+Thread length: 5-8 tweets for focused insights, 9-12 for comprehensive breakdowns, 13-15 maximum. Beyond 15, engagement drops sharply. Never pad to hit a target length.
+
+## Writing Guidelines
+
+- **The first tweet is everything.** It must be compelling as a standalone tweet. If someone only sees tweet 1 and never clicks the thread, it should still deliver value or create irresistible curiosity.
+- Number every tweet so readers know the thread length. "1/10" or "(1)" format both work. Knowing the length helps readers decide to commit.
+- One point per tweet. Do not cram multiple ideas into a single tweet. Each tweet should feel like a self-contained insight with a clear beginning and end.
+- Use the last tweet for a summary and CTA. Recap the 3-5 key points in bullet format, then ask for a follow, retweet of the first tweet, or bookmark.
+- Use hashtags only on the first tweet. Hashtags on every tweet in a thread look spammy and reduce readability. 2-3 relevant hashtags on tweet 1 is sufficient.
+- Write conversationally. Threads are a storytelling format. Use "I" instead of "one," contractions instead of formal language, and short sentences instead of complex ones.
+- Include a "retweet the first tweet" call to action in the final tweet. This is the primary sharing mechanism for threads and extends reach significantly.
+- Keep each tweet under 280 characters but aim for substance. A tweet that is only 40 characters feels like padding.
+- Reply to comments on the thread within the first hour. Engagement velocity in the early window determines total distribution.
+
+## Output Format
+
+```
+=== THREAD ===
+TWEET 1/N (Hook):
+[Standalone compelling statement — bold claim, surprising stat, or curiosity gap. Must work even if no one reads the rest. Max 280 chars.]
+
+#hashtag1 #hashtag2
+
+TWEET 2/N (Context):
+[Why this matters. Who should read this. Brief background. Max 280 chars.]
+
+TWEET 3/N (Point 1):
+[First key insight — one clear point with support. Max 280 chars.]
+
+TWEET 4/N (Point 2):
+[Second key insight — one clear point with support. Max 280 chars.]
+
+TWEET 5/N (Point 3):
+[Third key insight — one clear point with support. Max 280 chars.]
+
+...
+
+TWEET (N-1)/N (Summary):
+Key takeaways:
+- [Takeaway 1]
+- [Takeaway 2]
+- [Takeaway 3]
+
+TWEET N/N (CTA):
+[If this was valuable, retweet tweet 1 to share it with your audience.
+
+Follow @[handle] for more on [topic].
+
+Bookmark this thread for reference.]
+
+=== THREAD NOTES ===
+Total tweets: [N]
+Primary topic: [Topic]
+Target audience: [Who this is for]
+```
+
+## Quality Criteria
+
+- [ ] First tweet works as a compelling standalone statement, even without the rest of the thread
+- [ ] Thread is 5-15 tweets long (not shorter, not longer)
+- [ ] Every tweet contains exactly one clear point or insight
+- [ ] Tweets are numbered (1/N format) so readers know the length
+- [ ] Hashtags appear only on the first tweet (2-3 maximum)
+- [ ] No tweet splits a sentence across tweet boundaries
+- [ ] Summary tweet recaps key takeaways in bullet format
+- [ ] Final tweet includes a CTA: retweet tweet 1, follow, or bookmark
+- [ ] No external links in tweet bodies (links go in the final tweet or a reply)
+- [ ] Each tweet delivers standalone value while advancing the thread's narrative
+
+## Anti-Patterns
+
+- **Thread with no hook** — Starting with "Thread on [topic]:" without any compelling reason to read guarantees low engagement. The first tweet must create curiosity or deliver a striking insight.
+- **Threads longer than 15 tweets** — Engagement drops sharply after tweet 12-15. Readers lose interest and stop scrolling. If your content requires more, split into multiple threads.
+- **Splitting sentences across tweets** — "And the most important thing is... (2/10) ...that you always start early." This creates a disjointed reading experience and frustrates readers who see individual tweets out of context.
+- **Hashtags on every tweet** — Using hashtags on all tweets in a thread looks spammy and clutters the reading experience. Limit hashtags to tweet 1 only.
+- **No numbering** — Without numbering, readers do not know how long the thread is and cannot gauge their commitment. Always number tweets.
+- **Links in tweet bodies** — External links reduce distribution. Save links for the final tweet or post them as a reply below the thread.
+- **Not engaging with replies** — A thread that generates replies but gets no author responses signals to the algorithm that the conversation is one-directional.
+- **Posting threads at low-traffic hours** — Threads depend on immediate engagement velocity more than standalone tweets. Posting at 11 PM on a Sunday kills distribution.
+- **Padding with filler tweets** — Tweets like "Let me explain..." without actual content waste reader attention and feel artificially inflated.
+- **Reposting the same thread verbatim** — The algorithm detects duplicates. If revisiting a topic, rewrite with new framing or updated data.