diff --git a/.agents/skills/blog/SKILL.md b/.agents/skills/blog/SKILL.md new file mode 100644 index 00000000..c0628848 --- /dev/null +++ b/.agents/skills/blog/SKILL.md @@ -0,0 +1,75 @@ +--- +name: blog +description: Draft, review, and publish a blog post for runcycles.io with full review cycles, SEO, fact-checking, and external research +user-invocable: true +--- + +# Blog Post Workflow + +When the user invokes `/blog "topic"` or asks to write a blog post, follow this complete workflow: + +## Phase 1: Setup +1. Create a new branch from main: `blog/` +2. Read 2-3 existing blog posts in `blog/` to calibrate tone and format +3. Search existing posts for related content, cross-link opportunities, and terminology to reuse +4. Check memory files for content strategy (what's been published, what gaps exist) + +## Phase 2: Research +5. Search the existing blog library for any content that overlaps with the topic +6. Identify cross-linking targets (aim for 5-8 internal links for pillar posts) +7. Research external sources: framework docs, industry papers, developer community discussions +8. Note any claims that will need external verification + +## Phase 3: Draft +9. Write the post following these standards: + - Frontmatter: title (<60 chars), date, author (Albert Mavashev), tags (use established corpus tags), description (150-160 chars with keywords), blog: true, sidebar: false, featured: false + - Filename: lowercase kebab-case, under 60 chars + - Open with a concrete problem or scenario, not theory + - Use tables and comparisons for complex topics + - Link to related posts contextually in prose + - Use canonical terminology: ALLOW/ALLOW_WITH_CAPS/DENY, reserve-commit, RISK_POINTS, runtime authority, action authority, authority attenuation + - End with resource links section +10. Save to `blog/.md` + +## Phase 4: Review Cycle 1 (parallel agents) +11. **Link verification:** Check every internal link resolves to an existing .md file +12. **Fact-check:** Verify all claims, dollar figures, and terminology against source posts +13. **SEO audit:** Title length, description length, keyword coverage (guardrails, production, security, risk, graceful degradation as relevant), heading structure, tag alignment +14. Apply all fixes from cycle 1 + +## Phase 5: Review Cycle 2 +15. Full re-read for flow, consistency, and anything edits may have broken +16. Check for: absolute claims that should be softened, repetition between sections, filler + +## Phase 6: Review Cycle 3 +17. Final pass with scorecard rating each criterion 1-10: + - Factual accuracy, Credibility, Cross-links, SEO, Code accuracy, Structure, Terminology, Tone +18. Overall must be **9+ out of 10**. If not, fix and re-rate. + +## Phase 7: External Research +19. Cross-check key claims against external sources (framework docs, published guidance, academic papers) +20. Verify all external URLs are live +21. Add external references where they strengthen credibility +22. Soften any claims that can't be externally verified + +## Phase 8: Glossary Linking +23. Run `node scripts/link-glossary-terms.js --file=blog/.md` on the new post +24. This auto-links first-use glossary terms to `/glossary#anchor` canonical definitions +25. Review the diff — the script is conservative but may need manual adjustment for edge cases + +## Phase 9: User Review Loop +26. Present the post to the user for review +27. User will send external reviewer feedback — apply it precisely +28. Repeat until feedback says "publishable" + +## Phase 10: Publish +29. Commit with message: `blog: add ` +30. Push branch and create PR with summary + test plan +31. Return PR URL + +## Key Rules +- **Never overclaim.** Posts go through external fact-checking. Precision > boldness. +- **Acknowledge competitors.** Say what frameworks do well before critiquing gaps. +- **No product pitches.** Present Cycles concepts as best practices, not features. +- **Verify everything.** Every link, every dollar figure, every framework behavior claim. +- **Terminology must match.** Check reference_blog_terminology.md in memory. diff --git a/.outreach/seo-title-decisions.md b/.outreach/seo-title-decisions.md new file mode 100644 index 00000000..c324518c --- /dev/null +++ b/.outreach/seo-title-decisions.md @@ -0,0 +1,54 @@ +# SEO title-length decisions log + +The recurring SEO scan flags `` tags over 60 chars as "critical." +This file documents which long titles are **intentionally** kept long +(with rationale) so the same items don't get re-flagged across scans. + +The rule we apply, not the flat 60-char ceiling: + +> A title may exceed 60 chars **if and only if** the most important +> keyword anchors are front-loaded in the first 60 chars (so even +> when truncated in SERPs, the visible portion reads as a coherent +> hook), AND the post-truncation portion adds material context that +> AI Overview / Perplexity / ChatGPT-search citations parse and reward. + +## Shortened (2026-05-01) + +| Slug | Old length | New length | Notes | +|---|---|---|---| +| `blog/ai-agent-governance-framework-nist-eu-ai-act-iso-42001-owasp-runtime-enforcement` | 134 | 54 (63 with `— Cycles` template) | H1 kept long for in-page context. Title front-loads "AI Agent Governance" + four framework names that act as long-tail SEO anchors. The 63-char rendered total is intentional: dropping any of the four framework names (NIST / EU AI Act / ISO 42001 / OWASP) loses a real search term, so "60-char" rule yields here to keyword preservation. | +| `blog/ai-agent-governance-admin-dashboard-monitor-control-budgets-risk` | 86 | 50 | H1 left alone (rhetorical hook is the engagement angle). `<title>` shortened to keyword-direct form. | +| `quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails` | 92 | 48 | H1 kept long for first-time-reader clarity in the docs context. `<title>` is the SEO-visible string. | + +## Intentionally kept long (do not re-flag) + +| Slug | Length | Why kept | +|---|---|---| +| `blog/state-of-ai-agent-incidents-2026` | 100 | Colon-subhead pattern. Truncation cuts only the subtitle ("Failures, Costs, and What Would Have Prevented Them"); the visible portion ("The State of AI Agent Incidents (2026)") reads as a complete hook. The full string gets cited by AI search. | +| `blog/ai-agent-risk-assessment-score-classify-enforce-tool-risk` | 98 | Was shortened in the same pass — see "Shortened" above. *Status reversed if re-flagged.* | +| `blog/mcp-tool-poisoning-why-agent-frameworks-cant-prevent-it` | 97 | The "84% Success Rate" hook is the post's reason for ranking on incident-search queries. Truncated form ("MCP Tool Poisoning Has an 84% Success Rate") still reads complete. | +| `blog/why-multi-agent-systems-fail-87-percent-cost-of-every-coordination-breakdown` | 97 | Same logic — the "87%" claim is the SERP hook. Truncated form ("Multi-Agent Systems Fail Up to 87% of the Time") reads complete. | + +## When to re-evaluate + +Re-evaluate the "kept long" decisions if: +- Search Console shows CTR < 1% on the post for its target query +- The post's primary query starts ranking on page 2 (truncation may be cutting the hook) +- A future SEO audit specifically presents data on truncated-title CTR for these posts + +Don't re-evaluate based purely on a flat length scan. The length is a +choice, not a defect. + +## Conventions + +- `<title>` is the frontmatter `title` field. VitePress appends ` — Cycles` per the global `titleTemplate`. Aim frontmatter title ≤ 50–55 chars so the rendered SERP title stays under 60 with the suffix. +- `H1` is the body `# heading`. Independent from `<title>`. Can be longer/punchier — it's a layout element, not a SERP element. +- `description` is the frontmatter `description`. Aim ≤ 155 chars (Google's typical desktop description truncation). +- `og:title` is set via `transformPageData` per page; defaults to frontmatter title. LinkedIn / Twitter unfurl previews use this and have different (more generous) length conventions. + +## What the SEO scan should actually measure + +A title scan that ignores meta description length, H1 vs `<title>` +divergence, and `og:title` is incomplete. Future scans should report +all four fields per page, not just `<title>`. The 60-char rule is +useful as a default but not as a verdict. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..28694554 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +## Git Rules — STRICT +- ALWAYS use native git for ALL commits and pushes +- NEVER use mcp__github__ tools for committing or pushing +- Use mcp__github__ ONLY for: PRs, Issues, GitHub Actions +- Write commit messages to a temp file, then: `git commit -F <file>` +- NEVER use --no-gpg-sign flag + +# Cycles strict rules +- yaml API specs always the authority +- always update AUDIT.md files when making changes to server, admin, client repos +- maintain at least 95% or higher test coverage for all code repos + +# Build +- Install: `npm install` +- Dev server: `npm run dev` +- Build: `npm run build` \ No newline at end of file diff --git a/blog/ai-agent-governance-admin-dashboard-monitor-control-budgets-risk.md b/blog/ai-agent-governance-admin-dashboard-monitor-control-budgets-risk.md index 3211ec20..99dfe629 100644 --- a/blog/ai-agent-governance-admin-dashboard-monitor-control-budgets-risk.md +++ b/blog/ai-agent-governance-admin-dashboard-monitor-control-budgets-risk.md @@ -1,5 +1,5 @@ --- -title: "AI Agent Governance Dashboard: Operating Budgets, Risk Limits, and Keys in Production" +title: "AI Agent Governance Dashboard: Budgets, Risk, Keys" date: 2026-04-09 author: Albert Mavashev tags: [product, operations, dashboard, runtime-authority] diff --git a/blog/ai-agent-governance-framework-nist-eu-ai-act-iso-42001-owasp-runtime-enforcement.md b/blog/ai-agent-governance-framework-nist-eu-ai-act-iso-42001-owasp-runtime-enforcement.md index dd888fb1..33ae83d7 100644 --- a/blog/ai-agent-governance-framework-nist-eu-ai-act-iso-42001-owasp-runtime-enforcement.md +++ b/blog/ai-agent-governance-framework-nist-eu-ai-act-iso-42001-owasp-runtime-enforcement.md @@ -1,5 +1,5 @@ --- -title: "The AI Agent Governance Framework: Mapping NIST, EU AI Act, ISO 42001, and OWASP Requirements to Runtime Enforcement Controls" +title: "AI Agent Governance: NIST, EU AI Act, ISO 42001, OWASP" date: 2026-04-02 author: Cycles Team tags: [governance, compliance, EU AI Act, NIST, ISO 42001, OWASP, runtime authority, agents] @@ -9,7 +9,7 @@ sidebar: false featured: true --- -# The AI Agent Governance Framework: Mapping NIST, EU AI Act, ISO 42001, and OWASP Requirements to Runtime Enforcement Controls +# AI Agent Governance: Mapping NIST, EU AI Act, ISO 42001, and OWASP to Runtime Enforcement > **Part of: [AI Agent Risk & Blast Radius Reference](/guides/risk-and-blast-radius)** — the full pillar covering action authority, risk scoring, blast-radius containment, and degradation paths. diff --git a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md index faa5bd5f..7c460797 100644 --- a/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md +++ b/quickstart/how-to-choose-a-first-cycles-rollout-tenant-budgets-run-budgets-or-model-call-guardrails.md @@ -1,5 +1,5 @@ --- -title: "How to Choose a First Cycles Rollout: Tenant Budgets, Run Budgets, or Model-Call Guardrails?" +title: "Your First Cycles Rollout: Budgets vs Guardrails" description: "Decide where to start with Cycles: tenant budgets for cost isolation, run budgets for runaway prevention, or model-call guardrails for low-friction adoption." ---