docs: align AgentFlow 1.0 narrative

README.md

@@ -1,7 +1,11 @@
 # AgentFlow SDLC
 
+Use AI more confidently in software delivery.
+
 AgentFlow SDLC is an open-source process layer for AI-assisted software delivery. It makes agent work understandable, reviewable, resumable, and safe to ship through GitHub.
 
+AgentFlow SDLC 1.0 is the first mature release of this framework: a stable process layer for teams that want the speed of AI-assisted development without losing clarity, review, or control.
+
 AI assistants can write code quickly. AgentFlow helps teams keep the surrounding delivery system clear: what was requested, why decisions were made, what changed, what was validated, who reviewed it, and what should happen next.
 
 This repository is both the distributable framework and a live example of the workflow in use. Its own issues, workflow-status comments, handover comments, PR manifests, hooks, and validators demonstrate the intended operating model.
@@ -20,6 +24,12 @@ This repository is both the distributable framework and a live example of the wo
 
 Use it when you want agent-assisted work to be reviewable, auditable, and easy to resume instead of being hidden in one chat session.
 
+## Intelligent collaboration
+
+AgentFlow SDLC 1.0 adds intelligent collaboration: more AI intelligence when it improves a decision, not more agents for their own sake. The default remains one executor carrying context end to end. When uncertainty is high, AgentFlow can use focused advisors, broader discovery, isolated experiments, or human gates while preserving one accountable owner and compact durable evidence.
+
+The operating principle is simple: **increase intelligence per decision, not agents per task**.
+
 ## Why this matters now
 
 AI-native engineering has created a new failure mode: the code may be fast, but the work can become hard to understand. Important requirements, architecture tradeoffs, validation evidence, and review boundaries often remain trapped in a single LLM conversation. That makes adoption harder for teams that need GitHub history, compliance evidence, repeatable handoffs, or clear human approval gates.

agents/agentflow-sdlc/AGENT.md

@@ -1,10 +1,10 @@
 # AgentFlow SDLC Agent
 
-AgentFlow SDLC Agent is a portable, harness-neutral agent definition for running reviewable AI-assisted software delivery through GitHub evidence.
+AgentFlow SDLC Agent is a portable, harness-neutral agent definition for helping teams use AI more confidently in software delivery through reviewable GitHub evidence.
 
 ## Goal
 
-Help a software project move from an issue or maintainer request to a validated PR while keeping the work understandable, auditable, resumable, and safe for real teams.
+Help a software project move from an issue or maintainer request to a validated PR while keeping the work understandable, auditable, resumable, and safe for real teams. Use the smallest sufficient collaboration pattern: more intelligence when it improves the decision, not more agents for their own sake.
 
 ## Target users
 
@@ -32,7 +32,8 @@ Adapters and consuming-project instructions may specialize invocation details, b
 - Role phases are analyst, architect, developer planning, developer, tester, review, tech writer, and PR readiness. Product/JTBD is optional when shaping is needed.
 - GitHub issues, workflow-status comments, handover comments, commits, and PR bodies are durable evidence.
 - Local `.agent-runs/` files are scratch artifacts and must not be committed.
-- Optional multi-agent or sub-agent support is allowed only when it adds value or project routing selects another executor.
+- Optional collaboration support is allowed only when it adds value or project routing selects another executor.
+- Parent synthesis is required when helper intelligence is used; durable evidence stays compact.
 - Multi-agent claims require role-attribution evidence; same-context helper calls do not prove independent review.
 
 ## Accepted work

agents/agentflow-sdlc/README.md

@@ -2,7 +2,9 @@
 
 This package is the portable agent definition for **AgentFlow SDLC**, an open-source process layer for reviewable AI-assisted software delivery.
 
-Use it when another project needs a copyable agent contract for issue-driven SDLC work, harness capability mapping, sub-agent handoffs, validation, and continuous improvement.
+AgentFlow SDLC 1.0 is the first mature release of this package shape: a stable agent contract for teams that want AI speed without losing clarity, review, or control.
+
+Use it when another project needs a copyable agent contract for issue-driven SDLC work, intelligent collaboration, capability mapping, validation, and continuous improvement.
 
 ## Files
 
@@ -21,6 +23,10 @@ Use it when another project needs a copyable agent contract for issue-driven SDL
 | `continuous-improvement-plan.md`   | Feedback, regression, changelog, and maturity loop.                 |
 | `CHANGELOG.md`                     | Package-level change log.                                           |
 
+## 1.0 collaboration stance
+
+AgentFlow can use focused helper intelligence when it improves a decision, but it does not make multi-agent activity the goal. The default remains a simple, reviewable SDLC path with one accountable owner and compact durable evidence.
+
 ## Canonical sources
 
 This package references, rather than replaces, repository authorities: `../../AGENTS.md`, `../../docs/agent-workflow.md`, `../../docs/issue-standards.md`, `../../docs/capabilities.md`, and `../../docs/execution-targets.md`.

docs/agentflow-in-5-minutes.md

@@ -1,6 +1,6 @@
 # AgentFlow SDLC in 5 minutes
 
-AgentFlow SDLC is an open-source process layer for AI-assisted software delivery. It helps teams turn fast but opaque AI coding sessions into work that is understandable, reviewable, resumable, and safe to ship through GitHub.
+AgentFlow SDLC is an open-source process layer for AI-assisted software delivery. Version 1.0 is the first mature release: a stable way for teams to use AI more confidently while keeping work understandable, reviewable, resumable, and safe to ship through GitHub.
 
 ## The problem it solves
 
@@ -37,6 +37,12 @@ flowchart LR
 
 AgentFlow is **single-agent by default**. One executor can carry context end to end while switching through explicit roles: analyst, architect, developer, tester, reviewer, tech writer, and PR-readiness.
 
+## Intelligent collaboration when it helps
+
+AgentFlow 1.0 can use more AI intelligence without asking people to manage more agents. Clear work stays single-agent. Uncertain work can invite focused advisors. Broad work can use bounded discovery. Sensitive work keeps human approval. In every case, the parent workflow owns synthesis and leaves compact evidence.
+
+The guiding rule is: **increase intelligence per decision, not agents per task**.
+
 Optional multi-agent routing is available when it adds value, but it is explicit and evidenced. A multi-agent claim must show which intelligence executed which role, how it was reached, and whether review was independent.
 
 ## The primary way to evaluate it
@@ -57,6 +63,16 @@ node bin/cli.mjs update-prompt --target /path/to/your-project
 
 Both flows are read-only first and approval-gated before setup or sync commands run.
 
+## What you see vs. what AgentFlow may coordinate
+
+| You see                       | AgentFlow may coordinate                               |
+| ----------------------------- | ------------------------------------------------------ |
+| A clear architecture decision | focused risk, testability, or documentation checks     |
+| A readable PR summary         | structured evidence from the work session              |
+| A validation result           | bounded fix/check loops                                |
+| A handoff comment             | enough context for another person or agent to continue |
+| A human approval gate         | review retained for consequential decisions            |
+
 ## What the evidence looks like
 
 AgentFlow does not ask reviewers to trust a hidden agent session. A healthy run leaves:

docs/intelligent-collaboration.md

@@ -1,12 +1,12 @@
 # Intelligent collaboration
 
-AgentFlow SDLC uses intelligent collaboration to increase decision quality without increasing the cognitive load of AI-assisted delivery. The goal is not more agents. The goal is better SDLC decisions with compact, auditable evidence.
+AgentFlow SDLC 1.0 uses intelligent collaboration to help teams use AI more confidently in software delivery. The goal is not more agents. The goal is better SDLC decisions with less coordination burden and compact, auditable evidence.
 
 ## Core principle
 
 Increase intelligence per decision, not agents per task.
 
-Harnesses may run temporary helper intelligence behind stable SDLC roles, but the visible workflow remains the same: issue, role phases, evidence, validation, PR manifest, and follow-up issues.
+Agent tools may run temporary helper intelligence behind stable SDLC roles, but the visible workflow remains the same: issue, role phases, evidence, validation, PR manifest, and follow-up issues.
 
 ## Decision budget
 

docs/releases/v1.0.0.md

@@ -0,0 +1,32 @@
+# AgentFlow SDLC v1.0.0 — Reviewable AI-assisted delivery
+
+AgentFlow SDLC 1.0 is the first mature release of the framework: a stable process layer for teams that want the speed of AI-assisted development without losing clarity, review, or control.
+
+## What 1.0 means
+
+This release treats AgentFlow as an opinionated SDLC for humans and agents, not as a generic automation layer. The framework keeps work understandable by making roles, evidence, validation, handoffs, and review decisions explicit.
+
+## User-facing outcomes
+
+- **Use AI more confidently in software delivery.** AI-assisted work follows a visible path from request to pull request.
+- **Keep review meaningful.** PRs can show scope, implementation summary, validation, review mode, docs decisions, and follow-ups.
+- **Resume work without replaying a chat.** Issues, handovers, and PR manifests preserve durable context.
+- **Use more AI intelligence when it helps.** Intelligent collaboration can add focused advisors, discovery, experiments, or human gates without making multi-agent activity the goal.
+- **Preserve human authority.** Consequential and high-assurance decisions keep explicit human review.
+
+## Mature capability areas
+
+- role-based SDLC phases from analysis through PR readiness;
+- LLM-assisted onboarding and update flows;
+- canonical AgentFlow agent package;
+- reusable role-agent packages;
+- intelligent collaboration modes;
+- collaboration plan resolver and evidence validator;
+- compact workflow-status, handover, and PR evidence;
+- eval fixtures and improvement-loop scaffolding.
+
+## Design principle
+
+> Increase intelligence per decision, not agents per task.
+
+AgentFlow 1.0 keeps single-agent execution as the default and uses the smallest sufficient collaboration pattern when uncertainty, scope, or authority needs more attention.