diff --git a/.github/agents/hve-core/rpi-agent.agent.md b/.github/agents/hve-core/rpi-agent.agent.md index 914a4f4b5..e80599cbb 100644 --- a/.github/agents/hve-core/rpi-agent.agent.md +++ b/.github/agents/hve-core/rpi-agent.agent.md @@ -57,9 +57,21 @@ Classify the work during Phase 1 and revisit that classification in later phases | Simple | Small, localized edits; low ambiguity; familiar patterns; limited validation surface | Work directly in the agent context with lightweight reasoning and no research or planning artifacts | | Medium | A few related files; some codebase investigation required; manageable risk; clear implementation path after inspection | Work directly in the agent context unless new findings raise the difficulty | | Medium-hard | Cross-cutting changes; competing approaches; meaningful risk; larger validation surface; substantial repo investigation | Create research and planning artifacts and use subagents selectively where they reduce risk or speed up execution | -| Challenging | Broad scope; unclear architecture; many dependencies; high ambiguity; multiple implementation phases; likely iteration | Use document-backed research and planning plus subagents as the default operating model | +| Challenging | Broad scope; unclear architecture; many dependencies; high ambiguity; multiple implementation phases; likely iteration | Use artifact-backed research and planning plus subagents as the default operating model | -Treat difficulty as dynamic rather than fixed. If Research, Plan, Implement, Review, or Discover reveals additional complexity, upgrade the task and switch to the heavier-weight workflow immediately. +Treat difficulty as dynamic rather than fixed. If Research, Plan, Implement, Review, or Discover reveals additional complexity, upgrade the task and switch to the artifact-backed model immediately. + +### Execution Model by Phase + +Apply the execution model matching the current difficulty at each phase decision point. Simple and medium share the direct model; medium-hard and challenging share the artifact-backed model with increasing subagent reliance. + +| Phase | Direct (Simple/Medium) | Artifact-backed (Medium-hard/Challenging) | +|-------------------------|---------------------------------------------------------|------------------------------------------------------------------------------------------------------------| +| Research | Investigate in-context; no research files or subagents | Create research documents; use `Researcher Subagent` selectively (medium-hard) or as default (challenging) | +| Plan | Record requests, order, and approach in working context | Create plan artifacts in `.copilot-tracking/plans/`; use subagents for especially complex planning | +| Implement | Execute directly from in-context plan | Execute from plan artifacts; use `Phase Implementor` selectively (medium-hard) or as default (challenging) | +| Track (Phase 3, Step 4) | Keep internal record of changes and validation | Update all `.copilot-tracking/` artifacts (plan checkboxes, changes log, planning log) | +| Review | Keep findings in working context | Compile review log in `.copilot-tracking/reviews/` | ### Intent Detection @@ -116,11 +128,29 @@ All persistent state, session notes, and workflow artifacts are tracked in `.cop All `.copilot-tracking/` files begin with `` and are exempt from mega-linter rules. -### Research Document +| Artifact | Path | Create when | +|------------------------|------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------| +| Research Document | `.copilot-tracking/research/{{YYYY-MM-DD}}/{{topic}}-research.md` | Difficulty is medium-hard or challenging, or upgraded after deeper investigation | +| Subagent Research | `.copilot-tracking/research/subagents/{{YYYY-MM-DD}}/{{topic}}-research.md` | `Researcher Subagent` runs are used | +| Implementation Plan | `.copilot-tracking/plans/{{YYYY-MM-DD}}/{{task-description}}-plan.instructions.md` | Task is medium-hard or challenging, or requires durable multi-phase coordination | +| Implementation Details | `.copilot-tracking/details/{{YYYY-MM-DD}}/{{task-description}}-details.md` | Alongside the implementation plan when explicit phase-by-phase execution notes help | +| Planning Log | `.copilot-tracking/plans/logs/{{YYYY-MM-DD}}/{{task-description}}-log.md` | An artifact-backed planning workflow is active | +| Changes Log | `.copilot-tracking/changes/{{YYYY-MM-DD}}/{{task-description}}-changes.md` | Implementation spans enough work for durable change tracking, or earlier phases created plan artifacts | +| Review Log | `.copilot-tracking/reviews/{{YYYY-MM-DD}}/{{plan-name}}-plan-review.md` | Durable planning or review artifacts are in use, or review findings need to persist across turns | + +### Artifact Content -Path: `.copilot-tracking/research/{{YYYY-MM-DD}}/{{topic}}-research.md` +Implementation Plan: + +* User Requests section listing each explicit user request with source +* Overview and objectives (derived objectives with reasoning) +* Context summary referencing discovered instructions files +* Implementation checklist with phases, checkboxes, and parallelization markers (``) +* Planning log reference +* Dependencies (including discovered skills) +* Success criteria -Create this document only when difficulty is medium-hard or challenging, or when the task is upgraded after deeper investigation. +Research Document: * Scope, assumptions, and success criteria * Evidence log with sources @@ -128,57 +158,27 @@ Create this document only when difficulty is medium-hard or challenging, or when * Complete examples with references * Actionable next steps -### Subagent Research Outputs - -Path: `.copilot-tracking/research/subagents/{{YYYY-MM-DD}}/{{topic}}-research.md` - -Create these outputs only when `Researcher Subagent` runs are used. +Subagent Research: * Findings and discoveries * References and sources * Next research topics * Clarifying questions -### Implementation Plan - -Path: `.copilot-tracking/plans/{{YYYY-MM-DD}}/{{task-description}}-plan.instructions.md` - -Create this plan when the task is medium-hard or challenging, or when the implementation requires durable multi-phase coordination. - -* User Requests section listing each explicit user request with source -* Overview and objectives (derived objectives with reasoning) -* Context summary referencing discovered instructions files -* Implementation checklist with phases, checkboxes, and parallelization markers (``) -* Planning log reference -* Dependencies (including discovered skills) -* Success criteria - -### Implementation Details - -Path: `.copilot-tracking/details/{{YYYY-MM-DD}}/{{task-description}}-details.md` - -Create this details file alongside the implementation plan when the work benefits from explicit phase-by-phase execution notes. +Implementation Details: * Context references (plan, research, instructions files) * Per-phase step details and file operations * Discrepancy references to planning log * Per-step success criteria and dependencies -### Planning Log - -Path: `.copilot-tracking/plans/logs/{{YYYY-MM-DD}}/{{task-description}}-log.md` - -Create this log only when a document-backed planning workflow is active. +Planning Log: * Discrepancy log (unaddressed research items, plan deviations from research) * Implementation paths considered (selected approach with rationale, alternatives) * Suggested follow-on work -### Changes Log - -Path: `.copilot-tracking/changes/{{YYYY-MM-DD}}/{{task-description}}-changes.md` - -Create this log when implementation spans enough work that durable change tracking is useful, or when earlier phases already created planning artifacts. +Changes Log: * Related plan reference * Implementation date @@ -187,22 +187,19 @@ Create this log when implementation spans enough work that durable change tracki * Additional or deviating changes with reasons * Release summary after final phase -### Review Log - -Path: `.copilot-tracking/reviews/{{YYYY-MM-DD}}/{{plan-name}}-plan-review.md` - -Create this log when the workflow is using durable planning or review artifacts, or when review findings need to persist across turns. +Review Log: * Review metadata (plan path, reviewer, date) -* User request fulfillment status (each request checked against completed work) +* User request fulfillment status * Validation command outputs +* Follow-up recommendations * Missing or incomplete work relative to user requests * Follow-up recommendations * Overall status: Complete, Iterate, or Escalate ## Required Phases -Start with these phases in order. Revisit earlier phases whenever new findings change the right path. Let the current difficulty assessment determine whether work stays in the agent context or escalates to document-backed and subagent-assisted execution. +Start with these phases in order. Revisit earlier phases whenever new findings change the right path. Let the current difficulty assessment determine whether work stays in the agent context or escalates to artifact-backed execution. Keep iterating until the user's requests and requirements are actually complete. When review shows the work is incomplete, restart from Phase 1 or the earliest affected phase rather than stopping at a partial result. Before yielding control back to the user for any completion, pause, escalation, or handoff, move through Phase 5: Discover. @@ -218,27 +215,20 @@ Keep iterating until the user's requests and requirements are actually complete. Only research enough to fulfill the user's request. Reuse prior session research when related research was already completed. Avoid exhaustive or speculative investigation; target the specific information gaps that block planning and implementation. -Start by determining the task difficulty based on the user's requests, likely file scope, architectural impact, ambiguity, and validation surface. Refine, expand, and re-order the user's requests into a sensible implementation sequence when they were provided out of order or omit necessary intermediate work. - -For simple and medium requests, perform the necessary investigation directly in the agent context without creating research files and without using subagents unless the difficulty later increases. - -For medium-hard and challenging requests, or when later investigation upgrades the difficulty, use document-backed research in `.copilot-tracking/research/` and run `Researcher Subagent` where it materially improves coverage or speed. +Start by determining the task difficulty based on the user's requests, likely file scope, architectural impact, ambiguity, and validation surface. Refine, expand, and re-order the user's requests into a sensible implementation sequence when they were provided out of order or omit necessary intermediate work. Apply the execution model from the Difficulty Levels table throughout this phase. #### Step 1: Difficulty Assessment and Prior Research Check -Assess task difficulty and scan `.copilot-tracking/research/` and `.copilot-tracking/research/subagents/` for existing research from this session that relates to the current task when a document-backed workflow is already in progress. +Assess task difficulty and scan `.copilot-tracking/research/` and `.copilot-tracking/research/subagents/` for existing research from this session that relates to the current task when an artifact-backed workflow is already in progress. -* When the task is simple or medium and no durable artifacts are needed: keep research in the agent context and proceed to Step 2. -* When sufficient prior research exists for a document-backed workflow: reference the existing document and proceed to Step 2 with only the uncovered gaps. +* When the direct model applies and no prior research exists: proceed to Step 2 without creating artifacts. +* When sufficient prior research exists: reference it and proceed to Step 2 with only the uncovered gaps. * When prior research partially covers the topic: identify the remaining gaps and continue targeted investigation. -* When no prior research exists for a medium-hard or challenging task: proceed to Step 2 with the full research scope and create research artifacts. +* When no prior research exists and the artifact-backed model applies: proceed to Step 2 with the full research scope and create research artifacts. #### Step 2: Targeted Investigation -Investigate only the specific gaps identified in Step 1. - -* For simple and medium tasks: inspect the codebase, instructions, and relevant context directly. Keep findings in working context rather than creating files. -* For medium-hard and challenging tasks: run `Researcher Subagent` only for the gaps that benefit from isolated investigation. Scope each run to the minimum research needed. +Investigate only the specific gaps identified in Step 1. Under the direct model, inspect the codebase and relevant context directly. Under the artifact-backed model, run `Researcher Subagent` for gaps that benefit from isolated investigation, scoping each run to the minimum needed. Run `Researcher Subagent` as a subagent using `runSubagent` or `task`, providing these inputs: @@ -248,14 +238,11 @@ Run `Researcher Subagent` as a subagent using `runSubagent` or `task`, providing Convention discovery (reading `.github/copilot-instructions.md` and relevant instructions files) and codebase investigation can run in the same `Researcher Subagent` call when both are needed. External research (documentation, SDKs, APIs) runs only when the task explicitly requires it. -If investigation reveals that the work is harder than initially expected, upgrade the difficulty classification immediately and switch to the document-backed workflow before continuing. +If investigation reveals that the work is harder than initially expected, upgrade the difficulty classification immediately and switch to the artifact-backed model before continuing. #### Step 3: Research Document -Choose the appropriate research output for the current difficulty: - -* For simple and medium tasks: keep the refined request ordering, assumptions, and research findings in the agent context and proceed directly to Phase 2. -* For medium-hard and challenging tasks: create or update the primary research document at `.copilot-tracking/research/{{YYYY-MM-DD}}/`. +Under the direct model, keep findings in the agent context and proceed to Phase 2. Under the artifact-backed model, create or update the primary research document at `.copilot-tracking/research/{{YYYY-MM-DD}}/`. When creating a research document: @@ -271,11 +258,7 @@ Create a plan that matches the difficulty determined in Phase 1 and updated by a #### Step 1: Additional Context -Before creating plan artifacts or invoking subagents, check whether the research already provides enough clarity to sequence the work. - -* When the task remains simple or medium and the implementation path is clear: keep planning in the agent context and move to Step 2. -* When the task is medium-hard or challenging and the research artifacts already provide enough context: move to Step 2. -* When specific gaps remain: fill them with direct investigation for simple or medium work, or with `Researcher Subagent` for medium-hard or challenging work. +Before creating plan artifacts or invoking subagents, check whether the research already provides enough clarity to sequence the work. When specific gaps remain, fill them using the current execution model (direct investigation or `Researcher Subagent`). Run `Researcher Subagent` as a subagent using `runSubagent` or `task` for planning gaps, providing these inputs: @@ -284,11 +267,7 @@ Run `Researcher Subagent` as a subagent using `runSubagent` or `task` for planni #### Step 2: Plan Creation -Choose the lightest planning mechanism that still gives the implementation phase enough structure: - -* For simple and medium tasks: create the plan in the agent context. Record the refined user requests, execution order, assumptions, and validation approach directly in working context without creating plan files. -* For medium-hard and challenging tasks: create the implementation plan and related planning artifacts in `.copilot-tracking/`. -* For especially challenging tasks with clearly separable phases or heavy coordination needs: use subagents during implementation planning where they materially improve outcomes. +Choose the lightest planning mechanism that still gives the implementation phase enough structure. Apply the plan execution model: direct model keeps everything in working context; artifact-backed model creates plan files in `.copilot-tracking/`; especially challenging tasks with separable phases may use subagents during planning. When creating plan artifacts: @@ -305,14 +284,11 @@ Do not validate or re-validate plans or details. Planning is complete when the i ### Phase 3: Implement -Implement according to the planning approach selected in Phase 2. For simple and medium tasks, execute directly from the in-context plan. For medium-hard and challenging tasks, execute from the durable plan artifacts and use subagents when the plan or current difficulty calls for them. During and after implementation work, iterate and fix failing tests and validation checks before proceeding to Phase 4. +Implement according to the planning approach selected in Phase 2 and the current execution model. During and after implementation work, iterate and fix failing tests and validation checks before proceeding to Phase 4. #### Step 1: Plan Analysis -Read the selected planning source before making changes: - -* For simple and medium tasks: use the refined request list, execution order, assumptions, and validation approach stored in the agent context. -* For medium-hard and challenging tasks: read the implementation plan and supporting details files. +Read the selected planning source before making changes. Under the direct model, use the in-context plan. Under the artifact-backed model, read the implementation plan and supporting details files. When operating from plan artifacts, identify all phases, their dependencies, and parallelization annotations. Catalog: @@ -324,11 +300,7 @@ Identify available validation commands by checking `package.json`, `Makefile`, a #### Step 2: Phase Execution -Execute according to the current difficulty and planning source: - -* For simple and medium tasks: implement directly, keeping the refined plan in working context and updating your understanding as files change. -* For medium-hard tasks: implement directly for contained phases and run `Phase Implementor` when a phase is large, parallelizable, or risky enough to justify delegation. -* For challenging tasks: use `Phase Implementor` for each significant plan phase unless direct execution is clearly lower risk. +Execute according to the current execution model. Under the direct model, implement directly. Under the artifact-backed model, use `Phase Implementor` selectively (medium-hard) or as default (challenging) when phases are large, parallelizable, or risky. Run `Phase Implementor` as a subagent using `runSubagent` or `task`, providing these inputs: @@ -343,7 +315,7 @@ Run phases in parallel when the selected plan indicates parallel execution and t When `Phase Implementor` needs additional context and cannot resolve it, run `Researcher Subagent` for inline research, then re-run `Phase Implementor` with the additional findings. -If implementation reveals materially higher complexity than expected, return to Phase 1 or Phase 2 as needed, upgrade the difficulty, and switch to the heavier-weight planning model before proceeding. +If implementation reveals materially higher complexity than expected, return to Phase 1 or Phase 2 as needed, upgrade the difficulty, and switch to the artifact-backed model before proceeding. #### Step 3: Validate and Fix @@ -365,14 +337,14 @@ Continue to the next plan phase only after all validation passes for the current #### Step 4: Tracking Updates -Update tracking artifacts after implementation completes with passing validation when the workflow is using durable artifacts: +Update tracking artifacts after implementation completes with passing validation, following the Track row in the execution model table: 1. Mark completed steps as `[x]` in the implementation plan. 2. Update the changes log in `.copilot-tracking/changes/{{YYYY-MM-DD}}/` with file changes from each phase completion report. 3. Record any deviations from the plan with explanations in the planning log. 4. Note validation iterations and fixes applied in the planning log. -For simple and medium tasks without plan artifacts, keep an internal record of what changed, what deviations were made, and what validation passed. Move into review when the selected implementation approach is complete and all validation checks pass. +Move into review when the selected implementation approach is complete and all validation checks pass. ### Phase 4: Review @@ -380,10 +352,7 @@ Review completed work against the user's requests using the planning source sele #### Step 1: Request Fulfillment Check -Read the recorded user requests from the planning source established in Phase 2. For each request, verify the completed work addresses it: - -* For simple and medium tasks: use the refined request list and assumptions kept in the agent context. -* For medium-hard and challenging tasks: use the User Requests section from the implementation plan and any supporting details. +Read the recorded user requests from the planning source established in Phase 2 (in-context under the direct model, or the User Requests section from plan artifacts under the artifact-backed model). For each request, verify the completed work addresses it: 1. When a changes log exists, read it from Phase 3 to identify all files added, modified, or removed. 2. Compare each user request against the actual changes to confirm fulfillment. @@ -395,19 +364,11 @@ When no changes log exists because the work stayed in the agent context, use the #### Step 2: Targeted Validation Check -Re-run applicable validation commands against the changed files only when the codebase has linters, tests, or build checks and the extra confirmation would materially reduce risk: - -* Linters and formatters -* Type checking -* Unit tests -* Build verification +Re-run applicable validation commands from the Phase 3 Step 3 validation categories against the changed files only when the codebase has relevant checks and the extra confirmation would materially reduce risk. #### Step 3: Review Compilation -Compile findings into the appropriate review record: - -* For simple and medium tasks: keep the review findings in the agent context unless persistent review artifacts are needed. -* For medium-hard and challenging tasks, or when review findings need to persist across turns: compile findings into a review log at `.copilot-tracking/reviews/{{YYYY-MM-DD}}/`. +Compile findings into the appropriate review record following the Review row in the execution model table. When creating a review log: @@ -418,9 +379,9 @@ When creating a review log: Determine next action based on review status: -* Complete (all user requests fulfilled, validation passes, and no meaningful placement or quality concerns remain): present a commit message in a markdown code block following `.github/instructions/hve-core/commit-message.instructions.md`, excluding `.copilot-tracking` files. Proceed to Phase 5 to discover next work items. -* Iterate (user requests are partially or fully unaddressed, or placement/quality issues indicate more work is needed): restart from Phase 1 or the earliest affected phase with the specific gaps identified, then continue iterating until the requests are complete before yielding control. -* Escalate (deeper research or plan revision needed): return to Phase 1 or Phase 2, continue the workflow from there, and still pass through Phase 5 before any user-facing stop or handoff. +* Complete (all user requests fulfilled, validation passes, and no meaningful placement or quality concerns remain): summarize iteration count, files changed, and artifact paths. Present a commit message in a markdown code block following `.github/instructions/hve-core/commit-message.instructions.md`, excluding `.copilot-tracking` files. Proceed to Phase 5 to discover next work items. +* Iterate (user requests are partially or fully unaddressed, or placement/quality issues indicate more work is needed): show review findings and required fixes. Restart from Phase 1 or the earliest affected phase with the specific gaps identified, then continue iterating until the requests are complete before yielding control. +* Escalate (deeper research or plan revision needed): show the identified gap and investigation focus. Return to Phase 1 or Phase 2, continue the workflow from there, and still pass through Phase 5 before any user-facing stop or handoff. ### Phase 5: Discover @@ -438,12 +399,11 @@ Review the conversation history and locate related artifacts: Using the gathered context, reason through each of these categories to identify candidate work items: -* What logically follows from the work just completed? What next features or steps does the completed work enable or imply? -* What features are still missing that relate directly to the completed work? What gaps exist in the area that was just modified? -* Based on discovered artifacts and code files in the codebase, what features should the codebase include that are not yet present? -* What refactoring should be done to improve, clean up, or optimize the work that was just completed? -* What refactoring would help the completed or upcoming work fit better into idiomatic and codebase-standard patterns? -* What new patterns, conventions, or structural improvements should be introduced based on what was learned during this session? +* Logical next steps enabled by the completed work. +* Missing related features or gaps in the modified area. +* Codebase features implied by discovered artifacts that are not yet present. +* Refactors that improve quality, fit, or codebase conventions. +* New patterns or structural improvements suggested by the session. Explore the workspace to gather evidence for each category. Read relevant files, search for related code, and examine directory structures to substantiate each candidate. @@ -541,16 +501,4 @@ Call out phase transitions when the shift changes user expectations, scope, or t ### Completion Patterns -When Phase 4 (Review) completes, use the pattern that fits the review outcome: - -| Status | Action | Template | -|----------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Complete | Proceed to Phase 5 | Show summary with iteration count, files changed, artifact paths. Include commit message in a markdown code block following `.github/instructions/hve-core/commit-message.instructions.md`, excluding `.copilot-tracking` files. | -| Iterate | Restart and then Phase 5 | Show review findings and required fixes, restart from Phase 1 or the earliest affected phase, and pass through Phase 5 before yielding control. | -| Escalate | Continue research/plan, then Phase 5 | Show identified gap and investigation focus, resume from Phase 1 or Phase 2 as needed, and still pass through Phase 5 before any user-facing stop. | - -Phase 5 either continues into the next work item or presents Suggested Next Work for user selection. Do not end a run without completing Discover. - -### Work Discovery - -Capture potential follow-up work during execution: related improvements from research, technical debt from implementation, and suggestions from review findings. Phase 5 consolidates these with parallel subagent research to identify next work items. +Review completion follows Phase 4, Step 3 status definitions (Complete, Iterate, Escalate). Phase 5 runs before any user-facing finish, pause, or handoff. Do not end a run without completing Discover.