fix: Clarify devforge gates, relay semantics, and agent write access#12
Open
jirispilka wants to merge 5 commits into
Open
fix: Clarify devforge gates, relay semantics, and agent write access#12jirispilka wants to merge 5 commits into
jirispilka wants to merge 5 commits into
Conversation
Four reviewer dispatches missed a committed .devforge reference and two pieces of verbatim-carried cruft on apify/apify-mcp-server#1073 — the design's 'byte-identical, only plumbing moves' framing rewarded fidelity over judgment. Two always-on checks in the reviewer format close that. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUZNJQKNCn7ntZCbYsFer5
…questions only Three interactive-widget stream failures in one session, one swallowing a create-PR confirmation. Hard rules prevented false approval; this prevents the wasted round-trips. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUZNJQKNCn7ntZCbYsFer5
…relay fallback Every explorer/architect dispatch ended with 'no Write tool — orchestrator please persist', an undocumented rule-bend. The agents get Write; engines that still can't write get an explicit verbatim-relay rule. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUZNJQKNCn7ntZCbYsFer5
…goal Verify caught that apify/apify-mcp-server#684's literal fix cannot ship (SDK schema validation) — the highest-value moment of the run, handled in an improvised stop the skill never named. Without it a future orchestrator may design around the constraint without asking, shipping a mechanism the issue author never chose. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUZNJQKNCn7ntZCbYsFer5
jirispilka
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refines the devforge skill documentation and agent configurations to clarify gate-handling patterns, artifact relay mechanics when agents lack write access, and explicit instructions for agents to write to
.devforge/paths when dispatched by the orchestrator.Key changes
Gate and interaction flow: Expanded the "gates are chat-first" principle to specify the channel order (plan-mode dialog for design gate when enabled, plain chat otherwise) and clarified that interactive question widgets are only for genuine multiple-choice design questions—never for gate approve/revise decisions. Added guidance to fall back to plain chat after a single widget stream failure.
Artifact relay semantics: Documented that when a dispatched agent has no write access, the orchestrator relays the artifact verbatim to the target path unchanged—a mechanical relay, not authorship—and that this does not violate the no-judgment-files rule. Added a note to record the relay in
_progress.md.Verify gate constraint handling: Clarified that when the requested mechanism is infeasible (e.g., API/SDK constraint) but the goal is valid, the verify agent must present the constraint and viable options with a recommendation, then wait for the human's decision rather than silently designing around it. The human's pick is recorded verbatim in
_design_feedback.mdfor the architect to treat as settled.Reviewer findings scope: Added two always-on checks, as a standalone paragraph ahead of the stage-dispatch table (not inside the
reviewerrow, to avoid colliding with feat: Oracle baselines + blindness refined to judgments-not-ground-truth #9's edits to that row): committed code must not reference run-internal artifacts (.devforge/, plan files, session paths), and cruft preserved by a faithful migration is still a finding—"byte-identical" instructions cover assertions/behavior, not carried-over dead code.Agent tool access: Added
Writetool to bothdevforge-code-exploreranddevforge-code-architectagents, and added explicit instructions for both to write their artifacts to the exact.devforge/path named in the prompt when dispatched by devforge.Origin
Retrospective of a two-run session on apify/apify-mcp-server (#1061 → PR apify/apify-mcp-server#1073, #684 → PR apify/apify-mcp-server#1080). Each change maps to an observed failure: reviewers missing a committed
.devforgereference and preserved cruft; three question-widget stream failures (one swallowed a create-PR confirmation); every explorer/architect dispatch ending in an undocumented relay; and the SDK-constraint discovery on #684 being handled in a stop the skill never named.Merge-order note
Independent of #9/#10/#11 (based on
main). Previously overlapped #9 on thereviewerstage-table row (this PR's format-column addition vs. #9's reads-column addition); resolved by moving this PR's addition into its own paragraph ahead of the table, so the two no longer touch the same line and merge order no longer matters.https://claude.ai/code/session_01LUZNJQKNCn7ntZCbYsFer5