feat(agents): optimize RPI agent context management with discipline rules#1492
feat(agents): optimize RPI agent context management with discipline rules#1492
Conversation
… response formats - introduce hve-core/rpi-context-discipline.instructions.md for parent RPI agents - reference context discipline from rpi-agent, task-researcher, planner, implementor, reviewer - tighten subagent response formats to executive summaries with full detail on disk - update hve-core, hve-core-all, and project-planning collections plus generated plugins 🧹 - Generated by Copilot
…ditional output details - add count of DR- and DD- items in plan-validator - include relative path to research document in researcher subagent - add checklist of recommended next steps for both subagents 🔍 - Generated by Copilot
…t agents 🔒 - Generated by Copilot
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1492 +/- ##
==========================================
- Coverage 87.44% 87.43% -0.01%
==========================================
Files 68 68
Lines 10335 10335
==========================================
- Hits 9037 9036 -1
- Misses 1298 1299 +1
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
…n subagent response formats - shorten rpi-context-discipline description to fit 120-char target - drop duplicated path bullet from researcher and rpi-validator response formats - reorder plan-validator response to put findings before DR-/DD- delta line - regenerate hve-core, hve-core-all, and project-planning plugin READMEs ✏️ - Generated by Copilot
… description and update applyTo path 🔧 - Generated by Copilot Co-authored-by: Copilot <copilot@github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Advisory review, this PR is from a maintainer. Findings are informational only.
Overview
This PR introduces a well-designed context-discipline mechanism for the RPI workflow. The single-source-of-truth approach (one shared instructions file referenced via #file: from all five parent agents) is the correct pattern for this type of cross-cutting concern, and the subagent response-format updates are clear and consistently applied. Overall the implementation is sound. A few items to consider:
Issue Alignment
PR Template Compliance
Copilot instructions and Copilot agent under Type of Change — both correct — but leaves all three items under the "AI Artifact Contributions" sub-checklist unchecked:
[ ] Used /prompt-analyze to review contribution[ ] Addressed all feedback from prompt-builder review[ ] Verified contribution follows common standards and type-specific requirements
If /prompt-analyze review was performed, these should be checked. If skipped intentionally, mark them (N/A — internal workflow change) consistent with the pattern used elsewhere in this PR's checklist.
Coding Standards
💡 PR description contains an inaccurate applyTo pattern. The description reads:
The
applyTopattern targets.copilot-tracking/{research,plans,details,changes,reviews,challenges}/**
But the actual file uses {research,plans,details,changes,reviews} — correctly omitting challenges, which is consistent with the in-file note that Task Challenger is intentionally out of scope. The PR description should be corrected to match the real pattern to avoid confusing future readers.
💡 Writing style violations in the new instructions file (inline comment on lines 24–27). The Response Mode Selection section uses **Term** — Description bolded-prefix list items with em dashes, which conflicts with both the em-dash and bolded-prefix-list conventions in writing-style.instructions.md. See the inline comment for a suggested restructure.
💡 Missing attribution suffix. The description field reads "Context-discipline rules for RPI parent agents: lean post-work turns, response modes, subagent results". Per prompt-builder.instructions.md, artifacts should carry a - Brought to you by microsoft/hve-core suffix in the description frontmatter. Several peer files (pull-request.instructions.md, commit-message.instructions.md) follow this convention. Worth aligning for consistency.
Code Quality
✅ No bugs, logic errors, security concerns, or missing error handling identified. The #file: path resolution for agents at .github/agents/hve-core/ resolving to ../../instructions/hve-core/rpi-context-discipline.instructions.md is correct. Plugin symlinks and collection YAML entries are consistent across all three collections.
Co-authored-by: Copilot <copilot@github.com>
There was a problem hiding this comment.
PR Review: feat(agents): optimize RPI agent context management with shared discipline rules
Overall this is a well-structured, clearly documented PR with a coherent design. The single-source pattern via #file: references is idiomatic for this codebase, all five parent agents are updated consistently, and the four subagent response-format rewrites follow the new lean protocol faithfully. The collection and plugin outputs are regenerated correctly. Below are the findings from each review dimension.
Issue Alignment
Issue #1536 was inaccessible via the review toolchain due to an integrity policy filter, so full issue-to-implementation traceability cannot be confirmed automatically. Based on the PR description alone, the stated goals (disk-first architecture, lean post-work turns, executive-summary responses, response-mode selection) are well-addressed by the changes. No scope creep or obviously missing requirements are visible.
Action required: Please verify that issue #1536's acceptance criteria are fully satisfied and nothing was left out.
PR Template Compliance
Two items need attention:
1. AI Artifact Contributions checklist is entirely unchecked
Under Checklist → AI Artifact Contributions, all three items remain unchecked:
[ ] Used /prompt-analyze to review contribution
[ ] Addressed all feedback from prompt-builder review
[ ] Verified contribution follows common standards and type-specific requirements
This is inconsistent with the Type of Change → AI Artifacts section, where [x] Reviewed contribution with prompt-builder agent and addressed all feedback is checked. If the prompt-builder review was completed and feedback was addressed, the matching checklist items should be checked as well.
2. Spell-check checkbox marked as passing but was blocked
The Testing section marks npm run spell-check as ✅ passed while also annotating it "(Blocked: requires Node.js ≥22.18.0)". A check that could not run should not be marked as passed — it should remain unchecked with the blocking reason noted inline.
Coding Standards Review
rpi-context-discipline.instructions.md ✅
- Frontmatter contains the required
descriptionandapplyTofields per instruction-file conventions. - Attribution suffix (
- Brought to you by microsoft/hve-core) is present in thedescriptionvalue. - H1 heading is correct — no
title:frontmatter field, so H1 is the right document title per the markdown rules. applyTopattern'**/.copilot-tracking/{research,plans,details,changes,reviews}/**'correctly targets the tracking files that agents write to during RPI sessions; agents additionally pull the file in explicitly via#file:, giving two activation paths as intended.- Bullet-point punctuation follows complete-sentence rules throughout. Table descriptions in the Response Mode Selection table are acceptable as fragments within table cells.
Agent #file: path resolution ✅
The path #file:../../instructions/hve-core/rpi-context-discipline.instructions.md resolves correctly from .github/agents/hve-core/ → .github/ → instructions/hve-core/... in both repo and plugin distribution contexts.
All five parent agents updated consistently ✅ (rpi-agent, task-implementor, task-planner, task-researcher, task-reviewer — all confirmed).
All four subagent response formats updated consistently ✅ (implementation-validator, plan-validator, researcher-subagent, rpi-validator — pattern is uniform: log-path line → status line → ≤7 bullets → ≤3 questions → "Re-read <path>..." pointer).
Collection and plugin outputs ✅ — three collections updated, three plugin README/symlink outputs regenerated.
Code Quality and Security
No bugs, logic errors, security vulnerabilities, or breaking changes identified. The change is purely additive for parent agents (new ## Context Discipline section) and a targeted rewrite of Response Format sections for subagents. No dependency changes, no secrets, no infrastructure modifications.
Action Items
| # | Item | Severity |
|---|---|---|
| 1 | Check all three AI Artifact Contributions checklist boxes if the prompt-builder review was completed and feedback addressed |
Minor — template compliance |
| 2 | Uncheck the spell-check item (or annotate it as N/A) rather than marking a blocked run as passed | Minor — template accuracy |
| 3 | Manually confirm issue #1536 acceptance criteria are fully addressed (automated check was blocked by integrity policy) | Advisory — cannot auto-verify |
Note
🔒 Integrity filter blocked 1 item
The following item were blocked because they don't meet the GitHub integrity level.
- #1536
issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | none
rezatnoMsirhC
left a comment
rezatnoMsirhC
left a comment
There was a problem hiding this comment.
Thank you for this contribution. The single-source approach for context-discipline rules is clean and the #file: propagation pattern is well suited to keeping these rules in sync across the RPI parent agents. Two minor comments left inline.
…remove separate instructions file - streamline response mode selection and subagent result handling - clarify lean post-work turn requirements - remove deprecated context-discipline instructions from various collections 🔧 - Generated by Copilot
katriendg
changed the title
There was a problem hiding this comment.
Advisory Review — feat(agents): optimize RPI agent context management with shared discipline rules
Advisory review: this PR is from a maintainer. Findings are informational only.
Issue Alignment
The PR links Closes #1536. A linked issue is present ✅. The stated intent — reducing context bloat in long-running RPI sessions by capping subagent chat payloads and enforcing lean post-work turns — is coherent and well-motivated.
PR Template Compliance
| Item | Status |
|---|---|
| Description section filled in | ✅ |
| Related issue(s) present | ✅ (Closes #1536) |
| Type of Change checked | ✅ (New feature) |
| "Copilot instructions" checkbox checked | |
AI Artifact prompt-builder review attestation |
✅ |
| Testing section completed | ✅ |
| Required checklist items checked | ✅ |
.github/instructions/hve-core/rpi-context-discipline.instructions.md, updating three collections, and regenerating three plugin outputs — yet none of these appear in the diff. The actual PR contains changes to exactly 9 agent files. The checkbox and substantial portions of the description describe scope that is not present.
Coding Standards
prompt-builder.instructions.md applies to all *.agent.md files.
Duplication vs. #file: convention (see inline comment on rpi-agent.agent.md): All five parent agents have an identical 23-line ## Context Discipline block pasted inline. The PR description claims this is backed by a shared instructions file with #file: references. The instructions file does not exist in this PR, and none of the agents contain #file: references. Per the prompt-builder single-source guidance, shared protocol blocks should use #file: to avoid divergence. As-is, any future change to the discipline rules requires editing five files.
Subagent response format changes are well-structured and align with the prompt-builder Subagent Structural Template conventions. The shift to prescriptive caps (≤7 bullets, ≤240 chars, ≤3 questions) is a clear improvement over the previous open-ended bullet lists. The plan-validator addition of DR-/DD- item counts is a useful signal for parent agents.
Writing style: No em-dash patterns, no bolded-prefix list items, appropriate use of tables. ✅
Code Quality
The functional intent of the changes is sound — disk-first architecture, executive summary chat responses, and explicit re-read-only-when-needed rules are a reasonable approach to managing context in long sessions.
Potential ambiguity in parent agents: The new ## Context Discipline section instructs the agent to "emit one compact line per subagent... stop." The existing ### Response Format sections in each parent agent describe full bottom-up presentations (e.g., task-researcher's summary table). The two sections can coexist if Context Discipline governs intermediate turns and Response Format governs final-turn summaries — but this boundary is not explicitly stated. A clarifying sentence (e.g., "This discipline applies to intermediate turns after subagent returns, not to final-turn user summaries.") would prevent an agent from short-circuiting its completion presentation.
Unbounded checklist in researcher-subagent and rpi-validator response formats (see inline comment): The "recommended next research" checklist lacks a cap, inconsistent with the bounded constraints added for all other response elements.
Action Items
- Resolve the description/implementation gap: Either create the missing
rpi-context-discipline.instructions.mdand replace inline duplicates with#file:references, or update the PR description to accurately reflect the inline-copy approach and uncheck the "Copilot instructions" checkbox. - Add a cap to the "recommended next research" checklist in
researcher-subagent.agent.mdandrpi-validator.agent.md(e.g., "up to 5 items") for consistency with the bounded format. - Consider a clarifying sentence in each parent agent's Context Discipline section to make the scope boundary with Response Format explicit.
Note
🔒 Integrity filter blocked 11 items
The following items were blocked because they don't meet the GitHub integrity level.
- #1536
issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 47ab056
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - b3d55bd
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 023b41c
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 34f4898
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 7ce258f
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 57ea279
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 5bedf80
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - b63642e
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - 6469168
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved". - a1e8878
list_commits: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | none…alidator subagents 🔧 - Generated by Copilot
There was a problem hiding this comment.
Advisory review, this PR is from a maintainer. Findings are informational only.
Overview
This PR introduces a Context Discipline block across all five RPI parent agents and tightens subagent Response Format sections to cap chat output to executive summaries, with full fidelity written to .copilot-tracking/ files. The design rationale — self-contained agent packaging and prompt-caching cache hits — is clearly articulated in the description and Additional Notes. The changes are coherent, well-scoped, and the disk-first architecture decision is sound.
Two advisory observations are noted below.
Issue Alignment
Linked issue #1536 could not be read during this review (integrity policy restriction). Based on the PR description and the changes themselves, the work clearly targets RPI agent context verbosity — the stated purpose is consistent with what was implemented.
PR Template Compliance
Three Required Automated Checks are neither checked nor annotated as N/A:
npm run spell-check— unchecked, no annotationnpm run lint:md-links— unchecked, no annotationnpm run docs:test— unchecked, no annotation
The template notes these "must pass before merging." If they are not applicable for agent-only .agent.md changes, please annotate them consistently with the other N/A items in the checklist (e.g., (N/A — agent body changes only, no new links or documentation pages)). This keeps the audit trail clear for reviewers.
Coding Standards
ALL CAPS directives — prompt-builder.instructions.md (Patterns to Avoid section) explicitly lists ALL CAPS directives and emphasis markers as patterns to avoid in prompt authoring:
"The following patterns provide limited value as prompt instructions: ALL CAPS directives and emphasis markers."
Affected lines across all nine changed files:
| File | Lines | Terms |
|---|---|---|
rpi-agent.agent.md |
96, 100 | MUST, Do NOT |
task-implementor.agent.md |
61, 65 | MUST, Do NOT |
task-planner.agent.md |
63, 67 | MUST, Do NOT |
task-researcher.agent.md |
55, 59 | MUST, Do NOT |
task-reviewer.agent.md |
42, 46 | MUST, Do NOT |
implementation-validator.agent.md |
202, 211 | ALWAYS, Do NOT |
researcher-subagent.agent.md |
61, 71 | ALWAYS, Do NOT |
plan-validator.agent.md |
97, 107 | ALWAYS, Do NOT |
rpi-validator.agent.md |
67, 77 | ALWAYS, Do NOT |
Inline comments are on representative examples (one parent agent, one subagent). A global find-and-replace of MUST → must, ALWAYS → always, and Do NOT → Do not across the nine files would resolve all instances without changing the instructional intent.
Code Quality
No bugs, security issues, or architectural concerns found. The inlining decision (vs. #file: shared instructions) is well-reasoned, and the response-format caps are practical and consistent across all four subagents.
Note
🔒 Integrity filter blocked 1 item
The following item were blocked because they don't meet the GitHub integrity level.
- #1536
issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | none…or consistency 🔧 - Generated by Copilot
There was a problem hiding this comment.
Advisory review — this PR is from a maintainer. Findings are informational only.
Review Summary
This PR is well-structured and clearly motivated. The Context Discipline section is verbatim-identical across all five RPI parent agents (by design, as documented in the PR description), and the subagent response format updates are consistent and purposeful. No critical issues found.
Issue Alignment
- Linked issue: Closes #1536 ✅
- The PR description thoroughly describes the intent (lean post-work turns, response mode selection, subagent result handling), and the diff directly reflects those goals.
- No scope creep identified — all 9 changed files are the exact agents named in the description.
PR Template Compliance
- Description, Related Issue, Type of Change, Sample Prompts, Testing, and Security Considerations are all filled in correctly.
- Minor: Two Required Automated Checks are left unchecked without an N/A annotation:
[ ] Spell checking: npm run spell-check— this script is active in the repo and covers*.mdfiles; consider running it and checking the box (or annotating N/A if it was run and confirmed clean).[ ] Link validation: npm run lint:md-links— same note; agent files may contain#file:or relative references that benefit from link-checking.
Coding Standards Review
Applicable instruction file: prompt-builder.instructions.md (applyTo: **/*.agent.md)
- ✅ All five parent agents correctly use
*bullet lists (no+or-mixing). - ✅ No bolded-prefix list-item pattern (
**Term:** description) introduced — the* 1 line: ...pattern in response format sections is not a violation. - ✅ Ordered list steps in the Context Discipline section use imperative voice, consistent with the instructions' guidance for autonomous/action steps.
- ✅ Table columns align and use consistent Mode naming.
- ✅ No temporal markers, thought-process commentary, or narrative comments introduced.
Code Quality
- The inlining rationale (self-contained packaging + prompt caching locality) is sound and well-documented.
- The
≤ 240 charsand≤ 7 bulletslimits are consistent across all four updated subagents. researcher-subagentandrpi-validatorboth cap the next-steps checklist at 5 items for symmetry — this is a good tightening.- The placement of the
## Context Disciplinesection varies slightly across agents (after the parallelism note in most, after the subagent behavior bullets intask-reviewer) — this is acceptable given each file has a different section structure.
Action Items
- (Advisory) Run
npm run spell-checkandnpm run lint:md-linksbefore merge, and check or annotate the corresponding checklist boxes.
Note
🔒 Integrity filter blocked 1 item
The following item were blocked because they don't meet the GitHub integrity level.
- #1536
issue_read: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
To allow these resources, lower min-integrity in your GitHub frontmatter:
tools:
github:
min-integrity: approved # merged | approved | unapproved | none3 participants
Description
Tightened context discipline for the RPI (Research, Plan, Implement, Review) agent family by adding a shared Context Discipline section directly inside each parent agent and capping subagent chat responses to executive summaries. Disk-first tracking files remain the source of truth; chat responses now act as indices.
The discipline is built around three protocols, all inlined verbatim into every RPI parent agent:
Why inline the rules into each agent
Two reasons drove keeping these rules inside each
*.agent.mdfile rather than extracting them to a separate.instructions.md:#file:reference adds a resolution dependency that complicates packaging, mirroring, and any future relocation of the artifact tree. Inlining keeps the agent self-contained and aligned with the existing hve-core convention for RPI agents.#file:does not deliver the same byte-identical-in-context advantage at the agent prompt level.Agent updates
The Context Discipline section was inlined into all 5 RPI parent agents:
Each parent agent now contains the same Lean Post-Work Turn steps, the Response Mode Selection table, and the Subagent Result Handling bullets.
Subagent response format updates
Response Format sections were tightened in 4 RPI subagents to enforce executive-summary chat output with full fidelity persisted to the corresponding tracking file. Each updated section caps the chat response (≤7 prioritized bullets, ≤240 chars each, up to 3 clarifying questions only when blocking) and explicitly forbids pasting full file contents, code blocks, validation output, or long quotes:
Related Issue(s)
Closes #1536
Type of Change
Select all that apply:
Code & Documentation:
Infrastructure & Configuration:
AI Artifacts:
prompt-builderagent and addressed all feedback.github/instructions/*.instructions.md).github/prompts/*.prompt.md).github/agents/*.agent.md).github/skills/*/SKILL.md)Other:
.ps1,.sh,.py)Sample Prompts (for AI Artifact Contributions)
User Request:
Existing RPI workflow invocations (
@rpi-agent,@task-researcher,@task-planner,@task-implementor,@task-reviewer) remain unchanged. Context optimization operates transparently.Execution Flow:
.copilot-tracking/file.Output Artifacts:
RPI tracking files in
.copilot-tracking/directories remain the source of truth. Chat responses now contain executive summaries instead of full payloads.Success Indicators:
Testing
Automated Validation:
npm run lint:md)npm run lint:frontmatter, 536 files)npm run lint:collections-metadata, 13 collections)npm run plugin:generate)Security Analysis:
Checklist
Required Checks
AI Artifact Contributions
/prompt-analyzeto review contributionprompt-builderreviewRequired Automated Checks
npm run lint:mdnpm run spell-checknpm run lint:frontmatternpm run validate:skillsnpm run lint:md-linksnpm run lint:psnpm run plugin:generatenpm run docs:testSecurity Considerations
Additional Notes
Self-contained agents over shared instructions. An earlier iteration of this branch extracted the Context Discipline rules into a dedicated
rpi-context-discipline.instructions.mdfile referenced from each parent agent via#file:. That approach was reverted in favor of inlining: it keeps RPI parent agents fully self-contained for extension and plugin packaging, and it lets prompt caching (Anthropic prompt caching) recognize the identical Context Discipline block as a stable, repeated region across RPI invocations within a session.Disk-first architecture. Chat responses are now indices, not full results. Subagents always write complete findings to their tracking files before returning the summary. Parents re-read only when the next decision requires evidence beyond the summary bullets, which keeps long RPI sessions from accumulating large per-turn payloads.