jmagly/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
• "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 ensures high-quality artifacts 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
   • Each reviewer analyzes from their perspective
   • 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 decision rationale in synthesis

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/