artifact-orchestration

artifact-orchestration

Orchestrate multi-agent artifact generation with the Primary Author → Parallel Reviewers → Synthesizer → Archive pattern.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "SAD" → Software Architecture Document
• "software architecture document"
• "architecture document"
• "ADR" → Architecture Decision Record
• "generate [artifact]" for named SDLC artifacts (test plan, deployment plan, requirements)

Purpose

This skill implements the core AIWG multi-agent documentation pattern that supports artifact quality through:

• Single primary author for consistency
• Parallel expert reviews for coverage
• Synthesis of feedback for conflict resolution
• Formal archival with metadata tracking

Behavior

When triggered, this skill orchestrates:

1. Artifact identification:

   • Parse requested artifact type
   • Map to template and primary author
   • Identify required reviewers

2. Workspace setup:

   • Create .aiwg/working/{type}/{name}/
   • Initialize metadata via artifact-metadata skill
   • Load relevant template via template-engine skill

3. Primary author dispatch:

   • Launch primary author agent with template
   • Provide context (requirements, existing artifacts)
   • Receive draft v0.1

4. Parallel review dispatch:

   • Launch 3-5 reviewers via parallel-dispatch skill
   • Commit each reviewer's initial answer before exposing others' judgments; retain dissent and criteria/check references
   • Agreement is not proof, including same-vendor and cross-vendor agreement. Consequential claims require an executable check or accountable human acceptance. Prefer independent voting, or structured review with diverse initial answers and calibrated confidence, over plain debate. Record observed evaluator model/vendor/family, acceptance criteria reference, generator/evaluator disagreements and a re-review link after material fixes. Do not claim reduced human-review time. See $AIWG_ROOT/docs/decision/evaluator-calibration.md for calibration and REF-2922, REF-2923, REF-2919/2921 public sources.
   • Collect structured feedback

5. Synthesis:

   • Invoke Documentation Synthesizer agent
   • Merge feedback and resolve conflicts
   • Generate final artifact

6. Archive:

   • Move to .aiwg/{category}/
   • Update metadata to baselined
   • Update artifact index

Artifact Configuration

Software Architecture Document (SAD)

artifact: software-architecture-document
template: analysis-design/software-architecture-doc-template
primary_author: architecture-designer
reviewers:
  - security-architect
  - test-architect
  - requirements-analyst
  - technical-writer
output: .aiwg/architecture/sad.md

Test Plan

artifact: test-plan
template: test/test-plan-template
primary_author: test-architect
reviewers:
  - security-auditor
  - requirements-analyst
  - devops-engineer
output: .aiwg/testing/test-plan.md

Deployment Plan

artifact: deployment-plan
template: deployment/deployment-plan-template
primary_author: deployment-manager
reviewers:
  - devops-engineer
  - security-architect
  - reliability-engineer
  - support-lead
output: .aiwg/deployment/deployment-plan.md

Requirements Specification

artifact: software-requirements-spec
template: requirements/srs-template
primary_author: requirements-analyst
reviewers:
  - domain-expert
  - system-analyst
  - test-architect
  - architecture-designer
output: .aiwg/requirements/srs.md

Threat Model

artifact: threat-model
template: security/threat-model-template
primary_author: security-architect
reviewers:
  - privacy-officer
  - architecture-designer
  - devops-engineer
output: .aiwg/security/threat-model.md

Workflow Sequence

┌─────────────────────────────────────────────────────────┐
│ 1. SETUP                                                │
│    • Create workspace: .aiwg/working/{type}/{name}/     │
│    • Initialize metadata.json                           │
│    • Load template                                      │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ 2. PRIMARY AUTHOR                                       │
│    • Dispatch: architecture-designer (for SAD)          │
│    • Input: template, requirements, context             │
│    • Output: drafts/v0.1-primary.md                     │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ 3. PARALLEL REVIEW (single message, multiple agents)    │
│    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐  │
│    │ security-    │ │ test-        │ │ requirements-│  │
│    │ architect    │ │ architect    │ │ analyst      │  │
│    └──────┬───────┘ └──────┬───────┘ └──────┬───────┘  │
│           │                │                │          │
│           ▼                ▼                ▼          │
│    reviews/security.md  reviews/test.md  reviews/req.md│
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ 4. SYNTHESIS                                            │
│    • Dispatch: documentation-synthesizer                │
│    • Input: draft + all reviews                         │
│    • Output: synthesis/final.md                         │
│    • Conflicts: document with rationale                 │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│ 5. ARCHIVE                                              │
│    • Move to: .aiwg/{category}/{artifact}.md            │
│    • Update metadata: status=baselined, version=1.0.0   │
│    • Archive workspace to: .aiwg/archive/{date}/        │
└─────────────────────────────────────────────────────────┘

Usage Examples

Generate SAD

User: "Create the Software Architecture Document"

Skill orchestrates:
1. Setup workspace for SAD
2. Dispatch architecture-designer with SAD template
3. Launch parallel reviews (security, test, requirements, writer)
4. Synthesize feedback
5. Archive to .aiwg/architecture/sad.md

Output:
"SAD generation complete.
Version: 1.0.0
Status: Baselined
Location: .aiwg/architecture/sad.md

Reviews:
✓ Security Architect: Approved with suggestions
✓ Test Architect: Approved
✓ Requirements Analyst: Approved
✓ Technical Writer: Approved (minor edits)

Conflicts resolved: 2
- Auth approach: Chose JWT per security recommendation
- Caching strategy: Balanced performance vs complexity"

Generate with Context

User: "Generate deployment plan for production release"

Skill uses project-awareness context:
- Phase: Construction
- Environment: AWS
- Compliance: SOC2

Tailors template and reviewer focus accordingly.

Configuration

Custom Artifact Types

Add custom artifact configurations in .aiwg/config/artifacts.yaml:

artifacts:
  custom-api-doc:
    template: custom/api-documentation
    primary_author: api-documenter
    reviewers:
      - security-auditor
      - api-designer
      - technical-writer
    output: .aiwg/architecture/api-docs/

Review Depth

review_config:
  depth: standard  # minimal, standard, comprehensive
  timeout: 300     # seconds per reviewer
  require_unanimous: false  # or true for critical artifacts

Integration

This skill uses:

• parallel-dispatch: For launching reviewer agents
• artifact-metadata: For tracking artifact lifecycle
• template-engine: For loading and instantiating templates
• project-awareness: For context about current phase and state

Error Handling

Reviewer Timeout

If a reviewer times out:

1. Mark review as "incomplete"
2. Continue with other reviews
3. Flag in final synthesis
4. User can re-run partial review

Conflicting Reviews

When reviewers disagree:

1. Document both positions
2. Apply priority rules:
   • Security concerns take precedence
   • Compliance concerns take precedence
   • Domain expert breaks ties
3. Record both positions and the criteria/check or human acceptance reference in synthesis; precedence and consensus do not prove correctness
4. Re-review material fixes with fresh source bindings and link the earlier review

Missing Template

If template not found:

1. List similar templates
2. Offer to proceed with generic structure
3. Or abort with guidance

Output Locations

Artifact	Output Path
SAD	.aiwg/architecture/sad.md
ADR	.aiwg/architecture/adr-{number}.md
Test Plan	.aiwg/testing/test-plan.md
Deployment Plan	.aiwg/deployment/deployment-plan.md
SRS	.aiwg/requirements/srs.md
Threat Model	.aiwg/security/threat-model.md

References

• Multi-agent pattern: docs/multi-agent-documentation-pattern.md
• Templates: templates/
• Agent definitions: agents/