docs(vision): frame autonomy as configurable per workflow by ralphbean · Pull Request #3378 · fullsend-ai/fullsend

ralphbean · 2026-07-07T15:52:51Z

Summary

Keeps "everything autonomous" as the lede
Adds per-workflow configurability: each ASDLC phase can be human-driven, agent-driven, or both
Frames adoption as incremental — teams shift one phase at a time as confidence grows

Incorporates feedback from Romain on the vision doc.

Test plan

Verify doc renders correctly on the website
Review wording with Romain

🤖 Generated with Claude Code

fullsend-ai-review · 2026-07-07T15:53:48Z

🤖 Finished Review · ✅ Success · Started 3:53 PM UTC · Completed 4:04 PM UTC
Commit: 8217b39 · View workflow run →

qodo-code-review · 2026-07-07T15:54:32Z

PR Summary by Qodo

Vision: describe per-workflow configurable autonomy with incremental adoption

📝 Documentation 🕐 10-20 Minutes

AI Description

• Reframe the vision lede to keep “everything autonomous” as the explicit end state.
• Define autonomy as configurable per workflow/phase (human-driven, agent-driven, or both).
• Position rollout as incremental adoption rather than a single “flip the switch” change.

Diagram

graph TD
  A["docs/vision.md"] --> B["Goal framing"] --> C["Guardrails"] --> D["Per-workflow config"] --> E["Autonomy modes"] --> F["Incremental adoption"]

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a phase × autonomy matrix (table)

➕ Makes “configurable per phase/workflow” concrete and scannable
➕ Reduces ambiguity about what exactly is configurable
➖ More verbose and may require ongoing maintenance as phases evolve
➖ Could prematurely imply an implementation spec rather than a vision

2. Introduce a short, explicit example snippet (YAML/pseudocode)

➕ Clarifies what “configured per workflow” means operationally
➕ Aligns expectations for future tooling/config surface
➖ Risks locking in an interface too early
➖ Adds implementation flavor to a vision doc

Recommendation: The PR’s prose-first approach is appropriate for a vision document and keeps the narrative flexible. If reviewers still find “per workflow” abstract, the best follow-up would be a small table (phase × autonomy mode) rather than a config snippet, to stay conceptual while improving clarity.

Files changed (1) +4 / -4

Documentation (1) +4 / -4

vision.mdReframe autonomy as a configurable, incremental path to full autonomy +4/-4

Reframe autonomy as a configurable, incremental path to full autonomy

• Updates the goal section to lead with “everything autonomous” while clarifying that the path is incremental. Renames “guarded paths” to “guardrails” and adds an explicit per-workflow/per-phase configurability model (human-driven, agent-driven, or both), plus a minor wording tweak in the bugfix workflow description.

docs/vision.md

github-actions · 2026-07-07T15:55:09Z

Site preview

Preview: https://416ddb0f-site.fullsend-ai.workers.dev

Commit: e44aaeb18fcceab9e519249c394ed00a3efd4477

qodo-code-review · 2026-07-07T15:56:05Z

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Human-factors doc now stale 🐞 Bug ⚙ Maintainability

Description

docs/problems/human-factors.md explicitly frames its analysis around the vision’s “two points of
human participation” model, but the updated vision now emphasizes per-workflow/per-phase
configurability and incremental adoption. Leaving human-factors.md unchanged makes the documentation
set internally inconsistent and can mislead readers about what the current vision actually claims.

Code

docs/vision.md[10]

+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.

Relevance

⭐⭐⭐ High
They routinely fix downstream doc drift after source changes; multiple accepted “stale docs”
corrections across docs.
PR-#1039
PR-#1053

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The human-factors doc directly cites the vision as defining a fixed two-point model, while the
updated vision introduces per-phase configurability, so the downstream analysis no longer matches
the source-of-truth document it references.

docs/problems/human-factors.md[88-96]
docs/vision.md[5-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/problems/human-factors.md` depends on the vision stating a fixed “two-point model” (strategic intent + guarded paths; everything else autonomous). The updated vision text introduces per-workflow configurability across SDLC phases, which changes that premise.

## Issue Context
You can fix this either by:
- updating `human-factors.md` to explicitly state it is analyzing the earlier/fixed two-point framing (historical model), or
- updating it to analyze the configurable-per-phase model (or contrast both models).

## Fix Focus Areas
- docs/vision.md[5-10]
- docs/problems/human-factors.md[88-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. ~~Guardrails term mismatch~~ ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The vision doc renames the human approval concept to "Guardrails" but elsewhere (including later in
the same file) the docs still use "guarded paths" for the CODEOWNERS-gated areas. This inconsistent
terminology makes it harder to follow cross-doc discussions of CODEOWNERS-gated approval and what
exactly is being protected.

Code

docs/vision.md[R7-8]

1. **Strategic intent** — defining what the system should do and become. Features, architecture, direction.
-2. **Guarded paths** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.
+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

Relevance

⭐⭐⭐ High
Repo enforces terminology consistency via doc-wide renames (e.g., implementation→code) and other
consistency fixes.
PR-#194
PR-#2334

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
Within docs/vision.md, the list item uses “Guardrails” while the later workflow paragraph still says
“approve guarded paths”. Additionally, other docs consistently use “guarded paths,” indicating the
repo-wide canonical term has not been updated.
docs/vision.md[7-10]
docs/vision.md[38-38]
docs/problems/autonomy-spectrum.md[36-40]
docs/ADRs/0002-initial-fullsend-design.md[49-54]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/vision.md` introduces the label “Guardrails” for CODEOWNERS-gated approval, but the rest of the doc set (and even later in `docs/vision.md`) continues using “guarded paths”. This creates terminology drift for the same concept.

## Issue Context
The repository has multiple docs that use “guarded paths” as the canonical term; either update the vision back to that term, or do a coordinated rename across docs (and update the remaining occurrence in `docs/vision.md`).

## Fix Focus Areas
- docs/vision.md[7-8]
- docs/vision.md[38-38]
- docs/problems/autonomy-spectrum.md[36-40]
- docs/ADRs/0002-initial-fullsend-design.md[49-54]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. Unclear autonomy model 🐞 Bug ≡ Correctness

Description

In docs/vision.md the intro states humans participate at "two points", but immediately after it says
each SDLC phase/transition can be configured per-workflow as human-driven, agent-driven, or both.
This makes the intended steady-state vs incremental-migration model ambiguous and can mislead
readers about what "everything autonomous" concretely means.

Code

docs/vision.md[R5-10]

+Everything autonomous is the goal. A GitHub organization's repos operate with agents handling the full software development lifecycle: issue triage, implementation, code review, testing, and merge-to-production. Humans participate at two points:

1. **Strategic intent** — defining what the system should do and become. Features, architecture, direction.
-2. **Guarded paths** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.
+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

-Everything else is autonomous.
+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.

Relevance

⭐⭐⭐ High
Team has revised “two-point model” framing before; PR #24 explicitly questions it, suggesting
they’ll clarify ambiguity.
PR-#24

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The vision doc asserts a fixed "two points" human participation model and then immediately
introduces per-phase configurability, which implies humans may participate in more than two places
depending on workflow configuration.

docs/vision.md[5-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/vision.md` currently mixes two different framings back-to-back: (1) humans participate at exactly two points, and (2) each SDLC phase/transition can be configured per workflow as human-driven/agent-driven/both. This reads as internally inconsistent and makes it unclear whether per-workflow configurability is only an adoption strategy or also part of the long-term model.

## Issue Context
Other docs reference the vision's “two-point model”, so ambiguity here propagates into the rest of the documentation set.

## Fix Focus Areas
- docs/vision.md[5-10]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-code-review · 2026-07-07T15:56:05Z

+Everything autonomous is the goal. A GitHub organization's repos operate with agents handling the full software development lifecycle: issue triage, implementation, code review, testing, and merge-to-production. Humans participate at two points:

 1. **Strategic intent** — defining what the system should do and become. Features, architecture, direction.
-2. **Guarded paths** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.
+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

-Everything else is autonomous.
+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.


1. Unclear autonomy model 🐞 Bug ≡ Correctness

In docs/vision.md the intro states humans participate at "two points", but immediately after it says each SDLC phase/transition can be configured per-workflow as human-driven, agent-driven, or both. This makes the intended steady-state vs incremental-migration model ambiguous and can mislead readers about what "everything autonomous" concretely means.

Agent Prompt

## Issue description `docs/vision.md` currently mixes two different framings back-to-back: (1) humans participate at exactly two points, and (2) each SDLC phase/transition can be configured per workflow as human-driven/agent-driven/both. This reads as internally inconsistent and makes it unclear whether per-workflow configurability is only an adoption strategy or also part of the long-term model. ## Issue Context Other docs reference the vision's “two-point model”, so ambiguity here propagates into the rest of the documentation set. ## Fix Focus Areas - docs/vision.md[5-10]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-code-review · 2026-07-07T15:56:06Z

+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

-Everything else is autonomous.
+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.


3. Human-factors doc now stale 🐞 Bug ⚙ Maintainability

docs/problems/human-factors.md explicitly frames its analysis around the vision’s “two points of human participation” model, but the updated vision now emphasizes per-workflow/per-phase configurability and incremental adoption. Leaving human-factors.md unchanged makes the documentation set internally inconsistent and can mislead readers about what the current vision actually claims.

Agent Prompt

## Issue description `docs/problems/human-factors.md` depends on the vision stating a fixed “two-point model” (strategic intent + guarded paths; everything else autonomous). The updated vision text introduces per-workflow configurability across SDLC phases, which changes that premise. ## Issue Context You can fix this either by: - updating `human-factors.md` to explicitly state it is analyzing the earlier/fixed two-point framing (historical model), or - updating it to analyze the configurable-per-phase model (or contrast both models). ## Fix Focus Areas - docs/vision.md[5-10] - docs/problems/human-factors.md[88-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

codecov · 2026-07-07T15:58:13Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

fullsend-ai-review · 2026-07-07T16:04:29Z

Review

Findings

Medium

[terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" creates cross-document terminology inconsistency. The term "guarded paths" appears in at least 15 other locations across documentation files (ADRs, problem docs, human-factors.md, security-threat-model.md, autonomy-spectrum.md, intent-representation.md, testing-agents.md) and web/public/index.html. These files reference "guarded paths" as the canonical term defined in vision.md. Additionally, "guardrails" is already used extensively throughout the codebase (~40+ occurrences) with a distinct meaning — system-level safety mechanisms (org-wide guardrails, sandbox guardrails, configuration guardrails). The rename conflates two previously distinct concepts; line 64 of vision.md itself already uses "guardrails" in the broader sense ("automated testing as primary guardrails").
Remediation: Either update all documentation files to use "Guardrails" consistently (and disambiguate from the existing broader "guardrails" concept), or keep "Guarded paths" in vision.md to preserve terminological clarity.
[unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." This is stated in present tense as existing capability. AGENTS.md documents the autonomy model as "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths" — not per-workflow. The autonomy-spectrum problem document describes the model as binary per-repo, and notes whether per-repo binary is "too coarse" as an open question. No ADRs describe per-workflow configuration. The present tense "can be configured" implies existing capability rather than aspirational direction.
Remediation: Either reword to future tense ("will be configurable") or qualify as aspirational ("The target model allows..."), or if per-workflow configuration exists, add references to supporting ADRs/architecture.

Low

[missing-authorization] docs/vision.md — Documentation change with no linked issue. The PR restructures the vision document to frame autonomy as configurable per-workflow rather than binary per-repo, changes terminology from "Guarded paths" to "Guardrails", and adds a paragraph about incremental adoption.
Remediation: Consider creating a tracking issue that describes the scope of the vision.md reframing.

Labels: PR modifies documentation in docs/ directory

Previous run

Review

Findings

Medium

[terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" alters an established term used across 8+ documentation files (ADRs, problem docs, human-factors.md, security-threat-model.md, AGENTS.md). "Guarded paths" specifically refers to CODEOWNERS-enforced code paths requiring human approval, while "Guardrails" is used elsewhere in the codebase to refer to broader system-level safety mechanisms (sandboxing, policies, org-wide constraints). The explanatory text after the bold term is preserved, but the label change creates cross-document inconsistency.
Remediation: Preserve "Guarded paths" in this context, or if the rename is intentional, plan a follow-up to update references across all documentation files.
[internal-consistency] docs/vision.md:38 — The bolded concept name on line 8 uses "Guardrails" but the description paragraph on line 38 still says "approve guarded paths", creating an internal inconsistency within the same document where two different terms are used for the same concept.
Remediation: Use consistent terminology throughout the document — either both locations should use "guarded paths" or both should use "guardrails".
[unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." No other documentation (architecture.md, ADRs, problems/) describes per-workflow configuration of SDLC phases. The existing architecture describes per-repo autonomy (AGENTS.md: "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths"). The present-tense "can be configured" implies existing capability rather than aspirational direction.
Remediation: Qualify the claim as aspirational ("will be configurable" or "the goal is for each phase..."), or add a brief note that this is the design direction rather than current state.

Low

[stylistic-consistency] docs/vision.md:38 — The phrase "everything else is autonomous" is changed to "the rest is autonomous", weakening rhetorical parallelism with the standalone sentence earlier in the document and breaking a cross-document reference in human-factors.md line 90 which quotes the original phrasing verbatim.
Remediation: Consider maintaining the established phrasing "everything else is autonomous".

- Keeps "everything autonomous" as the lede - Adds per-workflow configurability: each SDLC phase can be human-driven, agent-driven, or both - Frames adoption as incremental - Uses "guardrails" consistently (generalizes beyond review agent) - Incorporates Romain's feedback on line 38 wording Assisted-by: Claude claude-opus-4-6 <noreply@anthropic.com> Signed-off-by: Ralph Bean <rbean@redhat.com>

fullsend-ai-review · 2026-07-07T21:14:10Z

🤖 Finished Review · ✅ Success · Started 9:14 PM UTC · Completed 9:27 PM UTC
Commit: e44aaeb · View workflow run →

fullsend-ai-review

See the review comment for full details.

Roming22

lgtm

ralphbean requested a review from a team as a code owner July 7, 2026 15:52

github-actions Bot deployed to site-preview July 7, 2026 15:55 View deployment

qodo-code-review Bot reviewed Jul 7, 2026

View reviewed changes

Roming22 reviewed Jul 7, 2026

View reviewed changes

Comment thread docs/vision.md Outdated

Comment thread docs/vision.md

This comment was marked as outdated.

Sign in to view

ralphbean force-pushed the docs/vision-configurable-autonomy branch from 8217b39 to e44aaeb Compare July 7, 2026 21:13

github-actions Bot deployed to site-preview July 7, 2026 21:15 View deployment

fullsend-ai-review Bot suggested changes Jul 7, 2026

View reviewed changes

Comment thread docs/vision.md

Comment thread docs/vision.md

fullsend-ai-review Bot added the component/docs User-facing documentation label Jul 7, 2026

Roming22 approved these changes Jul 8, 2026

View reviewed changes

Uh oh!

Conversation

ralphbean commented Jul 7, 2026

Summary

Test plan

Uh oh!

fullsend-ai-review Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qodo-code-review Bot commented Jul 7, 2026

PR Summary by Qodo

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Site preview

Uh oh!

qodo-code-review Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

qodo-code-review Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

qodo-code-review Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 7, 2026

Codecov Report

Uh oh!

fullsend-ai-review Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review

Findings

Medium

Low

Review

Findings

Medium

Low

Uh oh!

This comment was marked as outdated.

Uh oh!

fullsend-ai-review Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fullsend-ai-review Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Roming22 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fullsend-ai-review Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

qodo-code-review Bot commented Jul 7, 2026 •

edited

Loading

fullsend-ai-review Bot commented Jul 7, 2026 •

edited

Loading

fullsend-ai-review Bot commented Jul 7, 2026 •

edited

Loading