# IDEA-020: App Composition — Teams and Multi-App Orchestration

**Date:** 2026-03-04
**Source:** user
**Status:** raw

## Idea

Apps (IDEA-019) are single-purpose bundles. When you compose multiple apps together with a coordinating pipeline, you get a **Team** — a higher-level unit that simulates a real functional team (dev team, marketing team, design team). Teams can further compose into **Organizations**.

This creates a natural hierarchy:

```
Level 1 — Tool:     github-mcp, filesystem-mcp
Level 2 — Agent:    pr-analyzer, code-reviewer
Level 3 — App:      github-pr-reviewer, sdd-pipeline
Level 4 — Team:     software-dev-team, marketing-team
Level 5 — Org:      startup-operations
```

---

## Composition Model

Apps don't inherit from each other. They **share resources** and **call each other's pipelines**.

```yaml
# software-dev-team/app.yaml
name: software-dev-team
type: team               # declares this is a composition

uses:
  - sdd-pipeline         # reuse entire SDD app
  - github-pr-reviewer   # reuse PR review app
  - deployment-app

pipeline: dev-team-workflow.yaml
```

```yaml
# dev-team-workflow.yaml
steps:
  - name: spec
    call: sdd-pipeline/main          # calls another app's pipeline
    input: $trigger.feature_request
    output: $spec

  - name: review
    call: github-pr-reviewer/pr-review
    input: $spec.pr_url
    condition: $spec.pr_created == true
```

---

## Examples

### Software Dev Team
```
software-dev-team
  ├── sdd-pipeline          (spec → plan → code → review → QA → acceptance)
  ├── github-pr-reviewer    (automated PR analysis + inline comments)
  ├── deployment-app        (staging → prod pipeline)
  └── monitoring-app        (error alerts → auto-triage)
```

### Marketing Team
```
marketing-team
  ├── content-writer        (blog posts, social copy)
  ├── seo-analyzer          (keyword research, scoring)
  ├── social-poster         (Twitter, LinkedIn, Instagram)
  └── analytics-reporter    (weekly performance digest)
```

### Podcast Ghost
```
podcast-ghost
  ├── research-app          (topic deep-dive, source gathering)
  ├── script-writer         (episode structure + script)
  ├── show-notes-gen        (chapters, timestamps, links)
  └── distributor           (RSS, Spotify, YouTube descriptions)
```

### Startup Ops
```
startup-operations
  ├── software-dev-team     (team app)
  ├── marketing-team        (team app)
  ├── finance-tracker       (app)
  └── customer-support      (app)
```

---

## Key Design Questions

### 1. Agent sharing vs. copies

Option A — **Shared agents** (recommended):
```
software-dev-team uses sdd-pipeline
sdd-pipeline uses code-reviewer agent
github-pr-reviewer also uses code-reviewer agent
→ same agent instance, loaded once
```

Option B — **Per-app copies**:
```
each app owns its own agent instances
→ safe isolation but bloated
```

Recommendation: shared agents by default, explicit `isolate: true` in app.yaml when needed.

### 2. Pipeline-to-pipeline call mechanism

Option A — **Direct call** (synchronous):
```yaml
- call: other-app/pipeline-name
  input: $prev.output
  await: true
```

Option B — **Event bus** (async):
```yaml
- emit: sdd.spec.completed
  payload: $spec
# other-app's pipeline subscribes to this event
```

Both needed: direct call for sequential workflows, event bus for loose coupling and parallel execution.

### 3. Credential ownership

When two apps in a team need the same credential (`GITHUB_PAT_TOKEN`):
- Credential declared once at team level
- Apps reference by name, don't own the credential
- Team manifest declares `requires.credentials` as the union of all member apps

### 4. Conflict resolution

If two apps define an agent with the same name:
- Last writer wins? → unpredictable
- Namespace by app: `sdd-pipeline/code-reviewer` vs `github-pr-reviewer/code-reviewer`
- Explicit alias in team manifest: `alias: sdd-reviewer: sdd-pipeline/code-reviewer`

---

## What This Enables

- **Marketplace teams**: publish a complete "software dev team" that works out of the box
- **Eva self-modification**: Eva can install a `sdd-pipeline` team on herself and use it to propose and implement her own improvements — agents all the way down
- **Franchise model**: companies publish their internal team templates as iEvo Team apps — install once, replicate process across projects

---

## Open Questions

- [ ] Circular composition: can App A use App B which uses App A? Must detect and reject.
- [ ] Versioning: if `software-dev-team` pins `sdd-pipeline@1.2.0` but `startup-ops` needs `sdd-pipeline@2.0.0` — conflict resolution?
- [ ] Team-level memory: does a team have shared memory across its member apps, or is memory per-app?
- [ ] Pipeline event bus: is this iEvo-native or delegate to an external message broker (Redis, NATS)?
- [ ] Max composition depth: org → team → app → agent. Is 4 levels enough? Should there be a limit?

---

## Related

- **IDEA-019**: iEvo Apps (parent concept — apps are the building blocks of teams)
- **IDEA-017**: Provider-agnostic architecture (UAF agent format used inside apps)
- **IDEA-016**: Smart spec pipeline (SDD pipeline = first built-in team app candidate)
- **PROP-2026-03-04-plugin-system.md** (teams extend the plugin system)
- **PROP-2026-03-04-universal-orchestration-architecture.md** (master architecture)
