Skip to content

Commit a17c39c

Browse files
Copilotrjmurillo
Copilot
and
rjmurillo
committed
fix(agents): sync shared templates and regenerate platform agents
Co-authored-by: rjmurillo <6811113+rjmurillo@users.noreply.github.com>
1 parent 62883bd commit a17c39c

12 files changed

Lines changed: 799 additions & 9 deletions

‎.agents/planning/phase2-complete-handoff.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Phase 2 Handoff: Complete
2+
3+
**Date**: 2025-12-16
4+
**PR**: #49
5+
**Issue**: #44 (Agent Quality Remediation)
6+
**Branch**: `copilot/remediate-coderabbit-pr-43`
7+
8+
## Session Summary
9+
10+
Phase 2 consistency fixes have been implemented and the agent generation workflow has been corrected.
11+
12+
## Work Completed
13+
14+
### P1-1: Critic Escalation Template ✅
15+
- Added "Escalation Prompt Completeness Requirements" section
16+
- Added Verified Facts table template
17+
- Added anti-pattern: "Converting exact values to ranges"
18+
- Files: `templates/agents/critic.shared.md`, all platform outputs
19+
20+
### P1-2: Task Generator Estimate Reconciliation ✅
21+
- Added 10% threshold rule for estimate divergence
22+
- Added reconciliation process and actions table
23+
- Added output template for documenting reconciliation
24+
- Files: `templates/agents/task-generator.shared.md`, all platform outputs
25+
26+
### P1-3: Planner Condition Traceability ✅
27+
- Added Work Breakdown template with Conditions column
28+
- Added validation checklist for orphan conditions
29+
- Added anti-pattern: "Orphan Conditions"
30+
- Files: `templates/agents/planner.shared.md`, all platform outputs
31+
32+
### P1-4: Cross-Document Validation CI ✅
33+
- Created `build/scripts/Validate-PlanningArtifacts.ps1`
34+
- Created `build/scripts/tests/Validate-PlanningArtifacts.Tests.ps1` (17 tests)
35+
- Validates: estimate consistency, orphan conditions, document structure
36+
37+
### Workflow Correction ✅
38+
- Updated shared templates in `templates/agents/`
39+
- Ran `Generate-Agents.ps1` to regenerate all platform agents
40+
- Created retrospective document with learnings
41+
42+
## Files Changed in This Session
43+
44+
### Shared Templates
45+
```
46+
templates/agents/critic.shared.md
47+
templates/agents/task-generator.shared.md
48+
templates/agents/planner.shared.md
49+
```
50+
51+
### Generated Agents (36 total, 6 modified)
52+
```
53+
src/copilot-cli/critic.agent.md
54+
src/copilot-cli/task-generator.agent.md
55+
src/copilot-cli/planner.agent.md
56+
src/vs-code-agents/critic.agent.md
57+
src/vs-code-agents/task-generator.agent.md
58+
src/vs-code-agents/planner.agent.md
59+
```
60+
61+
### Validation Scripts
62+
```
63+
build/scripts/Validate-PlanningArtifacts.ps1
64+
build/scripts/tests/Validate-PlanningArtifacts.Tests.ps1
65+
```
66+
67+
### Previously Modified (src/claude)
68+
```
69+
src/claude/critic.md
70+
src/claude/task-generator.md
71+
src/claude/planner.md
72+
```
73+
74+
### Retrospective
75+
```
76+
.agents/retrospective/phase2-workflow-learnings.md
77+
```
78+
79+
## Key Learnings
80+
81+
1. **Agent Workflow**: Always update `templates/agents/*.shared.md` first, then run `Generate-Agents.ps1`
82+
2. **Tri-Platform Structure**: `src/claude/` is separate from the generator output (`src/copilot-cli/`, `src/vs-code-agents/`)
83+
3. **Validation**: Use `Generate-Agents.ps1 -Validate` to check for drift before making changes
84+
85+
## What's Left for Phase 3
86+
87+
Per issue #44, Phase 3 (P2) tasks remain:
88+
- P2-1: Update `src/claude/roadmap.md` with naming conventions
89+
- P2-2: Update `src/claude/memory.md` with freshness protocol
90+
- P2-3: Update `src/claude/orchestrator.md` with consistency checkpoint
91+
- P2-4: Create `.agents/governance/naming-conventions.md`
92+
- P2-5: Create `.agents/governance/consistency-protocol.md`
93+
94+
## Verification Commands
95+
96+
```bash
97+
# Validate agents match templates
98+
pwsh build/Generate-Agents.ps1 -Validate
99+
100+
# Run planning artifact validation
101+
pwsh build/scripts/Validate-PlanningArtifacts.ps1 -Path .
102+
103+
# Run Pester tests for new script
104+
pwsh -Command "Invoke-Pester build/scripts/tests/Validate-PlanningArtifacts.Tests.ps1 -Output Detailed"
105+
```
106+
107+
## For Future Agents
108+
109+
When continuing this work:
110+
1. Read this handoff document
111+
2. Read `.agents/retrospective/phase2-workflow-learnings.md` for workflow details
112+
3. Follow the correct workflow: templates → generate → verify → commit

‎.agents/retrospective/phase2-workflow-learnings.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Retrospective: Phase 2 CodeRabbit Remediation - Workflow Learnings
2+
3+
**Date**: 2025-12-16
4+
**Issue**: #44 (Phase 2 Consistency Fixes)
5+
**PR**: #49
6+
7+
## Executive Summary
8+
9+
During Phase 2 implementation, changes were made directly to `src/claude/` without also updating the shared templates in `templates/agents/`, causing agent drift and requiring rework.
10+
11+
## What Happened
12+
13+
1. Initial implementation modified only `src/claude/` files:
14+
- `src/claude/critic.md` - Added escalation template
15+
- `src/claude/task-generator.md` - Added estimate reconciliation protocol
16+
- `src/claude/planner.md` - Added condition traceability
17+
18+
2. These changes were NOT made to the shared source files in `templates/agents/`:
19+
- `templates/agents/critic.shared.md`
20+
- `templates/agents/task-generator.shared.md`
21+
- `templates/agents/planner.shared.md`
22+
23+
3. This caused the generated agents (`src/copilot-cli/`, `src/vs-code-agents/`) to drift from the manually-edited `src/claude/` files
24+
25+
## Root Cause
26+
27+
**Incomplete understanding of agent generation workflow**:
28+
- The repository uses a generation pattern: `templates/agents/*.shared.md` → `Generate-Agents.ps1` → `src/copilot-cli/`, `src/vs-code-agents/`
29+
- `src/claude/` appears to be a separate, manually-maintained platform (uses different frontmatter and "Claude Code Tools" section)
30+
- Future agents should understand this tri-platform structure
31+
32+
## Correct Workflow
33+
34+
When modifying agent behavior:
35+
36+
1. **Update shared template first**: Edit `templates/agents/[agent].shared.md`
37+
2. **Run generator**: `pwsh build/Generate-Agents.ps1`
38+
3. **Update src/claude if needed**: This platform has additional content not in shared templates
39+
4. **Verify all platforms**: Check `src/copilot-cli/`, `src/vs-code-agents/`, `src/claude/`
40+
5. **Commit all changes**: Include templates, generated files, and src/claude
41+
42+
## Skills Extracted
43+
44+
### Skill-AgentWorkflow-001
45+
**Statement**: When modifying agent behavior, update `templates/agents/*.shared.md` FIRST, then run `Generate-Agents.ps1`
46+
**Evidence**: Phase 2 changes to src/claude/ required rework to sync with templates
47+
**Pattern**: Generator-based workflow
48+
49+
### Skill-AgentWorkflow-002
50+
**Statement**: `src/claude/` is a separate platform with additional content (Claude Code Tools section) not in shared templates
51+
**Evidence**: Comparison shows Claude agents have extra "Claude Code Tools" section
52+
**Pattern**: Tri-platform structure (Claude, VS Code, Copilot CLI)
53+
54+
### Skill-AgentWorkflow-003
55+
**Statement**: Always verify agent changes appear in all three platform directories after generation
56+
**Evidence**: Changes to templates propagate to generated agents but not to src/claude
57+
**Pattern**: Manual + generated content coexistence
58+
59+
## Recommendations for Future Agents
60+
61+
1. Before making agent changes, run `pwsh build/Generate-Agents.ps1 -Validate` to check for drift
62+
2. Follow the workflow: templates → generate → verify → claude manual update if needed
63+
3. Include all generated files in commits
64+
4. Leave handoff artifacts documenting what was changed and why
65+
66+
## Files Modified in Correction
67+
68+
### Shared Templates
69+
- `templates/agents/critic.shared.md` - Added Escalation Prompt Completeness Requirements
70+
- `templates/agents/task-generator.shared.md` - Added Estimate Reconciliation Protocol
71+
- `templates/agents/planner.shared.md` - Added Condition-to-Task Traceability
72+
73+
### Generated Agents (via Generate-Agents.ps1)
74+
- `src/copilot-cli/critic.agent.md`
75+
- `src/copilot-cli/task-generator.agent.md`
76+
- `src/copilot-cli/planner.agent.md`
77+
- `src/vs-code-agents/critic.agent.md`
78+
- `src/vs-code-agents/task-generator.agent.md`
79+
- `src/vs-code-agents/planner.agent.md`
80+
81+
### Previously Modified (from original Phase 2)
82+
- `src/claude/critic.md`
83+
- `src/claude/task-generator.md`
84+
- `src/claude/planner.md`
85+
86+
## Validation Script Created
87+
88+
- `build/scripts/Validate-PlanningArtifacts.ps1` - Cross-document consistency validation
89+
- `build/scripts/tests/Validate-PlanningArtifacts.Tests.ps1` - 17 Pester tests

‎.agents/skills/agent-generation-workflow.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Skill: Agent Generation Workflow
2+
3+
**Skill ID**: Skill-AgentWorkflow-001
4+
**Category**: Infrastructure
5+
**Discovered**: 2025-12-16
6+
**Source**: PR #49 - Phase 2 CodeRabbit Remediation
7+
8+
## Skill Statement
9+
10+
When modifying agent behavior in this repository, always update the shared templates in `templates/agents/*.shared.md` FIRST, then run `pwsh build/Generate-Agents.ps1` to regenerate platform-specific agents.
11+
12+
## Pattern
13+
14+
```
15+
1. Edit templates/agents/[agent].shared.md
16+
2. Run: pwsh build/Generate-Agents.ps1
17+
3. Verify: Check src/copilot-cli/, src/vs-code-agents/
18+
4. If needed: Manually update src/claude/ (separate platform)
19+
5. Commit all changes together
20+
```
21+
22+
## Evidence
23+
24+
Phase 2 changes were initially made only to `src/claude/` files. This caused drift between the manually-edited Claude agents and the generated agents (copilot-cli, vs-code-agents). Rework was required to sync templates and regenerate.
25+
26+
## Related Skills
27+
28+
- **Skill-AgentWorkflow-002**: `src/claude/` is a separate platform with additional content (Claude Code Tools section) not in shared templates
29+
- **Skill-AgentWorkflow-003**: Always verify agent changes appear in all three platform directories after generation
30+
31+
## Validation Commands
32+
33+
```bash
34+
# Check for drift before making changes
35+
pwsh build/Generate-Agents.ps1 -Validate
36+
37+
# Regenerate all agents
38+
pwsh build/Generate-Agents.ps1
39+
40+
# Preview what would be generated
41+
pwsh build/Generate-Agents.ps1 -WhatIf
42+
```
43+
44+
## Anti-Pattern
45+
46+
❌ **Do NOT** edit `src/copilot-cli/` or `src/vs-code-agents/` directly - these are generated files
47+
48+
❌ **Do NOT** assume `src/claude/` will be updated by the generator - it's manually maintained
49+
50+
## Correct Pattern
51+
52+
✅ Edit `templates/agents/*.shared.md`
53+
✅ Run `Generate-Agents.ps1`
54+
✅ Update `src/claude/` manually if needed
55+
✅ Commit all changes together

‎src/copilot-cli/critic.agent.md‎

Lines changed: 65 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,10 +141,74 @@ If specialists do NOT have unanimous agreement:
141141

142142
1. **Document the conflict** in the critique clearly
143143
2. **Assess severity**: Minor (proceed with note) vs. Major (requires resolution)
144-
3. **For major conflicts**: MUST escalate to **high-level-advisor**
144+
3. **For major conflicts**: MUST escalate to **high-level-advisor** with full context:
145+
146+
```markdown
147+
## ESCALATION REQUIRED
148+
149+
**Conflicting Agents**: [Agent A] vs [Agent B]
150+
**Issue**: [Specific technical disagreement]
151+
152+
### Verified Facts (exact values, not summaries)
153+
154+
| Fact | Value | Source |
155+
|------|-------|--------|
156+
| [Data point] | [Exact value] | [Where verified] |
157+
158+
### Numeric Data
159+
160+
- [All percentages, hours, counts from analysis]
161+
162+
### Agent A Position
163+
- **Recommendation**: [Exact recommendation]
164+
- **Evidence**: [Specific facts, metrics, code references]
165+
- **Risk if ignored**: [Quantified impact]
166+
167+
### Agent B Position
168+
- **Recommendation**: [Exact recommendation]
169+
- **Evidence**: [Specific facts, metrics, code references]
170+
- **Risk if ignored**: [Quantified impact]
171+
172+
### Decision Questions
173+
174+
1. [Specific question requiring resolution]
175+
176+
**Recommendation**: Route to high-level-advisor for resolution
177+
```
178+
145179
4. **Block approval** until high-level-advisor provides guidance
146180
5. **Document resolution** in critique for retrospective learning
147181

182+
## Escalation Prompt Completeness Requirements
183+
184+
When escalating to high-level-advisor, ENSURE all verified facts are preserved with exact values.
185+
186+
### Mandatory Escalation Data
187+
188+
All escalation prompts MUST include:
189+
190+
1. **Verified Facts Table**: Exact values, not ranges or summaries
191+
2. **Numeric Data**: All percentages, hours, counts - preserve original precision
192+
3. **Conflicting Positions**: Each agent's position with rationale
193+
4. **Decision Questions**: Specific questions requiring resolution
194+
195+
### Anti-Pattern: Information Loss During Synthesis
196+
197+
**Anti-Pattern**: Converting "99%+ overlap (VS Code/Copilot), 60-70% (Claude)" to "80-90% overlap" loses actionable detail.
198+
199+
**Correct Approach**: Preserve all exact values in escalation:
200+
201+
```markdown
202+
| Fact | Value | Source |
203+
|------|-------|--------|
204+
| VS Code/Copilot overlap | 99%+ | Template analysis |
205+
| Claude overlap | 60-70% | Template analysis |
206+
```
207+
208+
**Why This Matters**: High-level-advisor cannot make informed decisions without precise data. Summarizing away detail forces decisions based on incomplete information.
209+
210+
### Conflict Categories
211+
148212
| Conflict Type | Example | Resolution Owner |
149213
|--------------|---------|------------------|
150214
| Security vs. Usability | Auth complexity vs. user experience | high-level-advisor |

‎src/copilot-cli/planner.agent.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -358,6 +358,61 @@ During impact analysis, specialists may have **conflicting recommendations**. Th
358358

359359
**Note**: The **critic** agent is responsible for escalating major conflicts to **high-level-advisor**. Unanimous specialist agreement is required for smooth approval.
360360

361+
## Condition-to-Task Traceability
362+
363+
When aggregating specialist reviews, ENSURE all conditions from specialist reviews are linked to specific task IDs.
364+
365+
### Traceability Requirement
366+
367+
> Every condition from specialist reviews MUST have a corresponding task assignment in the Work Breakdown.
368+
369+
### Work Breakdown Template with Conditions
370+
371+
When creating work breakdowns, include a Conditions column to trace specialist requirements:
372+
373+
```markdown
374+
| Task ID | Description | Effort | Conditions |
375+
|---------|-------------|--------|------------|
376+
| TASK-001 | Implement base auth service | 2h | None |
377+
| TASK-002 | Add OAuth2 integration | 3h | Security: Use PKCE flow |
378+
| TASK-003 | Create login form | 1.5h | QA: Requires test spec file path |
379+
| TASK-004 | Add error handling | 1h | None |
380+
| TASK-005 | Write integration tests | 2h | QA: Increase effort to 2h |
381+
```
382+
383+
### Validation Checklist
384+
385+
Before finalizing any plan with specialist conditions:
386+
387+
- [ ] Every specialist condition has a task assignment
388+
- [ ] Work Breakdown table reflects all conditions
389+
- [ ] No orphan conditions (conditions without task links)
390+
- [ ] Conditions column specifies source agent (e.g., "QA:", "Security:")
391+
392+
### Anti-Pattern: Orphan Conditions
393+
394+
**Anti-Pattern**: Putting conditions in a separate section without cross-references to tasks causes implementation gaps.
395+
396+
```markdown
397+
## Conditions (INCORRECT)
398+
- QA: Needs test specification file
399+
- Security: Use PKCE for OAuth
400+
401+
## Work Breakdown (INCORRECT - no condition links)
402+
| Task ID | Description | Effort |
403+
|---------|-------------|--------|
404+
| TASK-001 | Implement OAuth | 3h |
405+
```
406+
407+
**Correct Approach**: Link conditions directly to tasks:
408+
409+
```markdown
410+
| Task ID | Description | Effort | Conditions |
411+
|---------|-------------|--------|------------|
412+
| TASK-001 | Implement OAuth | 3h | Security: Use PKCE flow |
413+
| TASK-002 | Create test specs | 1h | QA: Needs test specification file |
414+
```
415+
361416
## Planning Principles
362417

363418
- **Incremental**: Deliver value at each milestone

0 commit comments

Comments
 (0)