expxagents 0.1.0

package/assets/core/best-practices/api-documentation.md

@@ -0,0 +1,137 @@
+---
+platform: software-house
+format: api-documentation
+constraints:
+  max_chars: null
+  image_ratio: null
+  max_hashtags: null
+---
+
+# Best Practices: API Documentation
+
+## Core Principles
+
+API documentation is the contract between your service and every developer who integrates with it. Incomplete or inaccurate docs erode trust and generate avoidable support tickets.
+
+- **Docs are part of the product.** Treat documentation as a shippable feature with the same quality bar as code.
+- **Show, don't just tell.** Every endpoint needs a working example request and response.
+- **Keep docs in sync with code.** Stale documentation is worse than no documentation — it actively misleads.
+- **Docs-as-code:** Version API docs alongside the API code; review documentation changes in the same PR.
+
+## OpenAPI / Swagger Standard
+
+Use OpenAPI 3.1 (preferred) or OpenAPI 3.0 as the specification format. All endpoints should be described in a machine-readable `openapi.yaml` or `openapi.json` file.
+
+### Required Fields Per Endpoint
+
+```yaml
+/users/{id}:
+  get:
+    summary: Get a user by ID
+    description: |
+      Returns a single user object. Requires authentication.
+      Returns 404 if the user does not exist.
+    operationId: getUserById
+    tags:
+      - Users
+    parameters:
+      - name: id
+        in: path
+        required: true
+        description: The unique identifier of the user
+        schema:
+          type: string
+          format: uuid
+          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+    responses:
+      "200":
+        description: User found
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/User"
+            example:
+              id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+              email: "jane@example.com"
+              name: "Jane Doe"
+              createdAt: "2024-01-15T10:30:00Z"
+      "401":
+        $ref: "#/components/responses/Unauthorized"
+      "404":
+        $ref: "#/components/responses/NotFound"
+```
+
+## Documentation Structure
+
+```
+[OVERVIEW]
+- What the API does and who it is for
+- Base URL(s) per environment
+- Versioning strategy (URL path, header, or query param)
+
+[AUTHENTICATION]
+- Auth method (API key, OAuth 2.0, JWT)
+- How to obtain credentials
+- How to send credentials (header, query param)
+- Token expiration and refresh procedure
+
+[RATE LIMITING]
+- Limits per plan or tier
+- Rate limit response headers
+- Retry strategy (exponential backoff with jitter)
+
+[ERRORS]
+- Standard error response format
+- Complete list of error codes and their meaning
+- Troubleshooting common errors
+
+[ENDPOINTS]
+For each endpoint:
+- Method and path
+- Summary and description
+- Request parameters (path, query, header, body)
+- Request body schema with all fields documented
+- Response codes and schemas
+- Working code example (curl, minimum one SDK)
+
+[CHANGELOG / API VERSIONING]
+- Breaking vs. non-breaking changes
+- Deprecation policy and timeline
+- Migration guides for version upgrades
+
+[SDKS AND CLIENT LIBRARIES]
+- Official SDK links
+- Community SDK links
+- Quickstart guides
+```
+
+## Guidelines
+
+- Every field in every schema must have: type, description, whether required, and an example value.
+- Document the null/empty behavior explicitly: "Returns null if not set" vs. "Field omitted from response if not set."
+- Error responses must be documented with the same rigor as success responses.
+- Authentication: include a working, copy-paste-ready curl command in the auth section.
+- Pagination: document the pagination strategy (cursor, offset, page) with examples of first page, next page, and last page.
+- Webhooks: document payload schema, signature verification, retry logic, and idempotency.
+- Keep examples realistic — use plausible fake data, not `foo`, `bar`, `test123`.
+- Provide a Postman collection or Insomnia workspace as a downloadable artifact.
+
+## Error Response Standard
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "The 'email' field is required and must be a valid email address.",
+    "details": [
+      {
+        "field": "email",
+        "issue": "required",
+        "value": null
+      }
+    ],
+    "requestId": "req_7f3a9b2c1d",
+    "docsUrl": "https://docs.example.com/errors/VALIDATION_ERROR"
+  }
+}
+```

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

@@ -0,0 +1,86 @@
+---
+platform: blog
+format: article
+constraints:
+  max_chars: null
+  image_ratio: "16:9"
+  max_hashtags: null
+---
+
+# Best Practices: Blog — Article
+
+## Format Rules
+
+- Ideal word count: 1500–3000 words for informational content; 800–1200 for opinion/news pieces
+- Title (H1): once, at the top; 50–60 characters for SEO display
+- H2 headers: 3–7 per article; include secondary keywords naturally
+- H3 headers: used for sub-points under H2 sections
+- Featured image: 1200x628px (16:9); include descriptive alt text with keyword
+- Meta description: 150–160 characters summarizing the article with a CTA
+- Reading time: aim for 5–8 minutes (800–1500 words at ~200 wpm average)
+- Internal links: 2–5 per article pointing to related content on the same site
+- External links: 1–3 authoritative sources (open in new tab)
+
+## Structure
+
+```
+[H1 TITLE — primary keyword near the front]
+
+[INTRODUCTION — 100–150 words]
+- Hook: question, statistic, or bold claim
+- State the problem clearly
+- Promise: "In this article you'll learn..."
+
+[H2 SECTION 1 — first major topic]
+[H3 sub-section if needed]
+[150–300 words per H2 section]
+[Include: one image or visual, one example or data point]
+
+[H2 SECTION 2]
+...
+
+[H2 SECTION N — practical steps or application]
+[Use numbered lists or a step-by-step format here]
+
+[H2 FREQUENTLY ASKED QUESTIONS (optional but SEO-valuable)]
+[3–5 Q&A pairs targeting long-tail search queries]
+
+[CONCLUSION — 100–150 words]
+- Summarize key takeaways
+- Reinforce main message
+- CTA: newsletter, related article, product, or comment question
+```
+
+## Guidelines
+
+- **Write for humans first, then optimize for search.** Content that solves a real problem ranks because it earns links and time-on-page.
+- Put the most important information first (inverted pyramid). Readers scroll but rarely finish.
+- Use short sentences (under 25 words), short paragraphs (3–4 lines max), and ample white space.
+- Bold key phrases, not entire sentences. Bold is a scannable emphasis tool.
+- Every H2 section should be comprehensible on its own — readers jump around.
+- Use original visuals, charts, or screenshots rather than stock photos wherever possible.
+- Update old articles to keep them current — freshness signals matter for rankings.
+- Internal linking strategy: link new posts to cornerstone content, and update cornerstone content to link to new posts.
+
+## Examples
+
+**Introduction template:**
+```
+[Stat or provocative question].
+
+If you've been [doing the common thing], you're not alone — but you might be leaving [result] on the table.
+
+In this guide, I'll walk you through [topic], covering:
+- [Point 1]
+- [Point 2]
+- [Point 3]
+
+Let's dive in.
+```
+
+**FAQ entry:**
+```
+### How long does [process] take?
+
+Most people see [result] within [timeframe]. The key variable is [factor]. If you follow the steps in Section 2, you can cut that time significantly.
+```

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

@@ -0,0 +1,91 @@
+---
+platform: blog
+format: seo-content
+constraints:
+  max_chars: null
+  image_ratio: "16:9"
+  max_hashtags: null
+---
+
+# Best Practices: Blog — SEO-Optimized Content
+
+## Format Rules
+
+- Title tag: 50–60 characters; primary keyword in the first 3 words when possible
+- Meta description: 150–160 characters; include primary keyword and a clear benefit
+- URL slug: lowercase, hyphens only, primary keyword only (e.g., `/best-crm-software`)
+- H1: exact match or close variant of the target keyword; use only once
+- Keyword density: 1–2% naturally placed; avoid keyword stuffing
+- Image alt text: descriptive and keyword-contextual (not just the keyword alone)
+- Schema markup: Article or HowTo schema for rich snippets
+- Page speed: target Core Web Vitals — LCP < 2.5s, CLS < 0.1, FID < 100ms
+
+## Structure
+
+```
+[TITLE TAG — primary keyword first]
+
+[META DESCRIPTION — keyword + benefit + CTA under 160 chars]
+
+[H1 — matches or closely mirrors title tag]
+
+[INTRODUCTION]
+- Mention primary keyword in first 100 words
+- Acknowledge the search intent (informational, commercial, transactional)
+
+[TABLE OF CONTENTS — for articles over 1500 words; improves dwell time]
+
+[H2 SECTIONS — secondary and LSI keywords as H2 headers]
+- Each H2 targets a related search query
+- 200–400 words per section
+
+[H2 FAQ SECTION]
+- Target "People Also Ask" queries from Google SERP
+- Question as H3, concise answer (40–60 words) immediately following
+
+[CONCLUSION with CTA]
+```
+
+## Guidelines
+
+- **Match search intent precisely.** Rank for the right audience by matching what someone actually wants when they type that query (informational, navigational, transactional, commercial investigation).
+- Use tools like Ahrefs, Semrush, or Google Search Console to identify the exact keyword phrase to target.
+- Cover the topic comprehensively — include sub-topics that competing articles address, then add unique depth they don't.
+- Build topical authority: create a cluster of 5–15 related articles all linking to one cornerstone page on the topic.
+- Earn backlinks through original data, studies, quotes from experts, or unique tools embedded in the page.
+- E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness): include author bios, cite sources, show real experience.
+- Structured data (JSON-LD): implement Article, BreadcrumbList, and FAQPage schema where relevant.
+- Internal link anchor text should be descriptive and keyword-relevant, not generic ("click here").
+
+## Examples
+
+**Meta description:**
+```
+Discover the 7 best project management tools in 2024 — compared by price, features, and team size. Find the right fit in under 5 minutes.
+```
+
+**FAQPage schema example (JSON-LD):**
+```json
+{
+  "@context": "https://schema.org",
+  "@type": "FAQPage",
+  "mainEntity": [{
+    "@type": "Question",
+    "name": "What is the best CRM for small businesses?",
+    "acceptedAnswer": {
+      "@type": "Answer",
+      "text": "HubSpot CRM is the top choice for small businesses due to its free tier, ease of use, and robust integrations."
+    }
+  }]
+}
+```
+
+**Keyword placement checklist:**
+- [ ] Title tag (first 3 words)
+- [ ] Meta description (natural inclusion)
+- [ ] H1 header
+- [ ] First paragraph (within 100 words)
+- [ ] At least one H2 header
+- [ ] Image alt text
+- [ ] URL slug
+- [ ] Conclusion paragraph

package/assets/core/best-practices/code-review.md

@@ -0,0 +1,97 @@
+---
+platform: software-house
+format: code-review
+constraints:
+  max_chars: null
+  image_ratio: null
+  max_hashtags: null
+---
+
+# Best Practices: Code Review
+
+## Core Principles
+
+Code review is a quality gate, a knowledge-sharing mechanism, and a communication process. It protects the codebase and grows the team simultaneously.
+
+- **Review code, not the person.** Feedback targets the implementation, not the developer.
+- **Be constructive and specific.** "This could be cleaner" is not actionable. "Extract this logic into a `calculateTax()` function to make it reusable and testable" is.
+- **Approve or block — don't be a passive reviewer.** An ambiguous review is worse than no review.
+- **Small PRs, fast reviews.** Prefer many small reviews over one massive review that nobody reads carefully.
+
+## What to Review
+
+### Correctness
+- Does the code do what the PR description claims?
+- Are edge cases and error paths handled?
+- Are inputs validated where they enter the system?
+- Are there potential null pointer exceptions, off-by-one errors, or race conditions?
+
+### Design and Architecture
+- Is the solution appropriately simple? Over-engineering is a real defect.
+- Does the code follow the existing architectural patterns of the codebase?
+- Are responsibilities well separated (single responsibility principle)?
+- Is there appropriate abstraction — not too much, not too little?
+
+### Performance
+- Are there N+1 query patterns or unnecessary loops?
+- Are expensive operations (DB calls, API requests) performed in tight loops?
+- Is caching used appropriately?
+
+### Security
+- Is user input sanitized and validated?
+- Are secrets hardcoded? (Should trigger immediate blocking)
+- Are authorization checks in place for all sensitive operations?
+- Is SQL/NoSQL injection prevented?
+
+### Tests
+- Do new features have unit tests?
+- Are edge cases tested?
+- Do tests actually assert the right things (not just that something runs without throwing)?
+
+### Readability and Maintainability
+- Is the code understandable without requiring the author to explain it?
+- Are variable and function names descriptive?
+- Are complex sections commented with the *why*, not just the *what*?
+
+## Review Comment Taxonomy
+
+Use a prefix to clarify the type of feedback:
+
+| Prefix | Meaning |
+|--------|---------|
+| `nit:` | Minor style preference; non-blocking |
+| `suggestion:` | Improvement idea; take it or leave it |
+| `question:` | Genuine question; not necessarily a problem |
+| `issue:` | Must be resolved; blocking approval |
+| `blocker:` | Critical problem; cannot merge |
+
+## Structure (PR Description Template)
+
+```markdown
+## What this PR does
+[1–3 sentence summary of the change]
+
+## Why
+[Link to ticket / business context]
+
+## How to test
+1. [Step 1]
+2. [Step 2]
+3. Expected result: [description]
+
+## Checklist
+- [ ] Unit tests added or updated
+- [ ] No secrets or hardcoded values
+- [ ] Documentation updated (if applicable)
+- [ ] Breaking changes noted in CHANGELOG
+```
+
+## Guidelines
+
+- Respond to all PR comments before requesting re-review — do not leave threads hanging.
+- A PR with more than 400 lines of diff is too large. Break it up.
+- Review within 24 hours of request during business hours — blocking others is a team cost.
+- The author should explain the *why* in the PR description; the reviewer should not have to ask.
+- Self-review before requesting others: re-read your own diff in GitHub/GitLab before clicking "Request Review."
+- Automated checks (linting, tests, type-checking) must pass before human review begins.
+- Approve only code you actually understand — "Looks good to me" without reading is not a review.

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

@@ -0,0 +1,75 @@
+---
+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

@@ -0,0 +1,93 @@
+---
+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

@@ -0,0 +1,99 @@
+---
+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 |