expxagents 0.24.2 → 0.25.1

package/assets/core/best-practices/copywriting.md

@@ -1,75 +0,0 @@
----
-platform: universal
-format: copywriting
-constraints:
-  max_chars: null
-  image_ratio: null
-  max_hashtags: null
----
-
-# Best Practices: Copywriting
-
-## Core Principles
-
-Copywriting is the craft of using words to move people toward a specific action. Every word must earn its place by advancing clarity, credibility, or conversion.
-
-- **One reader, one message.** Write to a single, specific person — not a demographic.
-- **Benefits, not features.** Features describe what something is; benefits describe what it does for the reader.
-- **The customer is the hero.** Your product is the guide. Their transformation is the story.
-- **Clarity beats cleverness.** If a reader has to work to understand you, they won't convert.
-
-## The Fundamental Frameworks
-
-### AIDA
-- **Attention** — Stop the scroll with a powerful hook
-- **Interest** — Make the reader care about the problem
-- **Desire** — Show them what life looks like with the solution
-- **Action** — Tell them exactly what to do next
-
-### PAS
-- **Problem** — Name the pain precisely
-- **Agitate** — Expand the problem; make it feel real and urgent
-- **Solution** — Present your offer as the clear path forward
-
-### FAB
-- **Feature** — What the product does
-- **Advantage** — Why that feature matters
-- **Benefit** — What that means for the reader personally
-
-## Structure
-
-```
-[HEADLINE — primary promise or hook]
-[SUBHEADLINE — supports or expands the headline]
-
-[OPENING — agitate the pain or amplify the desire]
-[BRIDGE — introduce the solution category]
-[PROOF — social proof, testimonials, data, or demonstration]
-[OFFER — what they get, when, for how much]
-[OBJECTION HANDLING — preemptively answer "but what about..."]
-[CTA — one clear next step with urgency or specificity]
-```
-
-## Guidelines
-
-- Write headlines that include: a number, a specific benefit, or a curiosity trigger.
-- Lead with the reader's world, not yours. Open with their pain or desire.
-- Use sensory, concrete language: "cut your workload in half" beats "improve efficiency."
-- Social proof should be specific: name, company, measurable result.
-- Reduce friction in CTAs: "Start my free trial" > "Sign up" > "Submit"
-- Read your copy aloud — if it sounds stiff, rewrite it until it flows.
-- Every paragraph should make the next one feel necessary.
-
-## Examples
-
-**Weak vs. strong headlines:**
-- Weak: "Our software helps teams collaborate better"
-- Strong: "Your team will ship 30% faster — or you don't pay"
-
-**Weak vs. strong CTA:**
-- Weak: "Learn more"
-- Strong: "Get instant access — no credit card required"
-
-**Testimonial (weak vs. strong):**
-- Weak: "Great product! Highly recommend."
-- Strong: "I went from 3 clients to 11 in 60 days after implementing this system. Worth every penny." — Sarah M., Freelance Designer

package/assets/core/best-practices/data-analysis.md

@@ -1,93 +0,0 @@
----
-platform: universal
-format: data-analysis
-constraints:
-  max_chars: null
-  image_ratio: null
-  max_hashtags: null
----
-
-# Best Practices: Data Analysis and Reporting
-
-## Core Principles
-
-Data analysis turns raw numbers into decisions. The goal is not to describe what happened, but to explain why it happened and recommend what to do next.
-
-- **Start with a question, not a dataset.** Analysis without a question produces observations, not insights.
-- **Distinguish correlation from causation.** Two metrics moving together does not mean one causes the other.
-- **Insight = What + So what.** "Conversions dropped 20%" is a finding. "Conversions dropped 20% because landing page load time increased after the deploy" is an insight.
-
-## Analysis Process
-
-### Step 1: Define the Question
-- Business question: "Why did revenue drop in Q3?"
-- Analytical question: "Which segment, channel, or product drove the Q3 revenue decline?"
-- Success metric: "The analysis is complete when we can name the primary causal factor and its magnitude."
-
-### Step 2: Data Collection and Validation
-- Identify data sources and their freshness
-- Check for null values, duplicates, and outliers
-- Validate against a known baseline or external benchmark
-- Document data limitations upfront
-
-### Step 3: Exploratory Analysis
-- Summarize distributions: mean, median, standard deviation
-- Look for trends over time
-- Segment by key dimensions (geography, product, cohort, channel)
-- Identify anomalies and investigate their cause
-
-### Step 4: Hypothesis Testing
-- State a hypothesis: "We believe [X] caused [Y] because [Z]"
-- Select appropriate statistical test (t-test, chi-square, regression)
-- Set significance threshold (p < 0.05 for most business contexts)
-- Interpret results — significance does not always mean practical importance
-
-### Step 5: Visualization
-- Choose chart type by relationship:
-  - Trends over time: line chart
-  - Comparisons: bar chart
-  - Composition: stacked bar or pie (use pie only for 2–4 categories)
-  - Distribution: histogram or box plot
-  - Correlation: scatter plot
-
-### Step 6: Communication
-- Lead with the insight, not the methodology
-- Use the "So What" test on every finding
-- Present data in the audience's language, not the analyst's
-
-## Structure (Analysis Report)
-
-```
-[EXECUTIVE SUMMARY — 3–5 bullet points max]
-- The question
-- The key finding
-- The recommended action
-
-[CONTEXT AND METHODOLOGY]
-- Data sources, date range, sample size
-- Limitations and caveats
-
-[FINDINGS]
-- Finding 1: [Insight + supporting data]
-- Finding 2: ...
-- [Charts and tables with clear titles and labeled axes]
-
-[ROOT CAUSE ANALYSIS]
-- Causal chain or contributing factors
-
-[RECOMMENDATIONS]
-- Action 1: [What to do] — Owner: [who] — Timeline: [when]
-- Action 2: ...
-
-[APPENDIX — raw tables, methodology detail]
-```
-
-## Guidelines
-
-- Every chart must have: a title that states the insight (not just the metric), labeled axes, a data source note, and a date range.
-- Never present a single number without context: comparison to prior period, target, or benchmark.
-- Round numbers appropriately for the audience: executives get "~$2M", analysts get "$1,847,320."
-- Avoid 3D charts — they distort perception of values.
-- Confidence intervals: always show uncertainty in forecasts and statistical estimates.
-- Reproducibility: document data sources, transformations, and calculations so the analysis can be replicated.
-- For dashboards: limit to 5–7 KPIs per view; group related metrics; use consistent color coding.

package/assets/core/best-practices/deploy-checklist.md

@@ -1,99 +0,0 @@
----
-platform: software-house
-format: deploy-checklist
-constraints:
-  max_chars: null
-  image_ratio: null
-  max_hashtags: null
----
-
-# Best Practices: Deployment Checklist and Runbook
-
-## Core Principles
-
-Deployments should be boring. A well-defined checklist eliminates cognitive load, reduces human error, and makes rollback a fast, practiced operation — not a panic.
-
-- **Never deploy on Fridays.** Changes need observation time; deploy when the full team is available to respond.
-- **Every deploy is a risk.** Mitigate it with incremental rollouts, feature flags, and observability.
-- **Runbook first.** If a deployment procedure is not written down, it does not exist reliably.
-
-## Pre-Deployment Checklist
-
-### Code and Build
-- [ ] All CI/CD pipeline checks passing (tests, linting, type checks, security scans)
-- [ ] PR reviewed and approved by at least one other engineer
-- [ ] Branch merged from up-to-date main/trunk
-- [ ] CHANGELOG updated with changes and version bump
-- [ ] No debug code, `console.log`, or temporary hacks remaining
-
-### Database and Data
-- [ ] Database migrations reviewed (are they reversible?)
-- [ ] Migration tested against a production-like dataset
-- [ ] No destructive schema changes without a data backup
-- [ ] Migration execution plan documented (run before or after deploy?)
-
-### Configuration and Secrets
-- [ ] All required environment variables set in target environment
-- [ ] No secrets committed to the repository
-- [ ] Third-party service credentials (API keys) valid and tested
-- [ ] Feature flags configured for the target environment
-
-### Rollback Plan
-- [ ] Rollback procedure documented: commands to revert deploy
-- [ ] Database rollback: is the migration reversible? If not, is there a compensating migration?
-- [ ] Rollback tested in staging (at minimum, the steps are verified as correct)
-- [ ] Team knows who is responsible for executing a rollback
-
-## Deployment Execution
-
-### During Deploy
-- [ ] Announce deploy start in the team communication channel
-- [ ] Monitor error rate and latency in real-time during rollout
-- [ ] Watch for new errors in the error tracking tool (Sentry, Datadog, etc.)
-- [ ] Pause or abort if error rate increases more than 5% above baseline
-
-### Post-Deployment Verification
-- [ ] Smoke test: manually verify the core user flow in production
-- [ ] Automated synthetic monitor alerts not triggered
-- [ ] Key metrics returning to expected values (conversion, error rate, latency p95)
-- [ ] Any affected external integrations verified (webhooks, third-party services)
-- [ ] Announce deploy completion in the team channel
-
-## Rollback Procedure
-
-```bash
-# Example rollback procedure for a containerized app
-# Step 1: Identify the last stable image tag
-docker image ls <image-name>
-
-# Step 2: Redeploy the previous version
-kubectl set image deployment/<app> app=<image>:<previous-tag>
-
-# Step 3: Monitor rollout
-kubectl rollout status deployment/<app>
-
-# Step 4: If database migration was run, execute rollback migration
-npm run migrate:down  # or equivalent
-
-# Step 5: Verify system health post-rollback
-# Run smoke tests and confirm error rate normalized
-```
-
-## Production Incident Response
-
-If a critical issue is discovered post-deploy:
-
-1. **Declare incident** — notify on-call and team channel immediately
-2. **Assess severity** — data loss? Revenue impact? % of users affected?
-3. **Rollback or hotfix** — default to rollback; hotfix only if rollback is slower or riskier
-4. **Communicate** — status page update within 5 minutes of a confirmed incident
-5. **Post-mortem** — within 48 hours: timeline, root cause, action items (blameless)
-
-## Deployment Frequency and Strategy
-
-| Risk Level | Strategy | Observation Period |
-|-----------|----------|--------------------|
-| Low (config change) | Direct deploy | 15 minutes |
-| Medium (new feature) | Canary rollout (5% → 20% → 100%) | 30 minutes per step |
-| High (data migration) | Blue/green with verification step | 2+ hours |
-| Critical (auth, payments) | Maintenance window, staged rollout | Full business day |

package/assets/core/best-practices/email-newsletter.md

@@ -1,84 +0,0 @@
----
-platform: email
-format: newsletter
-constraints:
-  max_chars: null
-  image_ratio: "600px-wide"
-  max_hashtags: null
----
-
-# Best Practices: Email — Newsletter
-
-## Format Rules
-
-- Subject line: 30–50 characters (mobile preview shows ~35 chars); avoid ALL CAPS and excessive punctuation
-- Preview text: 40–90 characters; extends the subject line narrative
-- Email width: 600px maximum for universal client rendering
-- Images: inline 600px wide; always include alt text for image-disabled clients
-- CTA buttons: minimum 44px height, 200px width; one primary CTA per section
-- Unsubscribe link: legally required (CAN-SPAM, GDPR) — include in footer
-- Plain text version: required alongside HTML for deliverability and accessibility
-- Send frequency: weekly or bi-weekly performs best for engagement; daily acceptable for daily-format newsletters
-
-## Structure
-
-```
-[FROM NAME] — Personal name or brand name (not "noreply@")
-[SUBJECT LINE] — Curiosity or value, not clickbait
-[PREVIEW TEXT] — Sentence that completes the subject line's promise
-
----
-
-[HEADER]
-- Logo or brand name
-- Issue number or date (builds ritual habit)
-
-[GREETING]
-- "Hi [First Name]," or "Hey," for conversational newsletters
-
-[INTRO — 2–3 sentences]
-- What's in this issue and why it matters
-
-[SECTION 1 — Main Story / Primary Value]
-- 150–300 words
-- One CTA button: [Read More] or [Get Access]
-
-[SECTION 2 — Secondary Content]
-- Curated link, quick tip, or community highlight
-- 50–100 words
-
-[SECTION 3 — Optional: sponsor or product mention]
-- Clearly labeled "Sponsored" or "From our partners"
-
-[FOOTER]
-- Unsubscribe | Preferences | View in browser
-- Mailing address (required legally)
-- Social links
-```
-
-## Guidelines
-
-- **Subject line determines open rate.** Split test at least 2 subject lines per send with 20%/20%/60% splits.
-- Use the reader's first name in the subject line sparingly — it works but loses impact if overused.
-- One primary CTA per email. Multiple equally-weighted CTAs reduce clicks on all of them.
-- Write in a consistent voice that matches a specific, recognizable personality. Subscribers subscribe to a person, not a publication.
-- Send at consistent times and days — subscribers form habits around your send schedule.
-- Re-engagement campaigns: email inactive subscribers (90+ days) with a re-confirm or goodbye sequence before purging.
-- Maintain list hygiene: remove hard bounces immediately; suppress soft bounces after 3 failures.
-- Deliverability: authenticate with SPF, DKIM, and DMARC; avoid spam trigger words; maintain list quality.
-
-## Examples
-
-**Subject line formulas:**
-- "[Number] things I learned from [unusual experience]"
-- "The [adjective] guide to [topic] (in 5 minutes)"
-- "Quick question for you..."
-- "[First Name], you might want to see this"
-
-**Preview text that extends the subject:**
-- Subject: "We need to talk about your content strategy"
-- Preview: "...because most people are building on the wrong foundation."
-
-**CTA button copy (strong vs. weak):**
-- Strong: "Get the free template", "Watch the 10-minute walkthrough", "Join 12,000 readers"
-- Weak: "Click here", "Learn more", "Submit"

package/assets/core/best-practices/email-sales.md

@@ -1,91 +0,0 @@
----
-platform: email
-format: sales
-constraints:
-  max_chars: null
-  image_ratio: null
-  max_hashtags: null
----
-
-# Best Practices: Email — Sales Email
-
-## Format Rules
-
-- Subject line: 6–10 words; curiosity or benefit-forward; never misleading
-- Length: 100–300 words for cold outreach; 300–600 for warm/nurture sequences
-- Paragraphs: 1–3 sentences each; wide white space between paragraphs
-- One CTA: one link or one ask per email — not multiple options
-- Personalization tokens: {first_name}, {company_name}, {role} at minimum
-- Signature: real name, role, company, phone number, and one social link
-- Images: minimal (can trigger spam filters); avoid in cold outreach
-
-## Structure — AIDA Framework
-
-```
-[SUBJECT LINE — curiosity or specific benefit]
-
-Hi {first_name},
-
-[ATTENTION — 1–2 sentences]
-- Specific, relevant hook: reference their company, a pain point, or a trigger event
-- NOT: "My name is X and I work at Y..."
-
-[INTEREST — 2–3 sentences]
-- Explain the problem you solve in concrete, non-jargon terms
-- Use numbers and specificity where possible: "We help [target persona] achieve [result] in [timeframe]"
-
-[DESIRE — 2–3 sentences]
-- Social proof: a customer name, outcome, or case study result
-- "We recently helped [similar company] [specific outcome]"
-
-[ACTION — 1 sentence]
-- Clear, low-friction ask
-- "Would you be open to a 15-minute call on Thursday or Friday?"
-- Avoid: "Let me know if you're interested" (too vague, puts effort on recipient)
-
-[SIGNATURE]
-{sender_name}
-{role} at {company}
-{phone}
-```
-
-## Guidelines
-
-- **The goal of every sales email is one thing: the reply.** Not the sale — the conversation.
-- Cold email subject lines should not look like marketing emails. They should look like emails from a person.
-- Personalize beyond {first_name}: reference a recent blog post, funding round, job posting, or product change.
-- Keep the first email short (under 150 words for cold). Earn the right to say more.
-- Follow-up sequence: 4–6 touches across 2–3 weeks. Persistence closes deals; abandonment is the #1 failure.
-- Never guilt-trip in follow-ups. Add new value: a case study, a relevant article, an offer.
-- A/B test: subject line, CTA wording, opening line, and send time.
-- Measure reply rate, not just open rate. Opens are vanity; replies are pipeline.
-
-## Examples
-
-**Cold outreach email:**
-```
-Subject: Idea for {company_name}'s onboarding flow
-
-Hi {first_name},
-
-I noticed {company_name} recently launched [feature/product] — congrats on the release.
-
-I work with SaaS teams to reduce onboarding drop-off after signup. One of our clients, [Company], cut their time-to-activation by 40% in 6 weeks using a method I'd love to walk you through.
-
-Would a 15-minute call this week or next work for you?
-
-[Name]
-```
-
-**Follow-up #2 (adding value):**
-```
-Subject: Re: Idea for {company_name}'s onboarding flow
-
-Hi {first_name},
-
-Following up on my last note — I wanted to share a short case study from [similar company] that you might find relevant: [link]
-
-Happy to apply the same approach to {company_name}. Worth a quick call?
-
-[Name]
-```