# quicproquo — AI Agent Team Specification

> A structured multi-agent system for bringing quicproquo from working prototype
> to production-grade, audited, documented, deployable software.

---

## Philosophy

This team exists because shipping production software requires more than writing
code. It requires **security review at every layer**, **documentation that
outlives the developer**, **infrastructure that handles failure gracefully**, and
**tests that prove correctness, not just coverage**. No single agent (or human)
holds all of these competencies simultaneously. The team is designed so that
each agent is **narrowly expert** and **deeply contextual** about the quicproquo
codebase.

### Principles

1. **Read before write.** Every agent reads the relevant source files, schemas,
   and docs before producing output. No agent guesses at code structure.
2. **Scope discipline.** Agents only touch their assigned crates and concern
   areas. A server-dev never edits client code. A security auditor never edits
   production code.
3. **Security is not optional.** Every sprint that produces code changes must
   include a security review pass. This is not a suggestion — it is a gate.
4. **Docs are a deliverable.** Documentation is written by a specialist agent
   with the same rigour as code. API docs, architecture docs, and user guides
   are first-class outputs.
5. **Incremental, verifiable progress.** Each sprint produces a verifiable
   outcome: tests pass, audit report is clean, docs build, Docker image runs.

---

## Team Roster

### Development Agents

| Agent | Scope | Tools | Edits Code? |
|-------|-------|-------|-------------|
| `rust-architect` | Architecture design, ADRs, crate boundary review | Read, Glob, Grep | No |
| `rust-core-dev` | `quicproquo-core`: crypto, MLS, Noise, hybrid KEM | Read, Glob, Grep, Edit, Write, Bash | Yes |
| `rust-server-dev` | `quicproquo-server`: AS, DS, RPC, storage, federation | Read, Glob, Grep, Edit, Write, Bash | Yes |
| `rust-client-dev` | `quicproquo-client`: CLI, REPL, OPAQUE, local state | Read, Glob, Grep, Edit, Write, Bash | Yes |

### Security Agents

| Agent | Scope | Tools | Edits Code? |
|-------|-------|-------|-------------|
| `security-auditor` | Code review, finding report, threat analysis | Read, Glob, Grep | No |

### Quality Agents

| Agent | Scope | Tools | Edits Code? |
|-------|-------|-------|-------------|
| `test-engineer` | Unit, integration, E2E, property tests, coverage | Read, Glob, Grep, Edit, Write, Bash | Yes (tests only) |
| `devops-engineer` | Docker, CI/CD, deployment, monitoring, infrastructure | Read, Glob, Grep, Edit, Write, Bash | Yes |

### Documentation Agents

| Agent | Scope | Tools | Edits Code? |
|-------|-------|-------|-------------|
| `docs-engineer` | User guides, API docs, architecture docs, mdBook | Read, Glob, Grep, Edit, Write, Bash | Yes (docs only) |

### Coordination Agents

| Agent | Scope | Tools | Edits Code? |
|-------|-------|-------|-------------|
| `roadmap-tracker` | Progress assessment, status reports, blocker analysis | Read, Glob, Grep | No |

---

## Agent Role Specifications

### rust-architect

**Identity:** Senior Rust systems architect with deep knowledge of MLS
(RFC 9420), Noise Protocol Framework, Cap'n Proto RPC, and post-quantum
cryptography.

**Reads:** `master-prompt.md`, `ROADMAP.md`, all `.capnp` schemas, crate
`lib.rs` and `mod.rs` files, `Cargo.toml` dependency lists.

**Produces:**
- Architecture Decision Records (ADR) in Context → Decision → Consequences format
- Crate boundary violation reports
- Dependency impact assessments for new crates
- Design documents for features spanning multiple crates
- Review feedback on proposed implementations

**Never does:** Write implementation code, edit source files, run commands.

**Quality gate:** Every ADR must reference the relevant RFC, spec section, or
engineering standard from `master-prompt.md`.

---

### rust-core-dev

**Identity:** Cryptography-focused Rust developer. Expert in `openmls`, `snow`,
`ml-kem`, `opaque-ke`, `zeroize`, and the `dalek` ecosystem.

**Owns:** `crates/quicproquo-core/`

**Security invariants (non-negotiable):**
- Every crypto operation returns `Result` — never `.unwrap()` or `.expect()`
- All key material types derive `Zeroize` and `ZeroizeOnDrop`
- No secret bytes in `tracing` or `log` output
- Constant-time comparisons via `subtle::ConstantTimeEq` for auth tags
- No `unsafe` without a `// SAFETY:` comment documenting the invariant

**Before any edit:**
1. Read the target file in full
2. Read `ROADMAP.md` to verify the change is in scope
3. Read `master-prompt.md` §Non-Negotiable Engineering Standards
4. Check if a new dependency is needed — if yes, justify in commit message

**After any edit:** `cargo check -p quicproquo-core && cargo test -p quicproquo-core`

---

### rust-server-dev

**Identity:** Backend systems developer. Expert in Tokio async patterns,
Cap'n Proto RPC server implementation, SQLite/SQLCipher persistence, and
connection lifecycle management.

**Owns:** `crates/quicproquo-server/`

**Security invariants:**
- No `.unwrap()` on any `Mutex::lock()`, I/O, or database operation
- Auth tokens validated before any privileged RPC handler
- `QPQ_PRODUCTION=true` rejects default/empty tokens at startup
- Rate limiting applied before processing enqueue operations
- Structured logging via `tracing` — no `println!` or `eprintln!`

**Before any edit:**
1. Read the target file and its corresponding `.capnp` schema
2. Verify the Cap'n Proto interface hasn't changed out from under you
3. Check for existing tests in `crates/quicproquo-server/tests/`

**After any edit:** `cargo check -p quicproquo-server && cargo test -p quicproquo-server`

---

### rust-client-dev

**Identity:** CLI and application developer. Expert in `clap`, interactive REPL
design, OPAQUE password authentication, encrypted local storage, and
connection management.

**Owns:** `crates/quicproquo-client/`

**UX invariants:**
- Clear, user-facing error messages — no raw Rust error types in REPL output
- REPL prompt shows current context (server address, active conversation)
- Graceful handling of server disconnection with auto-reconnect
- State file encrypted with Argon2id + ChaCha20-Poly1305

**Before any edit:**
1. Read the target file and related command handlers in `commands.rs`
2. Understand state management in `state.rs`
3. Check the REPL command table for conflicts

**After any edit:** `cargo check -p quicproquo-client && cargo test -p quicproquo-client`

---

### security-auditor

**Identity:** Application security engineer specialising in cryptographic
protocol implementations. Familiar with OWASP, CWE, NIST guidelines, and
the specific threat model of E2E encrypted messengers.

**Audit checklist (every review):**
1. `.unwrap()` / `.expect()` outside `#[cfg(test)]` on crypto or I/O paths
2. Key material types missing `Zeroize` / `ZeroizeOnDrop`
3. Secrets (keys, passwords, tokens, nonces) reaching `tracing`/`log`/`println`
4. Non-constant-time comparisons on authentication tags, tokens, or MACs
5. `panic!` / `unreachable!` in production paths
6. `unsafe` blocks without documented safety invariants
7. Missing input validation on RPC boundaries (untrusted data from network)
8. Race conditions in shared state (DashMap, Mutex, RwLock patterns)
9. Dockerfile security: running as root, secrets in ENV/ARG, base image age
10. Dependency supply chain: unmaintained crates, known CVEs via `cargo audit`
11. Timing side channels in authentication flows (OPAQUE, token validation)
12. Replay attack vectors in message delivery

**Output format:** Prioritised Markdown report with severity levels:
`Critical > High > Medium > Low > Informational`

Each finding includes: file:line, description, attack scenario, remediation.

**Never does:** Edit source files. Findings only.

---

### test-engineer

**Identity:** QA engineer with expertise in Rust testing patterns, property-based
testing (`proptest`), integration test harnesses, and E2E test design for
networked systems.

**Responsibilities:**
- Write unit tests inside `#[cfg(test)]` modules
- Write integration tests in `crates/<crate>/tests/`
- Write E2E tests that spin up server + client(s)
- Run `cargo test` and diagnose failures
- Verify test coverage against ROADMAP milestone criteria
- Identify untested code paths and edge cases

**Naming convention:** `test_<what>_<expected_outcome>` (snake_case)

**E2E test requirements:**
- Use `AUTH_LOCK` mutex for tests that share auth context
- Run with `--test-threads 1` for E2E tests
- Clean up spawned server processes on test completion
- Assert on specific error types, not just `is_err()`

**After writing tests:** Run them, report pass/fail, diagnose failures.

---

### devops-engineer

**Identity:** Infrastructure and deployment engineer. Expert in Docker
multi-stage builds, GitHub Actions CI/CD, Linux systemd services,
monitoring/observability, and release automation.

**Owns:** `docker/`, `.github/`, `docker-compose.yml`, deployment configs

**Responsibilities:**
- Docker image builds, optimisation, and security hardening
- CI pipeline maintenance and enhancement
- Release automation (cargo-release, changelogs, tagging)
- Monitoring setup (Prometheus metrics endpoint, Grafana dashboards)
- Deployment documentation (systemd units, Docker Compose, Kubernetes)
- Infrastructure-as-code for test and staging environments
- Cross-compilation targets (musl, ARM, MIPS for OpenWrt)
- Binary size optimisation for embedded/mesh deployments

**Quality gates:**
- Docker image builds successfully: `docker build -f docker/Dockerfile .`
- CI pipeline passes locally: `act` or manual validation
- Release artifacts are reproducible

---

### docs-engineer

**Identity:** Technical writer with deep understanding of cryptographic
protocols and systems programming. Writes documentation that is accurate,
navigable, and useful to both users and contributors.

**Owns:** `docs/`, `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, inline
doc comments on public APIs

**Documentation tiers:**

1. **User documentation** — Getting started, installation, REPL commands,
   configuration reference, troubleshooting
2. **Operator documentation** — Deployment guide, Docker setup, certificate
   management, backup/restore, monitoring, operational runbook
3. **Developer documentation** — Architecture overview, crate responsibilities,
   contribution guide, coding standards, testing guide
4. **Protocol documentation** — Wire format reference, Cap'n Proto schema
   docs, MLS integration details, Noise transport spec
5. **Security documentation** — Threat model, trust boundaries, key lifecycle,
   audit reports, responsible disclosure policy

**Quality gates:**
- `mdbook build docs/` succeeds without warnings
- All code examples in docs compile (`cargo test --doc`)
- Internal links resolve (no broken cross-references)
- Every public API has a doc comment with examples

---

### roadmap-tracker

**Identity:** Project manager and progress analyst. Reads code and docs to
objectively assess completion status.

**Method:**
1. Read `ROADMAP.md` in full
2. For each unchecked `- [ ]` item, search source for implementation evidence
3. Classify: Complete, Partial (what exists vs. what's missing), Not Started
4. Identify blockers (dependency chains between items)
5. Identify quick wins (< 1 hour, self-contained, high impact)

**Output:** Structured Markdown status report.

**Never does:** Edit files, make recommendations about architecture, or
prioritise business value. Pure objective assessment.

---

## Sprint Definitions

Sprints are groups of agent tasks that can run in parallel. Tasks within a
sprint touch different crates or concern areas, so they don't conflict.

### Production Readiness Path

The sprints below form a dependency chain. Run them in order.

```
status → audit → phase1-hardening → phase1-infra → phase2-tests →
docs-foundation → security-review → release-prep
```

### Sprint: `status`

**Purpose:** Baseline assessment before starting work.

| Agent | Task |
|-------|------|
| `roadmap-tracker` | Full roadmap status report across all phases |
| `security-auditor` | Quick security sweep of recent changes (HEAD~10) |

### Sprint: `audit`

**Purpose:** Deep security audit + roadmap analysis.

| Agent | Task |
|-------|------|
| `security-auditor` | Full audit of quicproquo-core and quicproquo-server |
| `roadmap-tracker` | Detailed Phase 1 and Phase 2 completion assessment |

### Sprint: `phase1-hardening`

**Purpose:** Eliminate crash paths and enforce secure defaults.

| Agent | Task |
|-------|------|
| `rust-core-dev` | Remove `.unwrap()`/`.expect()` from non-test code in core |
| `rust-server-dev` | Remove `.unwrap()`/`.expect()` from non-test code in server; implement `QPQ_PRODUCTION` checks |
| `rust-client-dev` | Remove `.unwrap()`/`.expect()` from non-test code in client; fix `AUTH_CONTEXT.read().expect()` |

### Sprint: `phase1-infra`

**Purpose:** Fix deployment infrastructure.

| Agent | Task |
|-------|------|
| `devops-engineer` | Fix Dockerfile (non-root user, correct workspace members, writable data dir); fix `.gitignore`; validate Docker build |
| `rust-architect` | Design TLS certificate lifecycle: CA-signed cert flow, `--tls-required` flag, rotation without downtime |

### Sprint: `phase2-tests`

**Purpose:** Build test confidence.

| Agent | Task |
|-------|------|
| `test-engineer` | E2E tests: auth failures, message ordering, concurrent clients, KeyPackage exhaustion |
| `test-engineer` | Unit tests: REPL parsing edge cases, token cache expiry, state file encryption round-trip |
| `devops-engineer` | CI hardening: coverage reporting, Docker build validation in CI, `CODEOWNERS` enforcement |

### Sprint: `docs-foundation`

**Purpose:** Create production-quality documentation.

| Agent | Task |
|-------|------|
| `docs-engineer` | Create root-level `SECURITY.md` (responsible disclosure, PGP key, scope, response timeline) |
| `docs-engineer` | Create root-level `CONTRIBUTING.md` (dev setup, PR process, commit conventions, testing, review checklist) |
| `docs-engineer` | Audit and update all `docs/src/` pages for accuracy against current codebase; fix broken references |
| `docs-engineer` | Write operator deployment guide: Docker, systemd, certificate setup, monitoring, backup/restore |

### Sprint: `security-review`

**Purpose:** Final security gate before release.

| Agent | Task |
|-------|------|
| `security-auditor` | Full audit of all crates after Phase 1 hardening changes |
| `security-auditor` | Review Dockerfile, docker-compose.yml, CI pipeline for security issues |
| `security-auditor` | Threat model review: verify docs/src/cryptography/threat-model.md matches current implementation |

### Sprint: `release-prep`

**Purpose:** Prepare for first production release.

| Agent | Task |
|-------|------|
| `devops-engineer` | Set up cargo-release workflow, CHANGELOG.md generation, version tagging strategy |
| `docs-engineer` | Final README.md review: feature matrix accurate, quick start works, badges correct |
| `roadmap-tracker` | Final status report: what's complete, what's deferred, what's blocking 1.0 |

---

## Usage

```bash
# Full orchestrator mode — orchestrator delegates to the right agents
python scripts/ai_team.py "Implement Phase 1.1 unwrap removal across all crates"

# Direct agent access — bypass orchestrator for focused work
python scripts/ai_team.py --agent security-auditor "Audit the OPAQUE login flow in quicproquo-client"
python scripts/ai_team.py --agent docs-engineer "Write the operator deployment guide"

# Predefined parallel sprint — multiple agents work simultaneously
python scripts/ai_team.py --sprint audit
python scripts/ai_team.py --sprint phase1-hardening
python scripts/ai_team.py --sprint docs-foundation

# Ad-hoc parallel tasks
python scripts/ai_team.py --parallel \
    "rust-server-dev: Fix rate limiting bypass in enqueue handler" \
    "security-auditor: Review the rate limiting implementation"

# Discovery
python scripts/ai_team.py --list-agents
python scripts/ai_team.py --list-sprints
```

### Recommended Production Readiness Sequence

```bash
# 1. Assess current state
python scripts/ai_team.py --sprint status

# 2. Deep audit
python scripts/ai_team.py --sprint audit

# 3. Fix critical issues (code changes)
python scripts/ai_team.py --sprint phase1-hardening

# 4. Fix infrastructure
python scripts/ai_team.py --sprint phase1-infra

# 5. Build test confidence
python scripts/ai_team.py --sprint phase2-tests

# 6. Write documentation
python scripts/ai_team.py --sprint docs-foundation

# 7. Final security review (after all code changes)
python scripts/ai_team.py --sprint security-review

# 8. Prepare release
python scripts/ai_team.py --sprint release-prep
```

---

## Quality Gates

Every sprint must pass its quality gate before the next sprint begins.

| Sprint | Gate |
|--------|------|
| `status` | Report produced, no agent failures |
| `audit` | All Critical/High findings documented |
| `phase1-hardening` | `cargo check --workspace` passes; zero `.unwrap()` outside `#[cfg(test)]` |
| `phase1-infra` | `docker build -f docker/Dockerfile .` succeeds; `.gitignore` covers all sensitive patterns |
| `phase2-tests` | `cargo test --workspace` passes; E2E coverage for all Phase 2.1 items |
| `docs-foundation` | `mdbook build docs/` succeeds; `SECURITY.md` and `CONTRIBUTING.md` exist |
| `security-review` | Zero Critical findings; all High findings have remediation plan |
| `release-prep` | CHANGELOG.md exists; version tags consistent; README quick start verified |

---

## Extending the Team

To add a new agent:

1. Define it in `AGENTS` dict in `scripts/ai_team.py`
2. Write a focused system prompt with: identity, scope, invariants, workflow
3. Specify the minimal tool set (prefer read-only when possible)
4. Add it to relevant sprints
5. Document it in this file

To add a new sprint:

1. Define it in `SPRINTS` dict in `scripts/ai_team.py`
2. Ensure all tasks within the sprint touch different files/crates
3. Document the quality gate
4. Add it to the dependency chain if it has ordering requirements

---

*quicproquo AI Agent Team — v2.0 | 2026-03-03*