joemooney · Oct 29, 2026 · Oct 30, 2026 · Oct 30, 2026
diff --git a/docs/product-workflow.md b/docs/product-workflow.md
@@ -0,0 +1,41 @@
+# From a conversation to a maintainable system
+
+<!-- trace:TASK-B6B1278890774EF993D2EBC327862470-108 | ai:codex -->
+
+AIDA connects the work people and agents do with the intent behind it. Start with a conversation, develop the system, and keep enough structured context for the next change. You can remain involved throughout or delegate selected stages under the project's policy.
+
+## The collaboration loop
+
+- **Discuss the outcome.** A person and coding agent explore the problem, constraints and alternatives. The person can develop, challenge and review the work throughout.
+- **Capture agreed intent.** The agent records requirements, acceptance criteria and consequential decisions in the project graph. Ask to inspect the record before implementation.
+- **Own a bounded change.** The work is assigned to a role and session. Isolated worktrees give separate changes their own checkout; leases and queue state coordinate ownership.
+- **Implement and validate.** Build the agreed behavior, link it to its specs and run the relevant checks. New discoveries can require revised intent or a separate decision.
+- **Review independently.** In the governed PR workflow, a separate reviewer evaluates the current change and its evidence. The author's self-check is useful preparation and does not constitute independent approval.
+- **Integrate under policy.** The authorized shipping path checks the applicable evidence and gates. Integration can lead to another conversation; a merged change and a released product are separate milestones.
+
+These are stages in an operating model, not a promise that every project uses one autonomy mode. The [configuration guide](configuration-guide.md) explains how execution mode, guidance and authority remain distinct. The graphic is explanatory, not a live dashboard.
+
+## What progress means
+
+In the standard PR lifecycle, Draft captures an idea, Approved records agreement, In Progress means implementation has started, and Done means work is finished on a branch. Completed follows recognized integration evidence on the default branch. Planned is optional; Needs Attention and terminal dispositions handle work that cannot simply proceed.
+
+A status is a recorded signal, not proof that deployed behavior is correct. Read the [lifecycle reference](lifecycle.md) for transition rules and exceptions. Deployment and release need their own project workflow.
+
+## Four records with different jobs
+
+- **Code history:** source, tests, trace comments and commits live on the product's code branches. Traces connect implementation to structured intent; they do not themselves approve a change.
+- **Canonical intent:** the default git-canonical store uses the orphan `aida-store` branch and a live `.aida-store/` worktree. YAML spec objects contain requirements, relationships, comments and transition history. Store history is separate from code history and must be synchronized deliberately. Sibling-store projects use their configured separate store repository.
+- **Derived read cache:** `.aida/cache.db` indexes store data for reads. It is rebuildable from the available canonical store and is not a replacement for that history. Cache reads can report stale, deferred or busy context; inspect freshness rather than assuming every displayed view is current.
+- **Local operational evidence:** session files, verdict artifacts, holds and handoff notes have local runtime locations under `.aida/`; machine grants and mandates have their own local authority context. Their scope, validation and retention differ from canonical intent. A store clone or cache rebuild does not recreate all of them or confer authority.
+
+This is a map of responsibilities, not a backup recipe or complete directory inventory. Some coordination events also live in the store, and the [storage reference](cli/10-storage.md) describes the particular data surfaces. Back up the canonical histories and needed local evidence according to your actual project setup.
+
+## Keep the intent useful
+
+For maintenance, ask the agent to locate the requirement and decision behind an existing behavior before changing it. `aida why` can resolve a code location through nearby trace comments. For enhancement, use the current acceptance criteria and relationships to identify what needs revising. For collaboration, hand over the agreed intent, implementation links and unresolved questions so another person or agent can continue.
+
+The graph is structured project memory, not a transcript archive or complete observation of everything an agent did. Its value depends on what was captured and kept accurate. Ask for a capture sweep at handoff, verify the record and keep consequential corrections explicit.
+
+## Read the evidence behind the model
+
+The [getting-started guide](getting-started.md) covers everyday conversational use. Operators can inspect `aida show`, `aida history`, `aida status` and `aida cache status`; exact flags are in command help. Contributors can inspect the [cache implementation](../aida-core/src/db/cache.rs), [storage abstraction](../aida-core/src/storage.rs), [session lifecycle](../aida-cli-lib/src/session_end.rs) and [product architecture](../OVERVIEW.md#architecture) for the source behind these distinctions.
diff --git a/docs/showcase/assets/workflow.svg b/docs/showcase/assets/workflow.svg
diff --git a/docs/showcase/build.py b/docs/showcase/build.py
@@ -12,7 +12,8 @@
 ROOT = Path(__file__).resolve().parents[2]
 SITE = ROOT / 'docs/showcase'
 PAGES = [('getting-started.md', 'getting-started.html', 'Get started'),
-         ('configuration-guide.md', 'configuration.html', 'Configuration')]
+         ('configuration-guide.md', 'configuration.html', 'Configuration'),
+         ('product-workflow.md', 'workflow.html', 'Workflow')]
 
 
 def inline(text):

diff --git a/docs/showcase/configuration.html b/docs/showcase/configuration.html
@@ -8,7 +8,7 @@
 <body>
 <!-- trace:TASK-B6B1278890774EF993D2EBC327862470-106 | ai:codex -->
 <a class="skip" href="#main">Skip to content</a>
-<header class="guide-header"><a class="brand" href="index.html"><span aria-hidden="true">✳</span> AIDA</a><nav aria-label="Product navigation"><a href="index.html">Product</a><a href="getting-started.html">Get started</a><a href="configuration.html" aria-current="page">Configuration</a></nav></header>
+<header class="guide-header"><a class="brand" href="index.html"><span aria-hidden="true">✳</span> AIDA</a><nav aria-label="Product navigation"><a href="index.html">Product</a><a href="getting-started.html">Get started</a><a href="configuration.html" aria-current="page">Configuration</a><a href="workflow.html">Workflow</a></nav></header>
 <main id="main" class="guide"><p class="eyebrow">THE GOVERNED SOFTWARE FACTORY</p><figure><img class="guide-graphic" src="assets/configuration.svg" alt="Configuration diagram; details follow in the source guide"></figure><h1 id="configure-the-way-your-team-works">Configure the way your team works</h1>
 <p>AIDA separates what work means, how it is dispatched and who may authorize its next step. You can start with conversational development and configure more delegation for selected work. Configuration is a product capability: teams can choose agent profiles, execution modes, work protocols and presentation preferences without adopting one fixed operating pattern.</p>
 <h2 id="six-places-to-make-a-choice">Six places to make a choice</h2>

diff --git a/docs/showcase/getting-started.html b/docs/showcase/getting-started.html
@@ -8,7 +8,7 @@
 <body>
 <!-- trace:TASK-B6B1278890774EF993D2EBC327862470-106 | ai:codex -->
 <a class="skip" href="#main">Skip to content</a>
-<header class="guide-header"><a class="brand" href="index.html"><span aria-hidden="true">✳</span> AIDA</a><nav aria-label="Product navigation"><a href="index.html">Product</a><a href="getting-started.html" aria-current="page">Get started</a><a href="configuration.html">Configuration</a></nav></header>
+<header class="guide-header"><a class="brand" href="index.html"><span aria-hidden="true">✳</span> AIDA</a><nav aria-label="Product navigation"><a href="index.html">Product</a><a href="getting-started.html" aria-current="page">Get started</a><a href="configuration.html">Configuration</a><a href="workflow.html">Workflow</a></nav></header>
 <main id="main" class="guide"><p class="eyebrow">THE GOVERNED SOFTWARE FACTORY</p><h1 id="build-as-you-already-work">Build as you already work</h1>
 <p>Keep working with your conversational coding agent. Explain the change, discuss tradeoffs, inspect the implementation and decide what should happen next. With AIDA configured in the project, your agent can use its CLI or MCP tools to maintain a durable record of requirements, decisions and the work that fulfills them.</p>
 <p>The result is the system you developed and a record of its intent: why it behaves that way, what was agreed and where the implementation came from. That record helps you maintain and enhance the system and work with other people and agents.</p>

diff --git a/docs/showcase/index.html b/docs/showcase/index.html
@@ -13,7 +13,7 @@
 <a class="skip" href="#main">Skip to content</a>
 <header class="nav">
   <a class="brand" href="#" aria-label="AIDA home"><span class="brand-symbol" aria-hidden="true">✳</span>AIDA<span class="brand-caption">THE GOVERNED SOFTWARE FACTORY</span></a>
-  <nav aria-label="Main navigation"><a href="getting-started.html">Get started</a><a href="configuration.html">Configuration</a><a href="#factory">The factory</a><a href="#autonomy">Autonomy</a><a href="#capabilities">Capabilities</a></nav>
+  <nav aria-label="Main navigation"><a href="getting-started.html">Get started</a><a href="configuration.html">Configuration</a><a href="workflow.html">Workflow</a><a href="#factory">The factory</a><a href="#autonomy">Autonomy</a><a href="#capabilities">Capabilities</a></nav>
   <a class="nav-cta" href="#start">Explore AIDA <span aria-hidden="true">↗</span></a>
 </header>
 <main id="main">
@@ -98,7 +98,7 @@ <h2>Built for the work<br>between the agents.</h2>
 <section class="start shell" id="start">
  <p class="section-index">06 / START WITH ONE CHANGE</p><h2>Give the next agent<br>more than a prompt.</h2><p>Choose a bounded change. Write down what success means. Run it through AIDA and inspect the resulting evidence.</p>
  <div class="actions"><a class="button primary" href="https://github.com/joemooney/aida" target="_blank" rel="noopener">Explore the repository <span aria-hidden="true">↗</span></a><a class="button secondary" href="getting-started.html">Getting started</a></div>
- <p><a class="text-link" href="configuration.html">Configure your operating model ↗</a></p>
+ <p><a class="text-link" href="configuration.html">Configure your operating model ↗</a> · <a class="text-link" href="workflow.html">Follow the workflow ↗</a></p>
  <div class="readiness"><span class="signal"></span><p><strong>Available today: alpha, Linux only.</strong> AIDA operates under a shared Unix user; multi-human identity separation is not a security boundary. Production deployment needs its own policy and automation.</p></div>
 </section>
 </main>