From 1e6b2390b81317734a321fbb9b962b615c5194f1 Mon Sep 17 00:00:00 2001 From: Joe Mooney Date: Thu, 29 Oct 2026 11:42:59 -0700 Subject: [PATCH] [AI:codex] docs(workflow): explain the collaboration loop and durable records (TASK-B6B1278890774EF993D2EBC327862470-108) --- docs/product-workflow.md | 41 +++++++++++++++++++++++++++++ docs/showcase/assets/workflow.svg | 1 + docs/showcase/build.py | 3 ++- docs/showcase/configuration.html | 2 +- docs/showcase/getting-started.html | 2 +- docs/showcase/index.html | 4 +-- docs/showcase/workflow.html | 42 ++++++++++++++++++++++++++++++ 7 files changed, 90 insertions(+), 5 deletions(-) create mode 100644 docs/product-workflow.md create mode 100644 docs/showcase/assets/workflow.svg create mode 100644 docs/showcase/workflow.html diff --git a/docs/product-workflow.md b/docs/product-workflow.md new file mode 100644 index 00000000000..395b1a78d69 --- /dev/null +++ b/docs/product-workflow.md @@ -0,0 +1,41 @@ +# From a conversation to a maintainable system + + + +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 new file mode 100644 index 00000000000..f0ba4c05f85 --- /dev/null +++ b/docs/showcase/assets/workflow.svg @@ -0,0 +1 @@ +Human and agent collaboration and its recordsDiagram one: Discuss, capture, own work, implement, independently review, integrate and return to discussion. Diagram two: code history and canonical intent are connected by traces; the read cache derives from the store, while local operational evidence has separate scope and retention.01 / People and agents work together1. DiscussPeople shape the outcome2. CaptureAgents record agreed intent3. Own workRoles, leases and worktrees4. ImplementBuild and validate5. ReviewIndependent current evidence6. IntegrateAuthorized policy checksFeedback returns to the conversation02 / Records have different responsibilitiesCode historySource, tests and trace commentsCanonical intentSpecs, decisions and historyRead cacheRebuilt from available store dataLocal evidenceSessions, verdicts and authority contextExplanatory model · Not a live dashboard or backup guarantee \ No newline at end of file diff --git a/docs/showcase/build.py b/docs/showcase/build.py index 1f053420bbd..03082a102b0 100644 --- 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 index e1bcc6d83bd..df75a4d56b7 100644 --- a/docs/showcase/configuration.html +++ b/docs/showcase/configuration.html @@ -8,7 +8,7 @@ -
✳ AIDA
+
✳ AIDA

THE GOVERNED SOFTWARE FACTORY

Configuration diagram; details follow in the source guide

Configure the way your team works

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.

Six places to make a choice

diff --git a/docs/showcase/getting-started.html b/docs/showcase/getting-started.html index 02c5055eb92..5217570aef5 100644 --- a/docs/showcase/getting-started.html +++ b/docs/showcase/getting-started.html @@ -8,7 +8,7 @@ -
✳ AIDA
+
✳ AIDA

THE GOVERNED SOFTWARE FACTORY

Build as you already work

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.

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.

diff --git a/docs/showcase/index.html b/docs/showcase/index.html index 9ea92739518..ac7b5fd22dd 100644 --- a/docs/showcase/index.html +++ b/docs/showcase/index.html @@ -13,7 +13,7 @@
AIDATHE GOVERNED SOFTWARE FACTORY - + Explore AIDA
@@ -98,7 +98,7 @@

Built for the work
between the agents.

06 / START WITH ONE CHANGE

Give the next agent
more than a prompt.

Choose a bounded change. Write down what success means. Run it through AIDA and inspect the resulting evidence.

Explore the repository Getting started
-

Configure your operating model ↗

+

Configure your operating model ↗ · Follow the workflow ↗

Available today: alpha, Linux only. AIDA operates under a shared Unix user; multi-human identity separation is not a security boundary. Production deployment needs its own policy and automation.

diff --git a/docs/showcase/workflow.html b/docs/showcase/workflow.html new file mode 100644 index 00000000000..e9586626609 --- /dev/null +++ b/docs/showcase/workflow.html @@ -0,0 +1,42 @@ + + + + +Workflow — AIDA + + + + + +
✳ AIDA
+

THE GOVERNED SOFTWARE FACTORY

Workflow diagram; details follow in the source guide

From a conversation to a maintainable system

+

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 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 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 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 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, storage abstraction, session lifecycle and product architecture for the source behind these distinctions.

+ + +