Skip to content

docs(vision): frame autonomy as configurable per workflow #3378

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ralphbean wants to merge 1 commit into
base: main
Choose a base branch
from
+4 −4
Open

docs(vision): frame autonomy as configurable per workflow #3378

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/vision.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## The goal

A GitHub organization's repos operate with fully autonomous agents handling the routine software development lifecycle: issue triage, implementation, code review, testing, and merge-to-production. Humans participate at two points:
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.
Comment thread
qodo-code-review[bot] marked this conversation as resolved.

@fullsend-ai-review fullsend-ai-review Bot Jul 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] terminology-consistency

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.

Suggested fix: Preserve "Guarded paths" in this context, or if the rename is intentional, plan a follow-up to update references across all documentation files.

Comment thread
ralphbean marked this conversation as resolved.

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.
Comment on lines +5 to +10

@qodo-code-review qodo-code-review Bot Jul 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

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 qodo-code-review Bot Jul 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

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

Comment thread
ralphbean marked this conversation as resolved.

@fullsend-ai-review fullsend-ai-review Bot Jul 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[medium] unsubstantiated-architecture-claim

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.

Suggested fix: 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.

Comment thread
ralphbean marked this conversation as resolved.

## The agentic SDLC

Expand Down Expand Up @@ -35,7 +35,7 @@ The current bugfix workflow spans three phases. The remaining phases are planned
***Feedback*** ◄─── Monitor ◄─────── Delivery
```

**Current (bugfix workflow):** An issue reports a bug (***feedback***). An agent triages, implements a fix (***execution***), and validates it against tests and review (***verification***). Humans set strategic intent and approve guarded paths; everything else is autonomous.
**Current (bugfix workflow):** An issue reports a bug (***feedback***). An agent triages, implements a fix (***execution***), and validates it against tests and review (***verification***). Humans must set strategic intent and approve guardrails; the rest may be fully autonomous based on configuration.

**Planned:** Discovery (identifying what needs work from production signals and tech debt), refinement (scoping and decomposing work), prioritization (ordering the backlog), delivery (merge-to-production with graduated autonomy), and monitor (production observability feeding back into the loop).

Expand Down
Loading