@jaimevalasek/aioson 1.4.0 → 1.6.0

package/template/.aioson/skills/squad/patterns/multi-platform-pattern.md

@@ -0,0 +1,108 @@
+---
+name: multi-platform-pattern
+description: How to create squads that produce content for multiple platforms simultaneously
+version: 1.0.0
+---
+
+# Multi-Platform Pattern
+
+A multi-platform squad produces content adapted for 2+ platforms from a single
+creative brief. The key challenge is platform-specific adaptation without
+losing message coherence.
+
+## When to use
+
+- Content squads targeting Instagram + YouTube + TikTok (or any combination)
+- Marketing squads with omnichannel campaigns
+- Brand squads maintaining consistent voice across platforms
+
+## Structure
+
+### Option A: Single creator + platform adapters
+
+```
+core-creator → platform-adapter-instagram
+             → platform-adapter-youtube
+             → platform-adapter-tiktok
+```
+
+Best when: one strong creative vision needs platform-specific formatting.
+
+### Option B: Platform specialists
+
+```
+briefer → instagram-specialist
+        → youtube-specialist
+        → tiktok-specialist
+        → brand-reviewer (cross-platform consistency check)
+```
+
+Best when: each platform requires deeply different approaches.
+
+### Option C: Hybrid (recommended for most cases)
+
+```
+strategist → core-creator → platform-specialists (parallel)
+                           → cross-platform-reviewer
+```
+
+## Executor recommendations
+
+| Role | Type | Model tier | Purpose |
+|---|---|---|---|
+| strategist | agent | powerful | Defines the creative brief and core message |
+| core-creator | agent | powerful | Creates the primary content piece |
+| platform-adapter | agent | balanced | Adapts content per platform specs |
+| brand-reviewer | agent | balanced | Ensures cross-platform consistency |
+| format-checker | worker | none | Validates platform constraints (char limits, dimensions) |
+
+## Format loading
+
+Load format templates from `formats/` only for platforms the squad targets:
+
+```
+formats/instagram-feed.md    → Instagram squads
+formats/youtube-long.md      → YouTube squads
+formats/tiktok.md            → TikTok squads
+formats/linkedin-post.md     → LinkedIn squads
+formats/twitter-thread.md    → Twitter/X squads
+```
+
+## Workflow template
+
+```json
+{
+  "slug": "multi-platform-content",
+  "phases": [
+    { "id": "brief", "executor": "strategist" },
+    { "id": "core-draft", "executor": "core-creator" },
+    { "id": "adapt", "executors": ["ig-adapter", "yt-adapter", "tt-adapter"], "parallel": true },
+    { "id": "review", "executor": "brand-reviewer", "review": { "criteria": ["brand-consistency", "platform-fit"] } },
+    { "id": "validate", "executor": "format-checker" }
+  ]
+}
+```
+
+## Anti-patterns
+
+- **Copy-paste across platforms:** Each platform has unique audience behavior. Adaptation is mandatory.
+- **Ignoring platform constraints:** Character limits, video durations, image ratios differ per platform.
+- **One-size-fits-all CTA:** "Subscribe" on YouTube, "Follow" on Instagram, "Connect" on LinkedIn.
+- **Missing cross-platform review:** Without consistency checks, brand voice fragments.
+
+## Content blueprint suggestion
+
+```json
+{
+  "slug": "multi-platform-package",
+  "contentType": "multi-platform",
+  "layoutType": "tabs",
+  "sections": [
+    { "key": "brief", "label": "Creative Brief" },
+    { "key": "core-content", "label": "Core Content" },
+    { "key": "instagram", "label": "Instagram Version" },
+    { "key": "youtube", "label": "YouTube Version" },
+    { "key": "tiktok", "label": "TikTok Version" }
+  ]
+}
+```

package/template/.aioson/skills/squad/patterns/persona-based-pattern.md

@@ -0,0 +1,98 @@
+---
+name: persona-based-pattern
+description: How to create squads driven by a specific person's voice, methodology, or brand
+version: 1.0.0
+---
+
+# Persona-Based Pattern
+
+A persona-based squad produces content or work that reflects a specific person's
+voice, methodology, or cognitive style. This pattern uses the profiler pipeline
+to create a cognitive genome that informs creative executors.
+
+## When to use
+
+- Personal branding squads (content in someone's voice)
+- Methodology-based squads (applying a specific expert's framework)
+- Ghost-writing or content delegation squads
+- Squads where "sounding like the person" is a core requirement
+
+## Detection heuristics
+
+The squad agent should suggest profiling when:
+
+- The user mentions a specific person by name
+- The goal includes "in the style of", "like {person}", "based on {person}'s approach"
+- The domain is personal branding or creator content
+- The user references a specific methodology tied to a person
+
+## Profiler pipeline
+
+```
+@profiler-researcher → @profiler-enricher → @profiler-forge
+         ↓                     ↓                    ↓
+   evidence gathering    pattern analysis      genome generation
+```
+
+### Step 1: Check existing profile
+
+Before running the pipeline, check `.aioson/profiler-reports/{person-slug}/`.
+If a profile exists, reuse it.
+
+### Step 2: Run profiling (if needed)
+
+1. `@profiler-researcher` — collects public evidence about the person
+2. `@profiler-enricher` — analyzes patterns, voice, methodology
+3. `@profiler-forge` — generates the cognitive genome
+
+### Step 3: Apply genome selectively
+
+The genome should only be applied to executors that produce voice-sensitive output:
+
+| Executor type | Apply genome? | Reason |
+|---|---|---|
+| Copywriter/Scriptwriter | Yes | Needs the person's voice |
+| Editor/Reviewer | Yes | Needs to judge voice fidelity |
+| Researcher/Analyst | No | Research should be objective |
+| Orchestrator | No | Coordination doesn't need voice |
+| Worker (no LLM) | No | Deterministic, no voice needed |
+
+### Step 4: Register in blueprint
+
+```json
+{
+  "profiling": {
+    "person": "Person Name",
+    "genomePath": ".aioson/profiler-reports/person-slug/genome.json",
+    "genomeSlug": "person-slug",
+    "evidenceMode": "verified",
+    "profiledAt": "2026-03-24T00:00:00Z"
+  }
+}
+```
+
+## Executor recommendations
+
+| Role | Type | Model tier | Genome? |
+|---|---|---|---|
+| researcher | agent | balanced | No |
+| scriptwriter | agent | powerful | Yes |
+| copywriter | agent | powerful | Yes |
+| editor | agent | balanced | Yes |
+| brand-guardian | agent | balanced | Yes |
+| publisher | worker | none | No |
+
+## Anti-patterns
+
+- **Applying genome to all executors:** Research and orchestration don't need persona voice.
+- **Profiling without consent:** Always ask the user before running the profiler pipeline.
+- **Stale genome:** If the person's style has evolved, the genome may need refreshing.
+- **Over-reliance on genome:** The genome calibrates voice, it doesn't replace creative judgment.
+- **Copying vs. calibrating:** The goal is to capture methodology and voice patterns, not to clone or impersonate.
+
+## Quality gates for persona fidelity
+
+- Voice consistency: Does the output sound like the person across all pieces?
+- Methodology alignment: Does the approach follow the person's known frameworks?
+- Authenticity check: Would the person recognize this as something they might produce?
+- Originality: Is it inspired by the person, not a copy of their specific works?

package/template/.aioson/skills/squad/patterns/pipeline-pattern.md

@@ -0,0 +1,106 @@
+---
+name: pipeline-pattern
+description: How to configure pipelines between squads for multi-stage workflows
+version: 1.0.0
+---
+
+# Pipeline Pattern
+
+A pipeline connects two or more squads so that the output of one becomes the
+input of the next. This pattern enables complex multi-stage workflows where
+each squad has a distinct responsibility.
+
+## When to use
+
+- Content pipeline: research squad → writing squad → publishing squad
+- Software pipeline: design squad → implementation squad → QA squad
+- Data pipeline: collection squad → analysis squad → reporting squad
+- Any workflow where stages have fundamentally different skill requirements
+
+## Structure
+
+### Ports (input/output contract)
+
+Each squad in a pipeline declares its ports:
+
+```json
+{
+  "ports": {
+    "inputs": [
+      { "key": "research-brief", "from": "research-squad", "format": "markdown" }
+    ],
+    "outputs": [
+      { "key": "draft-content", "to": "publishing-squad", "format": "content.json" }
+    ]
+  }
+}
+```
+
+### Pipeline definition
+
+```json
+{
+  "pipeline": {
+    "stages": [
+      { "squad": "research-squad", "output": "research-brief" },
+      { "squad": "writing-squad", "input": "research-brief", "output": "draft-content" },
+      { "squad": "publishing-squad", "input": "draft-content" }
+    ],
+    "trigger": "manual",
+    "errorStrategy": "stop-on-failure"
+  }
+}
+```
+
+## Key decisions
+
+### Trigger modes
+
+| Mode | Behavior |
+|---|---|
+| `manual` | User explicitly starts each stage |
+| `on-complete` | Next stage starts automatically when previous completes |
+| `scheduled` | Stages run on a schedule (e.g., research Monday, writing Wednesday) |
+
+### Error handling
+
+| Strategy | Behavior |
+|---|---|
+| `stop-on-failure` | Pipeline halts, user intervenes |
+| `retry` | Failed stage retries N times before halting |
+| `skip` | Failed stage is skipped, next stage gets partial input |
+
+### Data handoff format
+
+Squads should agree on a data contract. Recommended formats:
+
+- `content.json` — for structured content packages
+- Markdown files — for research reports, briefs, analysis
+- JSON files — for structured data, configurations
+- File references — for media assets
+
+## Executor design for pipelines
+
+Pipeline squads tend to be more focused than standalone squads:
+
+| Squad in pipeline | Typical executors |
+|---|---|
+| Research stage | researcher, analyst, fact-checker |
+| Creation stage | writer, designer, reviewer |
+| Publishing stage | formatter, publisher, distributor |
+
+Each squad should have clear input expectations and output guarantees.
+
+## Anti-patterns
+
+- **Monolith squad:** If a squad has 8+ executors covering research, creation, and distribution, consider splitting into a pipeline.
+- **Implicit contracts:** Squads in a pipeline must agree on data format. Don't assume.
+- **Tight coupling:** Each squad should be independently testable and runnable.
+- **Missing error handling:** Always define what happens when a stage fails.
+
+## Cross-squad awareness
+
+Squads with ports contribute to the Quality Structural scoring dimension:
+- +3 pts for having ports defined (inputs or outputs)
+
+The squad:doctor also checks for port consistency across connected squads.

package/template/.aioson/skills/squad/patterns/review-loop-pattern.md

@@ -0,0 +1,81 @@
+---
+name: review-loop-pattern
+description: How to configure review loops in squad workflows for quality assurance
+version: 1.0.0
+---
+
+# Review Loop Pattern
+
+A review loop adds a quality gate within a workflow phase. An executor produces
+output, a reviewer evaluates it, and the workflow either advances or retries.
+
+## When to use
+
+- Content squads where quality directly impacts reputation
+- Software squads with code review requirements
+- Any squad where output goes to external audiences
+- Squads with regulatory or compliance constraints
+
+## Structure
+
+```json
+{
+  "phases": [
+    {
+      "id": "draft",
+      "executor": "scriptwriter",
+      "review": {
+        "reviewer": "editor",
+        "criteria": ["clarity", "brand-voice", "factual-accuracy"],
+        "onReject": "revise-draft",
+        "maxRetries": 2,
+        "retryStrategy": "feedback-only",
+        "escalateOnMaxRetries": "human",
+        "vetoConditions": ["plagiarism-detected", "factual-error"]
+      }
+    }
+  ]
+}
+```
+
+## Key decisions
+
+### Who reviews?
+
+| Reviewer type | When to use |
+|---|---|
+| Peer executor | Same domain, different perspective (e.g., editor reviews writer) |
+| QA executor | Dedicated quality role in the squad |
+| Orchestrator | Lightweight structural checks |
+| Human gate | High-stakes output, legal, compliance |
+
+### Retry strategy
+
+| Strategy | Behavior |
+|---|---|
+| `feedback-only` | Reviewer sends feedback, creator revises (default) |
+| `full-rewrite` | Creator starts from scratch with reviewer notes |
+| `escalate` | Move to a more senior executor or human |
+
+### Veto conditions
+
+Veto conditions are hard stops — if triggered, the output is rejected regardless
+of other criteria scores. Use for:
+
+- Plagiarism detection
+- Factual errors in critical domains (medical, legal, financial)
+- Brand safety violations
+- Regulatory non-compliance
+
+## Anti-patterns
+
+- **Review everything:** Not all phases need review. Apply to high-impact outputs only.
+- **Self-review:** A reviewer should not be the same executor that created the output.
+- **Infinite retries:** Always set `maxRetries`. 2-3 is typical. Escalate after that.
+- **Vague criteria:** "Make it better" is not a criterion. Use measurable checks.
+
+## Integration with squad scoring
+
+Review loops contribute to the Quality Structural dimension:
+- +5 pts for having review loops in at least one workflow phase
+- +5 pts for having veto conditions defined

package/template/.aioson/skills/squad/references/checklist-templates.md

@@ -0,0 +1,122 @@
+---
+name: checklist-templates
+description: Quality checklist templates organized by domain and output type
+version: 1.0.0
+---
+
+# Checklist Templates
+
+Reusable quality checklists for squad outputs. These can be referenced in
+manifest checklists or used as veto condition sources.
+
+## General content checklist
+
+```markdown
+## Content Quality Checklist
+- [ ] Clear and compelling headline/title
+- [ ] Hook in the first paragraph/sentence
+- [ ] Logical flow from introduction to conclusion
+- [ ] No grammatical or spelling errors
+- [ ] Sources cited for factual claims
+- [ ] Call-to-action present and appropriate
+- [ ] Formatted for the target platform
+- [ ] Brand voice consistent throughout
+```
+
+## Social media checklist
+
+```markdown
+## Social Media Quality Checklist
+- [ ] Platform character/duration limits respected
+- [ ] Hook in first line (text) or first 3 seconds (video)
+- [ ] Hashtags relevant and platform-appropriate
+- [ ] CTA matches platform behavior (follow, like, comment, share)
+- [ ] Visual/thumbnail meets platform specs (dimensions, file size)
+- [ ] No banned words or flagged content
+- [ ] Posting time aligns with audience activity
+- [ ] Cross-platform consistency verified (if multi-platform)
+```
+
+## Video script checklist
+
+```markdown
+## Video Script Quality Checklist
+- [ ] Hook captures attention in first 3 seconds
+- [ ] Context bridge explains why viewer should stay (3-15s)
+- [ ] Value delivery structured in clear chapters/segments
+- [ ] Retention hooks at chapter transitions
+- [ ] CTA integrated naturally (not forced)
+- [ ] Script length matches target duration
+- [ ] Thumbnail concept included or referenced
+- [ ] Title options provided (3-5 variations)
+- [ ] Description and tags optimized for search
+```
+
+## Blog/article checklist
+
+```markdown
+## Blog/Article Quality Checklist
+- [ ] Title is descriptive and SEO-friendly
+- [ ] Meta description written (150-160 characters)
+- [ ] Introduction states the value proposition
+- [ ] Subheadings break content into scannable sections
+- [ ] Images/media support the text
+- [ ] Internal and external links included
+- [ ] Conclusion summarizes key takeaways
+- [ ] CTA directs reader to next step
+- [ ] Reading time estimate included
+```
+
+## Software deliverable checklist
+
+```markdown
+## Software Deliverable Checklist
+- [ ] Requirements fully addressed
+- [ ] Code follows project conventions
+- [ ] Tests written and passing
+- [ ] No security vulnerabilities introduced
+- [ ] Error handling covers edge cases
+- [ ] Documentation updated
+- [ ] Performance impact assessed
+- [ ] Backward compatibility maintained (or breaking changes documented)
+```
+
+## Research/analysis checklist
+
+```markdown
+## Research Quality Checklist
+- [ ] Research question clearly defined
+- [ ] Sources are credible and diverse
+- [ ] Data is current (within acceptable timeframe)
+- [ ] Claims are supported by evidence
+- [ ] Counterarguments acknowledged
+- [ ] Methodology is transparent
+- [ ] Conclusions follow from evidence
+- [ ] Limitations explicitly stated
+```
+
+## Using checklists in manifests
+
+Reference a checklist in the squad manifest:
+
+```json
+{
+  "checklists": [
+    {
+      "slug": "content-quality",
+      "title": "Content Quality",
+      "source": "skills/squad/references/checklist-templates.md#general-content-checklist",
+      "applies_to": ["scriptwriter", "copywriter"]
+    }
+  ]
+}
+```
+
+## Creating domain-specific checklists
+
+For domains not covered here, derive checklists from:
+
+1. **Investigation findings** — D3 (Quality Benchmarks) from @orache
+2. **Industry standards** — professional association guidelines
+3. **Anti-patterns** — D2 findings become negative checks ("must NOT contain...")
+4. **Platform requirements** — technical constraints from target platforms

package/template/.aioson/skills/squad/references/executor-archetypes.md

@@ -0,0 +1,123 @@
+---
+name: executor-archetypes
+description: Common executor roles and their recommended configurations across squad types
+version: 1.0.0
+---
+
+# Executor Archetypes
+
+Reference catalog of common executor roles. Use as inspiration when designing
+squad executors — adapt to the specific domain, don't copy blindly.
+
+## Content squads
+
+### Scriptwriter / Copywriter
+- **Type:** agent
+- **Model tier:** powerful
+- **Focus:** narrative structure, audience engagement, brand voice
+- **When to use:** Any squad producing written content
+- **Genome:** Apply persona genome if persona-based squad
+
+### Editor / Reviewer
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** clarity, grammar, factual accuracy, brand consistency
+- **When to use:** Squads with quality review requirements
+- **Genome:** Apply persona genome for voice consistency checks
+
+### Researcher / Analyst
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** data gathering, trend analysis, competitive intelligence
+- **When to use:** Squads that need evidence-based content
+- **Genome:** Do not apply persona genome
+
+### SEO Specialist
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** keyword research, meta descriptions, search optimization
+- **When to use:** Content squads targeting search traffic
+
+### Trend Analyst
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** platform trends, competitor analysis, topic suggestions
+- **When to use:** Social media and content squads
+
+### Visual Strategist / Thumbnail Designer
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** visual concepts, thumbnail psychology, brand visual identity
+- **When to use:** Video and social media squads
+
+## Software squads
+
+### Architect
+- **Type:** agent
+- **Model tier:** powerful
+- **Focus:** system design, API contracts, technology decisions
+- **When to use:** Software squads building new systems
+
+### Developer
+- **Type:** agent
+- **Model tier:** powerful
+- **Focus:** implementation, code quality, testing
+- **When to use:** All software squads
+
+### QA Engineer
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** test coverage, edge cases, regression testing
+- **When to use:** Software squads with quality requirements
+
+### DevOps / Infrastructure
+- **Type:** agent or worker
+- **Model tier:** balanced or none
+- **Focus:** deployment, CI/CD, monitoring
+- **When to use:** Software squads with deployment needs
+
+## Universal roles
+
+### Orchestrator
+- **Type:** agent
+- **Model tier:** powerful
+- **Focus:** coordination, workflow management, conflict resolution
+- **When to use:** Every squad with 3+ executors
+- **Genome:** Do not apply persona genome
+- **Special:** Has access to all executor outputs, manages workflow state
+
+### Worker (deterministic)
+- **Type:** worker
+- **Model tier:** none
+- **usesLLM:** false
+- **Focus:** file operations, data transformation, validation, API calls
+- **When to use:** Any step that can be done with a script (no judgment needed)
+- **Examples:** format validator, image resizer, link checker, data formatter
+
+### Fact-Checker
+- **Type:** agent
+- **Model tier:** balanced
+- **Focus:** source verification, claim validation, accuracy
+- **When to use:** Content squads in sensitive domains (health, finance, legal, news)
+
+## Executor classification decision tree
+
+```
+Is the task deterministic (same input → same output)?
+├── Yes → worker (type: worker, modelTier: none, usesLLM: false)
+└── No → agent
+    ├── Does it require complex reasoning or creativity?
+    │   ├── Yes → modelTier: powerful
+    │   └── No → modelTier: balanced
+    └── Is it a quick formatting/checking task?
+        └── Yes → modelTier: fast
+```
+
+## Sizing guidelines
+
+| Squad size | Executors | Orchestrator? |
+|---|---|---|
+| Micro (1-2 outputs) | 2-3 | Optional |
+| Standard (3-5 outputs) | 3-5 | Recommended |
+| Large (6+ outputs) | 5-8 | Required |
+| Pipeline stage | 2-4 | Optional |