docs(agent): agent-workflows ground truth + comment hygiene#4770
docs(agent): agent-workflows ground truth + comment hygiene#4770mmabrouk wants to merge 1 commit into
Conversation
Make the agent-workflows design folder readable before reviewers look at behavior, and strip stale work-package labels from live comments. - Add current-state pages: ground-truth, meeting-alignment, implementation-review, pr-stack, agent-template, protocol, triggers, status. - Move historical scratch/ POC material under trash/ (kept for provenance). - Remove WP-2/WP-6/WP-8 and "legacy"/old-name references from code comments in app.py, schemas.py, harnesses.py, docker-compose.dev.yml, and the runner README. No behavior change.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
dosubot
Bot
added
documentation
Reviewer guide: where to lookThis is a docs and comment-hygiene PR with no behavior change. To review it fast:
|
| environment: | ||
| DOCKER_NETWORK_MODE: ${DOCKER_NETWORK_MODE:-bridge} | ||
| # Agent workflow (WP-2): reach the harness wrapper sidecar in-network. | ||
| # Agent workflow: reach the agent runner sidecar in-network. |
There was a problem hiding this comment.
Comment-only: the stale WP-2 label is dropped for plain wording. The env key (AGENTA_AGENT_PI_URL) and its value are unchanged below.
| # -full base) so Daytona runs skip the ~150s per-invoke `npm install pi`. We | ||
| # ship the builder (poc/build_rivet_snapshot.py), not the snapshot itself: each | ||
| # operator builds their own, so we never distribute a Claude-containing image. | ||
| # See services/agent/docker/README.md for the licensing posture. |
There was a problem hiding this comment.
Comment-only: this adds the licensing rationale for the Daytona snapshot (ship the builder, not a Claude-containing image). No compose key or value changes here.
| app = ag.create_app() | ||
| # No builtin URI yet: registering the agent as a first-class workflow type | ||
| # (`agenta:builtin:agent:v0`) and its interface is WP-6. Here we register the handler | ||
| # (`agenta:builtin:agent:v0`) is still future work. Here we register the handler |
There was a problem hiding this comment.
Comment-only: the WP-6 label is replaced with 'still future work'. The registration call below is unchanged.
|
Superseded. Replacing the path-based stack with PRs sliced by functional area showing final code only, so reviewers don't comment on intermediate scaffolding that a later PR rewrites. See the new set. |
Railway Preview Environment
|
1 participant
This PR is part of a stack. Review bottom-up.
Each PR's diff is only its own delta. Merge from the bottom. This PR's base is #4769 (merge that first).
Context
The agent-workflows design folder grew during an exploratory build. It mixed current facts, dead RFCs, and per-work-package scratch notes, so a reviewer could not tell what the code does today from what we once planned. This PR reorganizes that folder so the design is readable before anyone reads behavior. It also strips stale internal labels from a handful of live code comments. Read this PR first.
The base is
feat/vercel-messages-protocol-version, so this diff shows only its own delta. This is slice #1 of the stack defined inpr-stack.md(documentation and comment hygiene).What this changes
Three groups, no behavior change.
(a) New current-state design pages.
ground-truth.mdmaps every live code surface and lists what is implemented, not implemented, and planned.meeting-alignment.md,implementation-review.md,agent-template.md,protocol.md,triggers.md, andstatus.mdcover alignment, a review of the current build, the planned template object, the wire protocol, trigger plans, and overall status.pr-stack.mdproposes the reviewable slicing this PR begins.(b) Historical material moved under
trash/. Old scratch notes and work-package POCs (WP-1 through WP-8, harness-port-redesign, old RFCs, research spikes) move there unchanged. They stay for provenance and explain why decisions were made. They are not current state.(c) Stale labels removed from live code comments. Five files drop WP-2, WP-6, and WP-8 markers and old harness or file names that no longer match the code. The edits touch comments, docstrings, and YAML comments only. No logic, no env values, no control flow changes.
What to verify
Two checks decide this PR.
First, confirm the five code files change comments only.
services/oss/src/agent/app.py,services/oss/src/agent/schemas.py,sdks/python/agenta/sdk/agents/adapters/harnesses.py, andservices/agent/README.mdreword comments or prose.hosting/docker-compose/ee/docker-compose.dev.ymlrewords comments and leaves every key and value untouched. No runtime behavior moves.Second, confirm
ground-truth.mdis now the single source of truth. It states that when another design page disagrees with it, that page and the referenced code win. The other pages should defer to it rather than restate or contradict it.How to review this PR
Read
docs/design/agent-workflows/ground-truth.mdfirst. It is the map. Then skimpr-stack.mdfor the slicing rationale that the rest of the stack follows. Then spot-check that the five code files are comment-only; for examplegh pr diff 4770and confirm the changed lines in those files are comment lines. Treattrash/as intentional archival. Do not review it line by line.