Refine system prompts — personality, communication protocols, compression#37
Refine system prompts — personality, communication protocols, compression#37AnExiledDev wants to merge 3 commits intomainfrom
Conversation
…press main prompt Main system prompt redesigned from 672 to 462 lines: added personality section with communication style and AuDHD-aware patterns, compressed specification management and code standards, removed browser automation and git worktrees (moved to loadable skills), added mandatory context-passing protocol for subagent spawning, absorbed assumption_surfacing and professional_objectivity into core sections. All 21 agent prompts now have communication protocols — read-only agents get "Handling Uncertainty" (flag assumptions, continue working), write-capable agents get "Question Surfacing Protocol" (BLOCKED + return for ambiguity). Architect agent gains anti-fluff enforcement and team orchestration planning. Generalist rewritten as explicit last-resort fallback. Bash guard hooks added to researcher, debug-logs, and perf-profiler agents.
📝 WalkthroughWalkthroughThis PR replaces Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User
participant Subagent
participant Orchestrator
participant Tools
User->>Subagent: Submit task/request
Subagent->>Subagent: Analyze request & detect ambiguity
alt Ambiguity affecting correctness
Subagent->>Subagent: Emit "BLOCKED: Questions" / Assumptions
Subagent->>Orchestrator: Return partial results + BLOCKED payload
Orchestrator->>User: Relay BLOCKED questions/options
User->>Orchestrator: Provide answers/clarifications
Orchestrator->>Subagent: Deliver clarifications
Subagent->>Tools: Continue/complete work per clarifications
else No critical ambiguity
Subagent->>Tools: Proceed using documented assumptions
Tools-->>Subagent: Results
Subagent-->>Orchestrator: Final output (with Assumptions)
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~50 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 10
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.devcontainer/CHANGELOG.md (1)
168-176:⚠️ Potential issue | 🟡 MinorConsolidate duplicate
### Changedsections under## [Unreleased].There’s already a
### Changedblock at Line 5; introducing another at Line 168 fragments the same category. Merge these into a single### Changedheading and keep the existing####area sub-headings underneath it.As per coding guidelines: "Group changelog entries under appropriate headings:
### Added,### Changed,### Fixed, or### Removed."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/CHANGELOG.md around lines 168 - 176, Merge the duplicate "### Changed" section into the existing "## [Unreleased]" block by removing the extra "### Changed" header at the new location and moving its four "#### Skill Engine: Auto-Suggestion" sub-heading and bullet list under the original "### Changed" area; ensure only one "### Changed" heading exists under "## [Unreleased]" and retain the sub-heading "#### Skill Engine: Auto-Suggestion" with its bullets unchanged.
🧹 Nitpick comments (3)
.devcontainer/CHANGELOG.md (1)
8-19: Rephrase bullets to user-facing outcomes instead of implementation internals.Several bullets describe how the prompt files were reorganized (e.g., exact line-count deltas, internal tag absorption/deduplication). Prefer wording focused on what users now experience (clearer behavior, more consistent agent responses, safer execution defaults).
As per coding guidelines: "Write CHANGELOG entries from the user's perspective — what changed, not how it was implemented."
Also applies to: 21-28
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/CHANGELOG.md around lines 8 - 19, Rewrite each bullet so it describes the user-facing effect rather than internal implementation details: for entries like "Main system prompt redesigned", "Added personality section", "Compressed specification management", "Compressed code standards", "Removed browser automation section", "Removed git worktrees section", "Added context-passing protocol", "Absorbed <assumption_surfacing>", "Absorbed <professional_objectivity>", "Deduplicated team composition examples", and "Consolidated 'no filler' instructions", change phrasing to outcomes users will notice (e.g., clearer and more consistent agent behavior, faster responses, safer defaults, easier extension via loadable skills) and remove line-counts, tag-absorption notes, and internal reorganizing language; apply the same user-facing rewrite to the related bullets in lines 21-28..devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/migrator.md (1)
123-132: Well-structured protocol addition that aligns with PR objectives.The "Question Surfacing Protocol" clearly defines how this write-capable agent should handle ambiguity — the STOP-and-BLOCK pattern is explicit and actionable. The 4-step process (STOP → include BLOCKED section → describe questions → return partial results) provides concrete guidance.
Optional enhancement: The three examples at the end (lines 285-321) demonstrate successful migration flows. Consider adding a fourth example showing the BLOCKED pattern in action — for instance, when the agent encounters unclear migration requirements or conflicting dependency constraints. This would reinforce the protocol with a concrete demonstration.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/migrator.md around lines 123 - 132, Add a fourth example to the examples section (after the existing three examples) that demonstrates the "Question Surfacing Protocol" BLOCKED pattern in practice: show an agent encountering ambiguous migration requirements or conflicting dependency constraints, the agent STOPs work on that area, includes a "## BLOCKED: Questions" section with each question stating what is needed, why it matters, and possible options, and returns its partial results; reference the protocol title "Question Surfacing Protocol" and the marker "## BLOCKED: Questions" so readers can cross-check the behavior..devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md (1)
57-67: Clarify the "BLOCKED: Questions" section placement and structure.The new Question Surfacing Protocol introduces a
## BLOCKED: Questionssection (line 63) for scope-level ambiguity, but this section doesn't appear in the Output Format template (lines 249-307). This creates ambiguity about where and how to include BLOCKED questions in the final spec structure.Additionally, "return partial results" could be more concrete—does this mean draft only the unambiguous requirements, or provide a stub structure with placeholders?
📋 Suggestions to improve clarity
Option 1: Add BLOCKED to the Output Format template
Insert after the Open Questions section (around line 303):
## BLOCKED: Questions [For scope-level ambiguity only. These questions prevent starting work until resolved.] 1. [Scope question] — [why it blocks progress] - Context: [what you know] - Needed: [what decision would unblock you]Option 2: Clarify "partial results" in the protocol
-2. For scope-level ambiguity (e.g., "which feature should I spec?"), include a `## BLOCKED: Questions` section and return partial results +2. For scope-level ambiguity (e.g., "which feature should I spec?"), include a `## BLOCKED: Questions` section and return a draft limited to what you can determine from context (e.g., discovered code structure, existing tests) without guessing scopeMinor: Grammar suggestion from static analysis
Line 67 could use a hyphen in the compound adjective:
-Your Open Questions section IS your question surfacing mechanism. +Your Open Questions section IS your question-surfacing mechanism.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md around lines 57 - 67, The docs introduce a "## BLOCKED: Questions" section in the Question Surfacing Protocol but the Output Format template lacks this section and the phrase "return partial results" is vague; update the Output Format template to include a clearly defined "## BLOCKED: Questions" block (placed immediately after "## Open Questions") with the suggested structure (question, why it blocks, context, needed decision) and expand the protocol text for "return partial results" to specify that agents should either (A) draft all unambiguous requirements and mark ambiguous sections as placeholders, or (B) provide a stub structure with placeholders and explanations—refer to the "## BLOCKED: Questions" header and "Open Questions" section when making these edits and fix the minor hyphenation in the compound adjective on line 67.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.codeforge/config/main-system-prompt.md:
- Around line 196-223: The Subagents section contradicts later write-agent
rules; update the orchestration to define explicit subagent modes (read-only vs
write-capable) under "Subagents (via `Task` tool)", state which core types can
operate in which mode (e.g., `explorer` read-only, `generalist` and `bash-exec`
may be write-capable when explicitly authorized), and add a clear rule that
spawning a write-capable agent requires explicit authorization/plan and follows
the "Context-passing protocol" (which should be annotated to apply only to
write-capable agents); ensure the "Task decomposition" and "Context-passing
protocol" sections reference these modes and include acceptance
criteria/authorization checks for write agents so delegation semantics are
consistent.
- Around line 374-380: The fenced code block showing the directory tree
(starting with ".specs/") is missing a language identifier which violates
markdownlint MD040; update the opening fence from ``` to ```text (or another
appropriate language) so the block becomes ```text and the rest of the content
remains unchanged, ensuring the snippet is properly recognized as text in the
file .codeforge/config/main-system-prompt.md.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md:
- Around line 113-121: The document contains a contradiction between the "Banned
patterns" list (the lines banning phrases like "This approach follows best
practices..." and "Any sentence explaining why the chosen approach is good") and
the later workflow requirement to provide an alternatives analysis with
reasoning; resolve this by updating agents/architect.md to permit short,
codebase-specific rationale only within the alternatives analysis step (or
explicitly carve out an "Allowed concise rationale" exception), and change the
"Banned patterns" text to forbid generic/boilerplate justifications while
referencing the alternatives analysis section by name so implementers know where
concise, contextual reasoning is required.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/explorer.md:
- Around line 51-60: The document currently conflicts between the "Handling
Uncertainty" rule (which forbids asking the user questions and requires
non-blocking progress with an ## Assumptions section) and a later instruction
that tells the agent to "ask caller to clarify"; update the ambiguous-request
behavior so it matches the Handling Uncertainty protocol: remove or replace the
"ask caller to clarify" instruction in the explorer.md ambiguous-request section
with explicit steps to (1) list an ## Assumptions section explaining each
assumption and its alternative interpretation, (2) proceed with work based on
the assumptions and flag uncertainty, and (3) present organized search results
or options for narrowing scope rather than posing direct questions to the
caller.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md:
- Around line 119-142: Decide and enforce a single ambiguity-handling policy:
either (A) always stop and return a ## BLOCKED: Questions section per the
"Question Surfacing Protocol" or (B) allow subagents to proceed with the most
likely interpretation per the "Behavioral Rules"; then update the text so both
places are consistent — modify the "When You Hit an Ambiguity" block to
explicitly state it is the authoritative policy (if choosing A) or change the
"Behavioral Rules" sentence that permits proceeding on ambiguity to reference
and defer to the Question Surfacing Protocol (if choosing B); ensure the
instructions mention the required ## BLOCKED format and what to include, and
remove the contradictory sentence so only one clear directive remains.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/git-archaeologist.md:
- Around line 51-59: The "Handling Uncertainty" section contradicts "Step 1" by
forbidding subagents from asking the user questions while Step 1 still instructs
asking clarifying questions; update the document so one rule overrides the other
by either (A) editing the "Handling Uncertainty" text to explicitly state it
supersedes Step 1 (e.g., "This override: subagents must not ask users questions;
instead follow the Assumptions protocol"), or (B) modifying Step 1 to
remove/replace any instruction to ask the user with guidance to create an "##
Assumptions" section and proceed; ensure references to both "Handling
Uncertainty" and "Step 1" are adjusted so there is a single, unambiguous path
for subagents.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md:
- Around line 64-73: Update the contradictory guidance so the researcher remains
non-interactive: replace the sentence that currently reads "state your
interpretation before proceeding so the user can correct course early" with
wording that instructs the subagent to record its interpretation in the output
(e.g., in the "## Assumptions" or findings section) for downstream review rather
than directly asking the user; reference the "Handling Uncertainty" header and
the existing "## Assumptions" requirement so the change explicitly ties the
interpretation to the report/log and clarifies it is non-blocking and not a
direct user prompt.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/statusline-config.md:
- Around line 23-32: The document contains conflicting guidance: the subagent
protocol forbids asking the user directly but later sections still instruct
agents to ask questions (notably the instructions that were at lines referenced
in the review). Update those sections to follow the Question Surfacing Protocol
by removing any direct “ask the user” steps and instead instructing the subagent
to STOP the ambiguous flow, include a `## BLOCKED: Questions` section in its
output, list each question with what’s needed/why/options, and return partial
results; update any templates or examples (the blocks originally at the later
“ask the user” spots) to show the `## BLOCKED: Questions` format so all
references (e.g., the later question templates) consistently route questions
through the orchestrator rather than prompting the user directly.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md:
- Around line 127-140: The file contains conflicting instructions: the "Question
Surfacing Protocol" forbids directly asking the user (the subagent must create a
"## BLOCKED: Questions" section), but later text instructs the agent to "ask
which module" / "ask the user how to proceed"; update the later instructions to
follow the Question Surfacing Protocol by replacing any phrases like "ask which
module" or "ask the user how to proceed" with explicit guidance to stop, include
a "## BLOCKED: Questions" section listing the precise clarifying items, and
return partial results; ensure the conflict is resolved by making the "Question
Surfacing Protocol" the single source of truth (e.g., adjust the later
instructions in the same doc to reference the protocol and to use "## BLOCKED:
Questions" and "## Bugs Discovered" rather than prompting the user).
---
Outside diff comments:
In @.devcontainer/CHANGELOG.md:
- Around line 168-176: Merge the duplicate "### Changed" section into the
existing "## [Unreleased]" block by removing the extra "### Changed" header at
the new location and moving its four "#### Skill Engine: Auto-Suggestion"
sub-heading and bullet list under the original "### Changed" area; ensure only
one "### Changed" heading exists under "## [Unreleased]" and retain the
sub-heading "#### Skill Engine: Auto-Suggestion" with its bullets unchanged.
---
Nitpick comments:
In @.devcontainer/CHANGELOG.md:
- Around line 8-19: Rewrite each bullet so it describes the user-facing effect
rather than internal implementation details: for entries like "Main system
prompt redesigned", "Added personality section", "Compressed specification
management", "Compressed code standards", "Removed browser automation section",
"Removed git worktrees section", "Added context-passing protocol", "Absorbed
<assumption_surfacing>", "Absorbed <professional_objectivity>", "Deduplicated
team composition examples", and "Consolidated 'no filler' instructions", change
phrasing to outcomes users will notice (e.g., clearer and more consistent agent
behavior, faster responses, safer defaults, easier extension via loadable
skills) and remove line-counts, tag-absorption notes, and internal reorganizing
language; apply the same user-facing rewrite to the related bullets in lines
21-28.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/migrator.md:
- Around line 123-132: Add a fourth example to the examples section (after the
existing three examples) that demonstrates the "Question Surfacing Protocol"
BLOCKED pattern in practice: show an agent encountering ambiguous migration
requirements or conflicting dependency constraints, the agent STOPs work on that
area, includes a "## BLOCKED: Questions" section with each question stating what
is needed, why it matters, and possible options, and returns its partial
results; reference the protocol title "Question Surfacing Protocol" and the
marker "## BLOCKED: Questions" so readers can cross-check the behavior.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md:
- Around line 57-67: The docs introduce a "## BLOCKED: Questions" section in the
Question Surfacing Protocol but the Output Format template lacks this section
and the phrase "return partial results" is vague; update the Output Format
template to include a clearly defined "## BLOCKED: Questions" block (placed
immediately after "## Open Questions") with the suggested structure (question,
why it blocks, context, needed decision) and expand the protocol text for
"return partial results" to specify that agents should either (A) draft all
unambiguous requirements and mark ambiguous sections as placeholders, or (B)
provide a stub structure with placeholders and explanations—refer to the "##
BLOCKED: Questions" header and "Open Questions" section when making these edits
and fix the minor hyphenation in the compound adjective on line 67.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (20)
.codeforge/config/main-system-prompt.md.devcontainer/CHANGELOG.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/bash-exec.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/claude-guide.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/debug-logs.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/dependency-analyst.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/doc-writer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/explorer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/git-archaeologist.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/investigator.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/migrator.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/perf-profiler.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/refactorer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/statusline-config.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md
| Subagents (via `Task` tool): | ||
| - Information gathering only | ||
| - Report findings; never decide or modify | ||
| - Core types (auto-redirected to enhanced custom agents): | ||
| - `Explore` → `explorer` (fast codebase search, haiku, read-only) | ||
| - `Plan` → `architect` (implementation planning, opus, read-only) | ||
| - `general-purpose` → `generalist` (multi-step tasks, inherit model) | ||
| - `Bash` → `bash-exec` (command execution, sonnet) | ||
| - `claude-code-guide` → `claude-guide` (Claude Code/SDK/API help, haiku) | ||
| - `statusline-setup` → `statusline-config` (status line setup, sonnet) | ||
|
|
||
| Creating worktrees (manual): | ||
| ```bash | ||
| # Legacy convention — detected by setup-projects.sh | ||
| mkdir -p /workspaces/projects/.worktrees | ||
| git worktree add /workspaces/projects/.worktrees/<branch-name> -b <branch> | ||
| ``` | ||
| Main thread acts only after sufficient context is assembled. | ||
|
|
||
| Note: The `magic-docs` built-in agent is NOT redirected — it runs natively for MAGIC DOC file updates. | ||
|
|
||
| Environment files: | ||
| - Place a `.worktreeinclude` file at the project root listing `.gitignore`-excluded files to copy into new worktrees (e.g., `.env`, `.env.local`) | ||
| - Uses `.gitignore` pattern syntax; only files matching both `.worktreeinclude` and `.gitignore` are copied | ||
| Task decomposition (MANDATORY): | ||
| - Break every non-trivial task into discrete, independently-verifiable subtasks BEFORE starting work. | ||
| - Each subtask should do ONE thing. Granularity enables parallelism and failure isolation. | ||
| - Spawn Task agents for each subtask. Prefer parallel execution when subtasks are independent. | ||
| - After each subtask completes, verify its output before proceeding. | ||
|
|
||
| Context-passing protocol (MANDATORY when spawning agents): | ||
| - Include relevant context already gathered — file paths, findings, constraints, partial results. | ||
| - Don't just say "investigate X" — say "investigate X, here's what I know: [context]." | ||
| - For write agents: include the plan, acceptance criteria, scope boundaries, and files to modify. | ||
| - For research agents: include what you've already searched and what gaps remain. | ||
| - Subagents have NO access to the conversation history. Everything they need must be in the task prompt. | ||
|
|
There was a problem hiding this comment.
Fix subagent capability contradiction in orchestration rules.
This block says subagents are “information gathering only” and “never decide or modify,” but the same prompt defines write agents and write-agent context passing (e.g., Line 220, Line 263-268). This conflict breaks delegation semantics and should be reconciled explicitly (read-only vs write-capable subagent modes).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.codeforge/config/main-system-prompt.md around lines 196 - 223, The
Subagents section contradicts later write-agent rules; update the orchestration
to define explicit subagent modes (read-only vs write-capable) under "Subagents
(via `Task` tool)", state which core types can operate in which mode (e.g.,
`explorer` read-only, `generalist` and `bash-exec` may be write-capable when
explicitly authorized), and add a clear rule that spawning a write-capable agent
requires explicit authorization/plan and follows the "Context-passing protocol"
(which should be annotated to apply only to write-capable agents); ensure the
"Task decomposition" and "Context-passing protocol" sections reference these
modes and include acceptance criteria/authorization checks for write agents so
delegation semantics are consistent.
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md
Outdated
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/explorer.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/git-archaeologist.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/refactorer.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/statusline-config.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md
Show resolved
Hide resolved
Address all 10 CodeRabbit review items plus 3 nitpicks: - Fix communication protocol contradictions across 8 agent files (aligned "ask the user" instructions with Handling Uncertainty / Question Surfacing Protocol sections) - Add `text` language identifier to fenced code block in main prompt - Soften architect anti-fluff rule to allow evidence-based rationale in alternatives analysis (was: ban ALL justification) - Merge duplicate ### Changed sections in CHANGELOG under [Unreleased] - Clarify spec-writer BLOCKED section and fix hyphenation Additional changes from approved plan (sessions 2-3): - Main prompt: add delegation-only orchestrator, git workflow discipline, dynamic team sizing, remove artificial teammate caps - Architect: complexity scaling, 20+ banned fluff patterns, edit ordering, rollback strategy, schema detection, 3 new examples - Merge tester→test-writer (absorb 120s timeout, delete tester.md) - Merge doc-writer→documenter (absorb README/API/docstring patterns, add worktree isolation, delete doc-writer.md) - Narrow investigator to cross-domain investigations only - Improve descriptions on 8 agents for routing accuracy - Fix stale doc-writer/tester references across 6 files
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md (1)
119-142:⚠️ Potential issue | 🟡 MinorClarify the relationship between the Question Surfacing Protocol and minor ambiguities.
Lines 125-130 state you MUST stop for situations like "Technology or approach choice not specified," but Line 262 allows proceeding with "minor ambiguities that do not affect correctness." A technology choice could be either category depending on context. Consider either:
- Adding a qualifier to the protocol: "MUST stop if the ambiguity affects correctness or requires user trade-off decisions"
- Removing the "minor ambiguities" exception from Line 262 to enforce strict blocking
The current wording creates uncertainty about when to stop versus when to proceed.
📝 Proposed clarification
Option 1: Update the protocol to acknowledge severity:
### When You Hit an Ambiguity -If you encounter ANY of these situations, you MUST stop and return: +If you encounter ANY of these situations that affect correctness or require user input, you MUST stop and return: - Multiple valid interpretations of the task - Technology or approach choice not specified - Scope boundaries unclear (what's in vs. out) - Missing information needed to proceed correctly - A decision with trade-offs that only the user can resolve + +For minor ambiguities that do not affect correctness (e.g., choosing between two equivalent approaches with no trade-offs), you may proceed by stating your interpretation and documenting your assumption.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md around lines 119 - 142, Update the "Question Surfacing Protocol" wording to remove the conflict with the "minor ambiguities" exception by making the stop condition conditional: change the MUST-stop list (in the Question Surfacing Protocol section) to read "MUST stop if the ambiguity affects correctness or requires user trade-off decisions (e.g., technology or approach choice that impacts outcomes)" and then edit the later clause that permits proceeding on "minor ambiguities" (around the later paragraph) to explicitly restrict it to non-blocking, cosmetic, or stylistic issues that do not affect correctness or require user choices; reference and update the "Question Surfacing Protocol" heading and the later "minor ambiguities" sentence in generalist.md to ensure they are consistent.
🧹 Nitpick comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md (1)
198-205: Consider making complexity thresholds explicitly heuristic.The file-count thresholds are useful, but presented as hard gates they can misclassify tasks (e.g., a risky 3-file API change). Suggest framing these as defaults with “override based on risk/coupling.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md around lines 198 - 205, Update the "Complexity assessment" section to treat the file-count thresholds as default heuristics rather than hard gates: modify the paragraph/table header under "Complexity assessment" and the Level descriptions (Simple, Moderate, Complex) to add a short caveat like "defaults — override based on risk, coupling, or scope" and a brief sentence explaining when to escalate (e.g., risky API changes, tight coupling, or high-impact edits may bump a task to a higher complexity level); ensure references to the table and any examples mention evaluating risk/coupling in functions that generate plans so consumers of this doc (the "Complexity assessment" text and the table entries) reflect the heuristic override.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md:
- Line 34: The opening paragraph of the "architect" agent repeats the same
sentence-start pattern and reads mechanically; rewrite that paragraph to vary
sentence openings and tighten phrasing for readability while preserving meaning
(you are a senior software architect specializing in implementation planning,
trade-off analysis, and technical decision-making). Locate the paragraph text in
agents/architect.md (the block beginning "You are a **senior software
architect**...") and rephrase to combine related clauses, remove redundant
starters, and use a more natural flow so an implementer can follow the intent
without changing the technical content.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/dependency-analyst.md:
- Around line 9-15: Summary: The agent description omits Ruby even though the
implementation supports Gemfile/Gemfile.lock; update the human-readable
ecosystem list to include Ruby/Gems. Edit the dependency-analyst agent
description string that lists "Node.js, Python, Rust, or Go ecosystems" and
append "Ruby (Gems)" or similar phrasing so it matches the implementation
references to **/Gemfile and **/Gemfile.lock; ensure the sentence about
supported ecosystems and the guidance about focusing on packages/versions
includes Ruby/Gems.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md:
- Around line 111-124: The fenced code block in documenter.md is missing a
language identifier (markdownlint MD040); update the triple-backtick block that
contains the Glob and Grep patterns (the block starting with "# Find existing
documentation") to include a language tag such as shell or bash (e.g., change
``` to ```shell) so the code block is properly highlighted and lint-compliant.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md:
- Around line 11-12: The doc has a scope contradiction: the header excludes
dependency/package vulnerability scanning by delegating to dependency-analyst,
yet later the agent includes "A06 dependency tooling" and a "dependency-audit"
behavior path; resolve by either removing the A06/dependency-audit references
from security-auditor.md or by explicitly expanding the scope to include
dependency scanning and noting overlap with dependency-analyst. Update the "A06
dependency tooling" and "dependency-audit" sections (or the header sentence that
references dependency-analyst) so they consistently reflect the chosen scope and
routing behavior.
---
Duplicate comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md:
- Around line 119-142: Update the "Question Surfacing Protocol" wording to
remove the conflict with the "minor ambiguities" exception by making the stop
condition conditional: change the MUST-stop list (in the Question Surfacing
Protocol section) to read "MUST stop if the ambiguity affects correctness or
requires user trade-off decisions (e.g., technology or approach choice that
impacts outcomes)" and then edit the later clause that permits proceeding on
"minor ambiguities" (around the later paragraph) to explicitly restrict it to
non-blocking, cosmetic, or stylistic issues that do not affect correctness or
require user choices; reference and update the "Question Surfacing Protocol"
heading and the later "minor ambiguities" sentence in generalist.md to ensure
they are consistent.
---
Nitpick comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md:
- Around line 198-205: Update the "Complexity assessment" section to treat the
file-count thresholds as default heuristics rather than hard gates: modify the
paragraph/table header under "Complexity assessment" and the Level descriptions
(Simple, Moderate, Complex) to add a short caveat like "defaults — override
based on risk, coupling, or scope" and a brief sentence explaining when to
escalate (e.g., risky API changes, tight coupling, or high-impact edits may bump
a task to a higher complexity level); ensure references to the table and any
examples mention evaluating risk/coupling in functions that generate plans so
consumers of this doc (the "Complexity assessment" text and the table entries)
reflect the heuristic override.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (25)
.codeforge/config/main-system-prompt.md.devcontainer/CHANGELOG.md.devcontainer/README.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/README.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/debug-logs.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/dependency-analyst.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/doc-writer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/explorer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/git-archaeologist.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/investigator.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/perf-profiler.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/refactorer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/statusline-config.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/tester.md.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/team/SKILL.md.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/SKILL.md.devcontainer/plugins/devs-marketplace/plugins/skill-engine/skills/worktree/references/parallel-workflow-patterns.md.devcontainer/plugins/devs-marketplace/plugins/spec-workflow/skills/spec-build/SKILL.md
💤 Files with no reviewable changes (2)
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/doc-writer.md
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/tester.md
🚧 Files skipped from review as they are similar to previous changes (5)
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/spec-writer.md
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/explorer.md
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/researcher.md
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/test-writer.md
- .devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/refactorer.md
| # Architect Agent | ||
|
|
||
| You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. You explore codebases to understand existing patterns, design implementation strategies that follow established conventions, and produce clear, actionable plans. You are methodical, risk-aware, and pragmatic — you favor working solutions over theoretical elegance, and you identify problems before they become expensive. | ||
| You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. You explore codebases to understand existing patterns, design implementation strategies that follow established conventions, and produce clear, actionable plans. You are methodical, risk-aware, and pragmatic — you favor working solutions over theoretical elegance, and you identify problems before they become expensive. Bad plans cascade into bad implementations — your plans must be so specific that an implementer can execute each step without re-interpreting your intent. |
There was a problem hiding this comment.
Tighten the opening paragraph wording for readability.
Line 34 repeats the same sentence start pattern multiple times, which makes the intro feel mechanical. A small rephrase would improve clarity.
✏️ Suggested wording tweak
-You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. You explore codebases to understand existing patterns, design implementation strategies that follow established conventions, and produce clear, actionable plans. You are methodical, risk-aware, and pragmatic — you favor working solutions over theoretical elegance, and you identify problems before they become expensive. Bad plans cascade into bad implementations — your plans must be so specific that an implementer can execute each step without re-interpreting your intent.
+You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. Explore codebases to identify existing patterns, then design strategies that follow established conventions and produce clear, actionable plans. Be methodical, risk-aware, and pragmatic — favor working solutions over theoretical elegance, and surface problems before they become expensive. Bad plans cascade into bad implementations, so every step must be specific enough to execute without reinterpretation.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. You explore codebases to understand existing patterns, design implementation strategies that follow established conventions, and produce clear, actionable plans. You are methodical, risk-aware, and pragmatic — you favor working solutions over theoretical elegance, and you identify problems before they become expensive. Bad plans cascade into bad implementations — your plans must be so specific that an implementer can execute each step without re-interpreting your intent. | |
| You are a **senior software architect** specializing in implementation planning, trade-off analysis, and technical decision-making. Explore codebases to identify existing patterns, then design strategies that follow established conventions and produce clear, actionable plans. Be methodical, risk-aware, and pragmatic — favor working solutions over theoretical elegance, and surface problems before they become expensive. Bad plans cascade into bad implementations, so every step must be specific enough to execute without reinterpretation. |
🧰 Tools
🪛 LanguageTool
[style] ~34-~34: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...s, and produce clear, actionable plans. You are methodical, risk-aware, and pragmat...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/architect.md
at line 34, The opening paragraph of the "architect" agent repeats the same
sentence-start pattern and reads mechanically; rewrite that paragraph to vary
sentence openings and tighten phrasing for readability while preserving meaning
(you are a senior software architect specializing in implementation planning,
trade-off analysis, and technical decision-making). Locate the paragraph text in
agents/architect.md (the block beginning "You are a **senior software
architect**...") and rephrase to combine related clauses, remove redundant
starters, and use a more natural flow so an implementer can follow the intent
without changing the technical content.
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/dependency-analyst.md
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md
Outdated
Show resolved
Hide resolved
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md
Outdated
Show resolved
Hide resolved
- security-auditor: soften dependency boundary from "use X instead" to "prefer X" — agent still has A06 dependency tooling for surface-level checks, which doesn't conflict with a preference statement - dependency-analyst: add Ruby/Gem ecosystem to description (agent already supports Gemfile scanning) - documenter: add `bash` language identifier to fenced code block - generalist: refine Question Surfacing Protocol to distinguish correctness-affecting ambiguity (STOP) from minor ambiguity (proceed with documented assumption)
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md (1)
52-69: 🛠️ Refactor suggestion | 🟠 MajorResolve ambiguity-handling contradiction (stop vs continue-with-TODO).
The prompt currently requires an immediate stop for any ambiguity, but later instructs the agent to continue documenting verified parts and mark unknowns with
TODO: verify. This conflict will produce inconsistent orchestration behavior.Proposed wording alignment
-If you encounter ANY of these situations, you MUST stop and return: +If you encounter correctness-affecting ambiguity, you MUST stop and return: -Never assume behavior you haven't verified by reading code. If a function is complex and unclear, document what you can verify and flag uncertainty with `TODO: verify`. +For non-blocking ambiguity, document only verified behavior and flag uncertainty with `TODO: verify`.Also applies to: 136-139, 352-353
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md around lines 52 - 69, The document has a contradiction between the "How to Surface Questions" rule that mandates an immediate stop and the later instruction to continue documenting verified parts with "TODO: verify"; reconcile by clarifying the escalation policy in the "How to Surface Questions" section: state that the agent MUST stop and emit a "## BLOCKED: Questions" only for true blocking ambiguities (list the existing bullet points), but for non-blocking gaps the agent should continue producing partial documentation and annotate unknowns with "TODO: verify"; update references to "## BLOCKED: Questions" and to "TODO: verify" (and the surrounding paragraphs) so they consistently describe which classes of ambiguity trigger a stop vs which allow continuation and partial output.
♻️ Duplicate comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md (1)
117-117:⚠️ Potential issue | 🟡 MinorAdd missing language identifiers to remaining fenced code blocks (MD040).
markdownlint is still reporting multiple unlabeled fenced blocks. Please add a language tag (
text,bash,markdown, etc.) to each flagged block.Also applies to: 135-135, 160-160, 199-199, 213-213, 236-236
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md at line 117, Multiple fenced code blocks in documenter.md are missing language identifiers (markdownlint MD040) — locate the unlabeled fenced blocks (for example the block following the line that contains "Glob: **/main.*, **/index.*, **/app.*, **/server.*" and the other flagged blocks) and add appropriate language tags (e.g., ```bash, ```text, ```markdown) to each fenced code block so markdownlint no longer reports MD040 for those sections.
🧹 Nitpick comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md (1)
11-13: Consider making the scope boundary more explicit.The softened language ("prefer", "dedicated") successfully resolves the hard contradiction flagged in the previous review. However, the distinction between when to use this agent's A06 dependency scanning versus routing to
dependency-analystrelies on inference.Consider explicitly stating the boundary, for example: "Includes basic dependency vulnerability scanning as part of comprehensive audits; for dedicated dependency analysis or complex supply-chain investigations, prefer dependency-analyst."
Optional wording refinement
- auth flows, or input handling. Focuses primarily on CODE-LEVEL security. - For dedicated dependency/package vulnerability analysis, prefer - dependency-analyst. + auth flows, or input handling. Focuses primarily on CODE-LEVEL security + and includes basic dependency vulnerability scanning as part of comprehensive + audits. For dedicated dependency analysis or complex supply-chain + investigations, prefer dependency-analyst.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md around lines 11 - 13, Clarify the scope boundary in the security-auditor agent docs by adding an explicit sentence after the existing line about dependency analysis that states: "Includes basic dependency vulnerability scanning (A06) as part of comprehensive code audits; for dedicated dependency analysis or complex supply-chain investigations, prefer the dependency-analyst agent." Update the file section mentioning "auth flows, or input handling. Focuses primarily on CODE-LEVEL security." to reference this new sentence so readers see when to use security-auditor versus dependency-analyst (mentioning the A06 scan and the dependency-analyst agent by name).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md:
- Around line 160-168: Update the documentation text in documenter.md to resolve
the contradiction by explicitly allowing derived, hand-written request/response
examples while continuing to forbid verbatim reproduction of source/type/schema
files; replace the vague “no source reproduction” wording with a clear rule such
as “Do not paste verbatim source/type/schema definitions — instead provide
concise, derived usage examples and concrete request/response pairs that
illustrate expected inputs and outputs without copying original code.” Apply
this clarification to the sections that mention examples and schema reproduction
(the blocks describing Request body, Response, Errors, and Example) so the spec
consistently instructs authors to include practical, illustrative examples but
not raw source dumps.
---
Outside diff comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md:
- Around line 52-69: The document has a contradiction between the "How to
Surface Questions" rule that mandates an immediate stop and the later
instruction to continue documenting verified parts with "TODO: verify";
reconcile by clarifying the escalation policy in the "How to Surface Questions"
section: state that the agent MUST stop and emit a "## BLOCKED: Questions" only
for true blocking ambiguities (list the existing bullet points), but for
non-blocking gaps the agent should continue producing partial documentation and
annotate unknowns with "TODO: verify"; update references to "## BLOCKED:
Questions" and to "TODO: verify" (and the surrounding paragraphs) so they
consistently describe which classes of ambiguity trigger a stop vs which allow
continuation and partial output.
---
Duplicate comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md:
- Line 117: Multiple fenced code blocks in documenter.md are missing language
identifiers (markdownlint MD040) — locate the unlabeled fenced blocks (for
example the block following the line that contains "Glob: **/main.*, **/index.*,
**/app.*, **/server.*" and the other flagged blocks) and add appropriate
language tags (e.g., ```bash, ```text, ```markdown) to each fenced code block so
markdownlint no longer reports MD040 for those sections.
---
Nitpick comments:
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md:
- Around line 11-13: Clarify the scope boundary in the security-auditor agent
docs by adding an explicit sentence after the existing line about dependency
analysis that states: "Includes basic dependency vulnerability scanning (A06) as
part of comprehensive code audits; for dedicated dependency analysis or complex
supply-chain investigations, prefer the dependency-analyst agent." Update the
file section mentioning "auth flows, or input handling. Focuses primarily on
CODE-LEVEL security." to reference this new sentence so readers see when to use
security-auditor versus dependency-analyst (mentioning the A06 scan and the
dependency-analyst agent by name).
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/dependency-analyst.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/security-auditor.md
| Document every public endpoint or function: | ||
|
|
||
| - **Endpoint/Function signature**: Method, path, parameters with types. | ||
| - **Description**: What it does (one sentence). | ||
| - **Parameters**: Name, type, required/optional, description, constraints. | ||
| - **Request body**: Schema with field descriptions and a concrete example. | ||
| - **Response**: Status codes, response schema, concrete example. | ||
| - **Errors**: Error codes and conditions. | ||
| - **Example**: A complete request/response pair that could be copy-pasted. |
There was a problem hiding this comment.
Tighten conflicting guidance on examples vs “no source reproduction.”
The spec asks for concrete request/response examples and “show, don’t tell,” but later forbids reproducing source/type definitions in docs. As written, this can be interpreted to ban practical examples entirely. Clarify that derived usage examples are allowed while verbatim source/type/schema dumps are not.
Also applies to: 230-235, 332-333, 341-343
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 160-160: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
@.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/documenter.md
around lines 160 - 168, Update the documentation text in documenter.md to
resolve the contradiction by explicitly allowing derived, hand-written
request/response examples while continuing to forbid verbatim reproduction of
source/type/schema files; replace the vague “no source reproduction” wording
with a clear rule such as “Do not paste verbatim source/type/schema definitions
— instead provide concise, derived usage examples and concrete request/response
pairs that illustrate expected inputs and outputs without copying original
code.” Apply this clarification to the sections that mention examples and schema
reproduction (the blocks describing Request body, Response, Errors, and Example)
so the spec consistently instructs authors to include practical, illustrative
examples but not raw source dumps.
Summary
Core problems solved
Files changed (20)
main-system-prompt.mdarchitect.mdgeneralist.mdCHANGELOG.mdTest plan
Summary by CodeRabbit
New Features
Documentation
Chores