@jaimevalasek/aioson 1.7.2 → 1.9.0

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

@@ -1,106 +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.
+---
+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

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

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