Skip to content

Refine system prompts — personality, communication protocols, compression#37

Closed
AnExiledDev wants to merge 3 commits intomainfrom
worktree-prompt-refinement
Closed

Refine system prompts — personality, communication protocols, compression#37
AnExiledDev wants to merge 3 commits intomainfrom
worktree-prompt-refinement

Conversation

@AnExiledDev
Copy link
Owner

@AnExiledDev AnExiledDev commented Feb 27, 2026

Summary

  • Main system prompt redesigned (672 → 462 lines) — added personality section, compressed low-value sections, removed browser automation and git worktrees (moved to loadable skills), added mandatory context-passing protocol for subagent spawning
  • All 21 agent prompts now have communication protocols — read-only agents get "Handling Uncertainty" (flag assumptions, continue), write-capable agents get "Question Surfacing Protocol" (BLOCKED + return for ambiguity)
  • Architect agent hardened — anti-fluff enforcement with banned patterns, team orchestration planning capability, strengthened output format
  • Generalist rewritten as last-resort — description actively discourages selection when a specialist matches
  • Bash guard hooks added to researcher, debug-logs, and perf-profiler agents

Core problems solved

  1. Main prompt had zero personality — now has casual-professional voice with AuDHD-aware communication patterns
  2. Agents didn't communicate back effectively (only 4/20 had protocols) — now all 21 do
  3. Generalist was over-selected — now explicitly labeled as last resort
  4. Orchestrator didn't pass sufficient context when spawning agents — new mandatory context-passing protocol
  5. Architect produced plans with AI fluff — anti-fluff enforcement with banned patterns and good/bad examples
  6. Main prompt had instruction bloat (672 lines) — compressed to 462 lines by removing rarely-used sections and deduplicating

Files changed (20)

Area Files Changes
Main prompt main-system-prompt.md Rewrite: personality, compression, reorder
Architect architect.md Anti-fluff, team planning, uncertainty handling
Generalist generalist.md Last-resort rewrite + question surfacing
Tier 1 agents (5) explorer, researcher, doc-writer, spec-writer, test-writer Communication protocols + targeted improvements
Tier 2 agents (2) investigator, git-archaeologist Structured output + uncertainty handling
Remaining agents (11) All others Communication protocol additions
Changelog CHANGELOG.md 22 new lines documenting all changes

Test plan

  • Load main prompt in a fresh session and verify personality comes through
  • Spawn architect agent — verify anti-fluff plan output
  • Verify generalist description is no longer a catch-all in agent routing
  • Spawn a read-only agent (explorer) — verify Handling Uncertainty section in output when given ambiguous task
  • Spawn a write agent (doc-writer) — verify BLOCKED: Questions output when given ambiguous task
  • Verify all existing hooks still work (no file renames that break paths)
  • Check Bash guard hooks work on researcher, debug-logs, perf-profiler

Summary by CodeRabbit

  • New Features

    • Uniform uncertainty handling: subagent non-interactive protocol, BLOCKED/Assumptions sections, and pre-tool guard hooks across agents.
    • Dynamic, port-agnostic forwarding with notifications.
  • Documentation

    • Major system-prompt/personality redesign with concise templates, anti‑fluff enforcement, and updated planning/execution guidance.
    • Expanded, phase-driven agent docs (planning, specs, docs, testing) and standardized output formats.
  • Chores

    • Agent roster updates: doc-writer → documenter, tester removed, agent counts and role listings adjusted.

…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.
@coderabbitai
Copy link

coderabbitai bot commented Feb 27, 2026

📝 Walkthrough

Walkthrough

This PR replaces <identity> with <personality> in the main system prompt, restructures policy and execution blocks, and updates ~20 agent specs to add standardized uncertainty/question-surfacing protocols, hooks, role renames (doc-writer → documenter), and worktree/isolation metadata.

Changes

Cohort / File(s) Summary
Core prompt & changelog
​.codeforge/config/main-system-prompt.md, .devcontainer/CHANGELOG.md
Replaced <identity> with <personality>; major reorganization of rule precedence, core directives, planning/execution, execution gate, and communication/formatting templates; changelog updated to reflect orchestration, policy, and infra moves.
Global uncertainty / surfacing protocol
devs-marketplace/plugins/agent-system/agents/.../bash-exec.md, .../claude-guide.md, .../debug-logs.md, .../dependency-analyst.md, .../explorer.md, .../git-archaeologist.md, .../investigator.md, .../migrator.md, .../perf-profiler.md, .../researcher.md, .../security-auditor.md, .../spec-writer.md, .../statusline-config.md, .../test-writer.md
Added standardized "Handling Uncertainty" / "Question Surfacing Protocol": subagents cannot ask users directly, must emit Assumptions or BLOCKED: Questions with alternatives, and follow stop/continue rules; expanded read-only/never-modify constraints in many agents.
Agent role changes & planning
devs-marketplace/plugins/agent-system/agents/architect.md, .../generalist.md, .../documenter.md, .../doc-writer.md
Architect: added anti-fluff enforcement, phased planning, complexity assessments. Generalist: redefined as fallback with tool restrictions and surfacing protocol. doc-writer removed and replaced by documenter (registry/docs updates).
Removals & additions (docs/test agents)
.../doc-writer.md (deleted), .../tester.md (deleted), .../documenter.md (added/expanded)
Removed old doc-writer and tester specs; added comprehensive documenter.md with phase-driven documentation strategy, templates, critical constraints, and spec lifecycle.
Skill / worktree updates
plugins/.../skill-engine/skills/*, plugins/.../spec-workflow/*, plugins/.../worktree/*, .devcontainer/README.md, .../agent-system/README.md
Replaced doc-writer refs with documenter, adjusted agent counts and role lists for worktree isolation, and updated parallel-workflow/spec-build references and tables.
Hooks & execution guards
.../debug-logs.md, .../perf-profiler.md, .../researcher.md, .../refactorer.md, .../investigator.md
Introduced PreToolUse/PostToolUse hooks (guard-readonly-bash.py checks, test-verification hooks), added permissionMode/isolation/memory metadata and stricter execution-discipline directives.

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
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

Poem

🐇 I hop through prompts with ears alert and bright,

I swapped a name for personality's light.
When questions bloom, I stamp a BLOCKED sign,
Send parcels to the orchestrator — neat and fine.
Assumptions listed, alternatives in sight,
I nibble uncertainty and keep outputs tight.

🚥 Pre-merge checks | ✅ 3
✅ Passed checks (3 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the main changes: system prompts are being refined with personality additions, communication protocols, and compression. It accurately captures the primary objectives.
Description check ✅ Passed The description is comprehensive and follows the template structure with Summary, Core problems solved, Files changed, and Test plan sections. All required elements are present and well-documented.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch worktree-prompt-refinement

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

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 | 🟡 Minor

Consolidate duplicate ### Changed sections under ## [Unreleased].

There’s already a ### Changed block at Line 5; introducing another at Line 168 fragments the same category. Merge these into a single ### Changed heading 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: Questions section (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 scope

Minor: 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

📥 Commits

Reviewing files that changed from the base of the PR and between 5612bc4 and 5ae914c.

📒 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

Comment on lines 196 to 223
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.

Copy link

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical

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.

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
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 4

♻️ Duplicate comments (1)
.devcontainer/plugins/devs-marketplace/plugins/agent-system/agents/generalist.md (1)

119-142: ⚠️ Potential issue | 🟡 Minor

Clarify 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:

  1. Adding a qualifier to the protocol: "MUST stop if the ambiguity affects correctness or requires user trade-off decisions"
  2. 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

📥 Commits

Reviewing files that changed from the base of the PR and between 5ae914c and ef2fae1.

📒 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.
Copy link

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

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.

Suggested change
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.

- 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)
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

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

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 | 🟠 Major

Resolve 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 | 🟡 Minor

Add 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-analyst relies 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

📥 Commits

Reviewing files that changed from the base of the PR and between ef2fae1 and 9de1a30.

📒 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

Comment on lines +160 to +168
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.
Copy link

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant