feat: define intelligent collaboration modes for AgentFlow SDLC

[smota]

Epic: #115

Background & Problem Statement

AgentFlow SDLC's core value is reducing cognitive load for AI/Agentic development through an opinionated SDLC, not maximizing automation for its own sake. The framework should still increase harness leverage and collective AI intelligence where it improves decisions, lowers uncertainty, and preserves the existing evidence and guardrail model.

Current docs define single-agent default, optional multi-agent routing, capability resolution, role-pass evidence, and no-false-claim guardrails. What is missing is a small set of named collaboration modes and decision rules that let agents and humans understand when extra intelligence is worth the coordination cost.

Proposed Solution

Define an opinionated collaboration model that keeps the visible SDLC simple while allowing harness-managed helper intelligence behind stable roles.

Core modes:

• auto-minimal — default; choose the smallest helper set that reduces risk or uncertainty.
• single-agent — one orchestrator performs all roles.
• advisory — one or more read-only helpers provide focused findings.
• council — role-local panel at major decision points, especially architecture/review.
• parallel-discovery — bounded read-only fanout for broad repo discovery.
• spike — isolated child worktree experiment, opt-in and high-cost.
• human-gated — human authority required for high-assurance gates.

Requirements

• Add docs that explain collaboration modes in human-readable and agent-executable terms.
• Define the “smallest sufficient collaboration” / decision budget rule.
• Map issue profile, risk, uncertainty, and touched surface to collaboration modes.
• Explain that “multi-agent” is an internal mechanism, not a user-facing goal.
• Preserve single-agent default for routine work.
• Preserve GitHub evidence, role-pass, handover, PR manifest, and follow-up discipline.
• Include examples showing visible output stays compact even when helper agents are used.

Technical Design

Suggested docs:

• docs/intelligent-collaboration.md
• updates to docs/capabilities.md
• updates to docs/agent-workflow.md
• updates to agents/agentflow-sdlc/runtime-capabilities.md
• updates to agents/agentflow-sdlc/execution-model.md

Suggested decision rule:

Spend AI tokens where uncertainty is high.
Spend workflow ceremony where audit risk is high.
Spend human attention only where authority is needed.

Feature Tracking

• Define collaboration modes and selection triggers.
• Document decision budget and smallest-sufficient-collaboration rule.
• Add strategy synthesis and dissent summary guidance.
• Add examples for single-agent, advisory, council, parallel-discovery, spike, and human-gated modes.
• Update agent package docs to reference the model.

Acceptance criteria

• Humans can understand when AgentFlow uses extra AI intelligence and why.
• Agents can select a collaboration mode without inventing process.
• Default mode remains single-agent/auto-minimal for low-risk work.
• Collaboration mode never bypasses role-pass, review, validation, or GitHub evidence.
• Mode selection is documented in workflow evidence with a concise rationale.

Test plan

• Run pnpm format:check.
• Run pnpm test:workflow.
• Add or update docs/examples validation if available.

Workflow classification

• Profile: standard
• Risk: low
• Effort: medium
• Change surfaces: docs, agent package, workflow guidance
• Review: self-review acceptable; human editorial review useful.

[github-actions]

Integrated into development by PR #116: #116

Merge commit: 5d08ddbe7e3cefe8fe59d9421a86cea781514495
Release/promotion to main is tracked separately.

[github-actions]

Integrated into development by PR #117: #117

Merge commit: 0a19c0a24cb234e21f9f48dd7034f0a4a7ad55bd
Release/promotion to main is tracked separately.

[github-actions]

Integrated into development by PR #118: #118

Merge commit: 6cd23f4289fff1ffd01dfca4605711030dd333f0
Release/promotion to main is tracked separately.