haiku-method 2.2.0

package/studios/dev-evangelism/stages/narrative/discovery/STORY-ARC.md

@@ -0,0 +1,29 @@
+---
+name: story-arc
+location: .haiku/intents/{intent-slug}/knowledge/STORY-ARC.md
+scope: intent
+format: text
+required: true
+---
+
+# Story Arc
+
+Narrative structure and key messages for the developer evangelism content. This output drives the create stage's content production across all planned formats.
+
+## Content Guide
+
+Structure the arc around developer storytelling:
+
+- **Hook** -- the developer-relatable problem or curiosity that opens the narrative
+- **Story arc** -- problem-solution-outcome structure with technical grounding
+- **Key messages** -- 3 or fewer takeaways that developers can act on immediately
+- **Audience-message mapping** -- which messages resonate with which segments and why
+- **Format adaptations** -- how the narrative adjusts for blog, talk, demo, or video
+- **Editorial notes** -- jargon flags, tone guidance, and claims requiring code proof
+
+## Quality Signals
+
+- Story arc follows a clear problem-solution-outcome structure
+- Takeaways are actionable, not aspirational
+- Narrative adapts across planned content formats without losing coherence
+- Technical claims are flagged for validation in the create stage

package/studios/dev-evangelism/stages/narrative/hats/editor.md

@@ -0,0 +1,8 @@
+**Focus:** Refine the narrative for clarity, technical accuracy, and audience fit. Eliminate jargon that excludes target segments, tighten the story arc, and verify that takeaways are genuinely actionable.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** polish prose at the expense of technical substance
+- The agent **MUST NOT** let marketing language creep into developer-facing narrative
+- The agent **MUST NOT** approve vague takeaways that a developer cannot act on
+- The agent **MUST NOT** ignore tone mismatches between the narrative and target audience expectations
+- The agent **MUST** flag any claims that require code proof or demo validation

package/studios/dev-evangelism/stages/narrative/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/dev-evangelism/stages/narrative/hats/storyteller.md

@@ -0,0 +1,8 @@
+**Focus:** Craft the narrative arc that transforms technical topics into compelling developer stories. Build the problem-solution-outcome structure, define the hook, and map key messages to audience segments.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** lead with product features instead of developer problems
+- The agent **MUST NOT** create abstract narratives that lack concrete technical grounding
+- The agent **MUST NOT** overload the story with more than 3 key takeaways
+- The agent **MUST NOT** write for a generic audience instead of specific developer segments
+- The agent **MUST** ensure the narrative works across the planned content formats (talk, post, demo)

package/studios/dev-evangelism/stages/narrative/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit design/synthesis artifact for the narrative stage of dev-evangelism. Units here are narrative artifact — designed outputs that downstream stages execute against. Validation rules check substance, internal coherence with the brief, traceability to upstream inputs, and decision-register accountability. NOT executable verify-commands.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
+- The agent **MUST NOT** validate against frontmatter schema, `depends_on:` resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
+- The agent **MUST NOT** advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
+- The agent **MUST NOT** reject for stylistic preferences. Substantive gaps only.
+- The agent **MUST** name a specific failed criterion in any rejection.
+- The agent **MUST NOT** invent rules not in this mandate. Stage scope is the contract.
+
+## What you check (BODY ONLY)
+
+### 1. Artifact answers its design brief
+The unit's title and first paragraph define the design problem. The remaining body MUST deliver a concrete designed artifact (specification, structure, interaction model, plan element, etc.) — not an outline, not a deferral, not a "we'll figure this out later".
+
+### 2. Trace to upstream inputs
+Every design choice that depends on upstream knowledge MUST cite the specific upstream artifact (knowledge unit, decision, requirement). Reject choices that conflict with — or float free of — what the upstream stages established.
+
+### 3. Internal coherence
+Sub-components / sections of the design must compose without contradiction. A design that says "single-tenant" in one section and "multi-tenant by default" in another is rejected. Cite the contradicting paragraphs.
+
+### 4. Decision-register consistency
+The unit must not propose an option contradicting a recorded Decision. Cite the Decision ID.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted, OR flagged `(needs human escalation)`. Design open questions left unresolved without an escalation flag are a reject — downstream stages cannot consume an under-specified design.

package/studios/dev-evangelism/stages/narrative/outputs/NARRATIVE-BRIEF.md

@@ -0,0 +1,25 @@
+---
+name: narrative-brief
+location: .haiku/intents/{intent-slug}/stages/narrative/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Narrative Brief
+
+Story arc, key messages, takeaways, and format-specific narrative adaptations.
+
+## Expected Artifacts
+
+- **Story arc** -- problem-solution-outcome structure with developer-relatable hook
+- **Key messages** -- 3 or fewer actionable takeaways per audience segment
+- **Audience-message mapping** -- messages matched to developer segments and formats
+- **Editorial guidance** -- tone, jargon flags, and claims requiring demo validation
+
+## Quality Signals
+
+- Story arc has a clear problem-solution-outcome structure
+- Key messages are actionable and tied to specific audience needs
+- Narrative is coherent across planned content formats
+- Technical claims are flagged for code proof in the create stage

package/studios/dev-evangelism/stages/narrative/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Narrative Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Story arc has a clear problem-solution-outcome structure with a developer-relatable hook"
+- "Key messages are distilled to 3 or fewer takeaways that the audience can act on immediately"
+- "Narrative brief maps each message to a specific audience segment and content format"
+
+### Bad criteria — vague (no clear check)
+
+- "Story is compelling"
+- "Messages are clear"
+- "Narrative works"
+

package/studios/dev-evangelism/stages/narrative/review-agents/coherence.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the narrative is coherent, technically grounded, and serves the target developer audience.
+
+**Check:**
+- The agent **MUST** verify that the story arc has a clear problem-solution-outcome structure
+- The agent **MUST** verify that key messages are actionable and limited to 3 or fewer takeaways
+- The agent **MUST** verify that narrative tone matches developer audience expectations, not marketing speak
+- The agent **MUST** verify that technical claims are flagged for proof in the create stage

package/studios/dev-evangelism/stages/publish/STAGE.md

@@ -0,0 +1,15 @@
+---
+name: publish
+description: Distribute content across channels
+hats: [distributor, community-manager, verifier]
+fix_hats: [distributor, feedback-assessor]
+review: auto
+elaboration: autonomous
+inputs:
+  - stage: create
+    discovery: content-package
+---
+
+# Publish
+
+Distribute content across channels.

package/studios/dev-evangelism/stages/publish/discovery/DISTRIBUTION-LOG.md

@@ -0,0 +1,28 @@
+---
+name: distribution-log
+location: .haiku/intents/{intent-slug}/knowledge/DISTRIBUTION-LOG.md
+scope: intent
+format: text
+required: true
+---
+
+# Distribution Log
+
+Record of all published content with timestamps, channels, and initial engagement. This output feeds the measure stage for impact analysis.
+
+## Content Guide
+
+Structure the log around distribution tracking:
+
+- **Publish record** -- timestamp, channel, URL, and platform-specific metadata for each asset
+- **Platform adaptations** -- format and tone adjustments made per channel
+- **Community seeding** -- forums and channels where discussion was initiated with links
+- **Initial engagement** -- early metrics snapshot within 24-48 hours of publish
+- **Issue log** -- any publish failures, rendering problems, or access issues encountered
+
+## Quality Signals
+
+- Every distributed asset has a recorded timestamp and verified access URL
+- Platform-specific adaptations are documented for each channel
+- Community seeding targets are specific forums, not generic platform names
+- Initial engagement captures both reach and interaction metrics

package/studios/dev-evangelism/stages/publish/hats/community-manager.md

@@ -0,0 +1,8 @@
+**Focus:** Seed discussion in developer communities, respond to early feedback, and cultivate organic engagement around published content. Build genuine conversations rather than broadcast-only distribution.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** spam communities with promotional posts disguised as discussion
+- The agent **MUST NOT** ignore negative or critical feedback from developers
+- The agent **MUST NOT** engage in communities without understanding their norms and rules
+- The agent **MUST NOT** seed discussion without a plan for sustained follow-up
+- The agent **MUST** maintain authentic developer voice rather than corporate messaging tone

package/studios/dev-evangelism/stages/publish/hats/distributor.md

@@ -0,0 +1,8 @@
+**Focus:** Execute multi-channel distribution — publish blog posts, submit conference talks, upload videos, and share across developer platforms. Adapt content format per platform rather than cross-posting identical copies.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** cross-post identical content without platform-specific adaptation
+- The agent **MUST NOT** publish without verifying that links, embeds, and code blocks render correctly
+- The agent **MUST NOT** ignore platform-specific metadata (tags, categories, canonical URLs)
+- The agent **MUST NOT** publish to channels without tracking links or analytics in place
+- The agent **MUST** record actual publish timestamps and access URLs for every distributed asset

package/studios/dev-evangelism/stages/publish/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/dev-evangelism/stages/publish/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit operational artifact for the publish stage of dev-evangelism. Units here are distribution action — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
+- The agent **MUST NOT** validate against frontmatter schema, `depends_on:` resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
+- The agent **MUST NOT** advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
+- The agent **MUST NOT** reject for stylistic preferences. Substantive gaps only.
+- The agent **MUST** name a specific failed criterion in any rejection.
+- The agent **MUST NOT** invent rules not in this mandate. Stage scope is the contract.
+
+## What you check (BODY ONLY)
+
+### 1. Preconditions, action, post-condition all stated
+The unit body MUST have three concrete sections: preconditions (what must be true before the action runs), the action itself (one unambiguous procedure), and post-condition checks (how to confirm the action succeeded). Reject if any of the three is missing or vague.
+
+### 2. Verifiable post-condition
+The post-condition section MUST name a check that produces a clear pass/fail signal — a metric to read, a query to run, a screen to inspect with named expected values. "Verify by eye that things look good" is a reject.
+
+### 3. Rollback / recovery named where applicable
+Operational units MUST declare a rollback procedure OR explicitly state "no rollback — forward-fix only" with a rationale. Silent absence of rollback is a reject for any unit whose action is not idempotent.
+
+### 4. Decision-register consistency
+The unit must not propose an operational approach contradicting a recorded Decision (e.g., blue-green deploy when Decision N chose canary). Cite the Decision ID.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted, OR flagged `(needs human escalation)`. Operational open questions left to runtime are how outages happen.

package/studios/dev-evangelism/stages/publish/outputs/DISTRIBUTION-LOG.md

@@ -0,0 +1,25 @@
+---
+name: distribution-log
+location: .haiku/intents/{intent-slug}/stages/publish/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Distribution Log
+
+Record of all published content with timestamps, channels, and initial engagement.
+
+## Expected Artifacts
+
+- **Publish record** -- timestamp, channel, URL, and platform-specific metadata for each asset
+- **Platform adaptations** -- format and tone adjustments made per channel
+- **Community seeding** -- forums and channels where discussion was initiated
+- **Initial engagement** -- early metrics snapshot within 24-48 hours of publish
+
+## Quality Signals
+
+- Every distributed asset has a recorded timestamp and access URL
+- Platform-specific adaptations are documented, not just cross-posted
+- Community seeding covers at least 3 relevant developer forums or channels
+- Initial engagement metrics are captured for baseline comparison

package/studios/dev-evangelism/stages/publish/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Publish Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Distribution log records publish timestamps, channels, and initial engagement metrics for every asset"
+- "Cross-posting strategy adapts format per platform rather than identical copy-paste"
+- "Community seeding plan identifies at least 3 forums or channels for organic discussion"
+
+### Bad criteria — vague (no clear check)
+
+- "Content is published"
+- "Channels are covered"
+- "Post is live"
+

package/studios/dev-evangelism/stages/publish/review-agents/reach.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify distribution covers the target audience effectively across planned channels.
+
+**Check:**
+- The agent **MUST** verify that all planned channels received platform-adapted content, not identical copies
+- The agent **MUST** verify that publish timestamps and access URLs are recorded for every asset
+- The agent **MUST** verify that tracking and analytics are active before distribution
+- The agent **MUST** verify that community seeding targets forums where the target audience is genuinely active

package/studios/dev-evangelism/stages/research/STAGE.md

@@ -0,0 +1,13 @@
+---
+name: research
+description: Identify target audience, map the topic landscape, analyze competitive content
+hats: [audience-analyst, topic-scout, verifier]
+fix_hats: [audience-analyst, feedback-assessor]
+review: auto
+elaboration: collaborative
+inputs: []
+---
+
+# Research
+
+Identify target audience, map the topic landscape, analyze competitive content.

package/studios/dev-evangelism/stages/research/discovery/AUDIENCE-LANDSCAPE.md

@@ -0,0 +1,29 @@
+---
+name: audience-landscape
+location: .haiku/intents/{intent-slug}/knowledge/AUDIENCE-LANDSCAPE.md
+scope: intent
+format: text
+required: true
+---
+
+# Audience Landscape
+
+Developer audience research and topic landscape analysis. This output feeds the narrative stage as foundational context for story arc and messaging decisions.
+
+## Content Guide
+
+Structure the landscape around developer understanding:
+
+- **Developer segments** -- defined with skill levels, technology stacks, pain points, and content format preferences
+- **Topic landscape** -- trending themes, underserved areas, and competitive content analysis
+- **Content gaps** -- opportunities where the team's expertise fills a genuine need
+- **Community presence** -- where each segment is active and receptive (forums, platforms, events)
+- **Sources consulted** -- community data, analytics, conference programs, with retrieval dates
+- **Open questions** -- what remains unvalidated or requires direct audience feedback
+
+## Quality Signals
+
+- Developer segments are evidence-based, not assumed from job titles alone
+- Topic recommendations match audience needs and team credibility
+- Content gaps are validated against existing competitive content
+- Community mapping identifies specific platforms and forums, not generic categories

package/studios/dev-evangelism/stages/research/hats/audience-analyst.md

@@ -0,0 +1,8 @@
+**Focus:** Map the developer audience — skill levels, technology stacks, pain points, learning preferences, and where they consume technical content. Transform community signals into targetable audience segments.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** define developer segments solely by job title without considering skill level and technology context
+- The agent **MUST NOT** assume content preferences without evidence from community behavior
+- The agent **MUST NOT** conflate beginner and advanced audiences into a single "developers" segment
+- The agent **MUST NOT** ignore platform-specific audience differences (e.g., Twitter/X vs. Reddit vs. Hacker News)
+- The agent **MUST** distinguish between developers who build with the technology and those who evaluate it

package/studios/dev-evangelism/stages/research/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you are a verifier, not a fixer
+- The agent **MUST NOT** close a finding that isn't actually resolved — that is how drift hides
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
+- The agent **MUST NOT** expand the scope beyond the one feedback item you were dispatched against

package/studios/dev-evangelism/stages/research/hats/topic-scout.md

@@ -0,0 +1,8 @@
+**Focus:** Scan the technical landscape for trending topics, underserved content areas, and opportunities where the team's expertise can fill a gap. Analyze conference programs, blog ecosystems, and community discussions to identify high-value content topics.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** recommend topics where the team lacks genuine technical credibility
+- The agent **MUST NOT** chase trends without validating sustained developer interest
+- The agent **MUST NOT** ignore existing content saturation when recommending topics
+- The agent **MUST NOT** limit scanning to a single platform or content format
+- The agent **MUST** assess whether a topic is still timely or already past peak interest

package/studios/dev-evangelism/stages/research/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit knowledge artifact for the research stage of dev-evangelism. Units here are audience/topic insight — knowledge artifacts that downstream stages consume. Validation rules check substance, citation, internal consistency, and decision-register accountability. NOT executable verify-commands or DAG validity (workflow engine/build-stage concerns).
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
+- The agent **MUST NOT** validate against frontmatter schema, `depends_on:` resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
+- The agent **MUST NOT** advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
+- The agent **MUST NOT** reject for stylistic preferences. Substantive gaps only.
+- The agent **MUST** name a specific failed criterion in any rejection.
+- The agent **MUST NOT** invent rules not in this mandate. Stage scope is the contract.
+
+## What you check (BODY ONLY)
+
+### 1. Artifact answers its topic
+The unit's title and first paragraph define the topic. The remaining body MUST deliver substantive content on that topic. Reject placeholders, content-free outlines, or redirects.
+
+### 2. Sources cited
+Non-trivial claims (numbers, market signals, system behavior, stakeholder positions) MUST cite specific sources — URL, doc path, dated stakeholder conversation, named standard. Reject "industry common knowledge" or unsourced numerical claims.
+
+### 3. Internal consistency
+Title, mission, and body must align. Numerical/categorical claims must be consistent across the body. Recommendations must follow from the evidence presented.
+
+### 4. Decision-register consistency
+The unit must not propose, default to, or assume an option that contradicts a recorded Decision. Cite the Decision ID in any rejection.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted with veto-style approval, OR flagged `(needs human escalation)`.

package/studios/dev-evangelism/stages/research/outputs/RESEARCH-BRIEF.md

@@ -0,0 +1,25 @@
+---
+name: research-brief
+location: .haiku/intents/{intent-slug}/stages/research/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Research Brief
+
+Developer audience segments, topic landscape, and content gap analysis.
+
+## Expected Artifacts
+
+- **Developer segments** -- defined with skill levels, technology stacks, pain points, and content preferences
+- **Topic landscape** -- trending and underserved topics with competitive content analysis
+- **Content gaps** -- opportunities where the team has unique expertise to contribute
+- **Community map** -- where target developers are active and receptive
+
+## Quality Signals
+
+- Developer segments include skill levels, pain points, and content format preferences
+- At least 5 topics are analyzed with competitive content assessment
+- Content gaps are validated against existing materials in the space
+- All claims reference specific data sources with retrieval dates

package/studios/dev-evangelism/stages/research/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Research Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Audience landscape identifies at least 3 developer segments with skill levels, pain points, and preferred content formats"
+- "Topic scan surfaces at least 5 trending or underserved topics with competitive content analysis for each"
+- "Research brief maps existing content gaps where the team has unique expertise to contribute"
+
+### Bad criteria — vague (no clear check)
+
+- "Research is done"
+- "Audience is understood"
+- "Topics are identified"
+

package/studios/dev-evangelism/stages/research/review-agents/relevance.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify research targets genuine developer needs and credible topic opportunities.
+
+**Check:**
+- The agent **MUST** verify that audience segments are based on observable signals, not assumptions about developer behavior
+- The agent **MUST** verify that topic recommendations align with both audience demand and team expertise
+- The agent **MUST** verify that competitive content analysis covers current materials, not outdated references
+- The agent **MUST** verify that content gaps are genuine opportunities, not areas competitors wisely avoided

package/studios/documentation/STUDIO.md

@@ -0,0 +1,13 @@
+---
+name: documentation
+description: Technical documentation lifecycle for API docs, guides, runbooks, and knowledge bases
+stages: [audit, outline, draft, review, publish]
+category: engineering
+default_model: sonnet
+---
+
+# Documentation Studio
+
+Use this studio for any technical documentation effort — API references, user guides, operational runbooks, architecture decision records, onboarding docs, or knowledge base articles. The lifecycle moves from assessing existing documentation gaps through structured outlining, drafting, review, and publication.
+
+Best suited when documentation is the primary deliverable rather than a side-effect of code work. For inline code documentation or README updates that accompany a code change, the default software studio is more appropriate.

package/studios/documentation/examples/api-reference-revamp/intent.md

@@ -0,0 +1,17 @@
+---
+title: api-reference-revamp
+studio: documentation
+stages: [audit, outline, draft, review, publish]
+status: complete
+---
+
+# API Reference Revamp
+
+Rebuild the public API reference from the OpenAPI spec, add hand-written request/response examples for every endpoint, and ship versioned docs for the latest and previous-major versions. Older versions are EOL'd.
+
+## Goals
+
+- Generate endpoint pages from the OpenAPI spec (single source of truth)
+- Hand-write one realistic request/response example per endpoint
+- Two-version navigation: latest + previous-major, older versions redirect to EOL page
+- Dogfood the docs by running every example in CI

package/studios/documentation/examples/api-reference-revamp/pre-intent.yml

@@ -0,0 +1,17 @@
+related:
+  - software
+  - dev-evangelism
+  - libdev
+turns:
+  - role: user
+    text: "Our API reference is a dumping ground. Rebuild it properly."
+  - role: agent
+    text: "Generated from OpenAPI or hand-curated?"
+  - role: user
+    text: "Generated from the spec, but with hand-written examples per endpoint."
+  - role: agent
+    text: "Versioning — latest only, or every public version?"
+  - role: user
+    text: "Latest plus the previous major. We EOL anything older."
+  - role: agent
+    text: "Got it — OpenAPI-driven reference with curated examples, latest + one back."

package/studios/documentation/fix-hats/reconciler.md

@@ -0,0 +1,10 @@
+---
+agent_type: general-purpose
+---
+**Focus:** Reconcile cross-stage artifacts against studio-wide standards. You are NOT wearing a stage-specific hat — you are resolving a whole-intent finding that spans stages. Your mandate is alignment, not fresh authoring.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** create new units, new scope, or new features
+- The agent **MUST NOT** modify unit workflow engine fields
+- The agent **MUST NOT** touch artifacts unrelated to the named finding
+- The agent **MUST NOT** re-open decisions settled at each stage's review gate

package/studios/documentation/fix-hats/validator.md

@@ -0,0 +1,10 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**Focus:** Independently verify that the reconciler's fix resolves the intent-scope feedback. You are the terminal hat — the workflow engine trusts your closure decision.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** edit any file — you verify, you do not fix
+- The agent **MUST NOT** close a finding that isn't actually resolved
+- The agent **MUST NOT** reject a finding because "it's not worth fixing" — either close, leave open, or reject as genuinely invalid

package/studios/documentation/operations/freshness-review.md

@@ -0,0 +1,20 @@
+---
+name: freshness-review
+type: scheduled
+owner: human
+frequency: "quarterly"
+---
+
+**Purpose:** Identify documentation that has fallen behind the codebase or product.
+
+**Procedure:**
+- [ ] Compare documentation against current feature state
+- [ ] Check code examples compile/run against current version
+- [ ] Identify pages with no updates in 6+ months
+- [ ] Flag pages for features that have been significantly changed
+- [ ] Prioritize updates by page traffic and user impact
+
+**Signals:**
+- Quarterly review
+- After major product releases
+- After API breaking changes

package/studios/documentation/operations/link-checker.md

@@ -0,0 +1,20 @@
+---
+name: link-checker
+type: scheduled
+owner: agent
+schedule: "0 9 * * 1"
+runtime: node
+---
+
+**Purpose:** Detect broken links before users do. Link rot erodes trust in documentation.
+
+**Procedure:**
+- Crawl all published documentation pages
+- Verify internal links resolve to existing pages
+- Verify external links return 200 responses
+- Report broken links with the page they appear on
+
+**Signals:**
+- Weekly check
+- After any documentation restructuring
+- After external dependencies change URLs

package/studios/documentation/reflections/clarity.md

@@ -0,0 +1,16 @@
+---
+name: clarity
+studio: documentation
+---
+
+**Analyze:** Review findings from editor and SME, revision cycles between draft and final.
+
+**Look for:**
+- Common clarity issues (jargon, missing context, assumed knowledge)
+- Sections that required the most revision
+- Whether the target audience was correctly identified
+
+**Produce:**
+- Clarity improvement patterns
+- Writing guideline recommendations
+- Audience definition refinement

package/studios/documentation/reflections/coverage.md

@@ -0,0 +1,16 @@
+---
+name: coverage
+studio: documentation
+---
+
+**Analyze:** Gaps closed vs gaps identified in audit, documentation coverage by feature area.
+
+**Look for:**
+- Audit gaps that were not addressed (what got deprioritized and why)
+- Feature areas still lacking documentation
+- Whether the outline structure matched how users navigate
+
+**Produce:**
+- Coverage delta (gaps at start vs gaps remaining)
+- Feature area coverage map
+- Recommendations for prioritizing remaining gaps