memory-journal-mcp 7.7.1 → 8.0.0

package/skills/adversarial-performance/references/feedback-loop.md

@@ -0,0 +1,177 @@
+# Feedback Loop & Documentation
+
+Reference for journaling, cross-session learning, and retrospective patterns
+used throughout the adversarial performance protocol.
+
+## Journal Entry Templates
+
+Each phase creates a journal entry using `create_entry`. The structured
+entry types and tags enable precise retrieval and performance trend tracking
+across releases.
+
+### Phase 1 — Profiling
+
+```
+create_entry({
+  content: "# Performance Profile: [Repository Name]\n\n[full profiling content with baselines]",
+  entry_type: "perf_profile",
+  tags: ["adversarial-performance", "profile"],
+  project_number: <project number>
+})
+```
+
+### Phase 2 — Stress Test Review
+
+```
+create_entry({
+  content: "# Stress Test Review: [Repository Name]\n\nOverall Score: X/5.0 — Grade Y\n\n[findings table and scores]",
+  entry_type: "perf_stress_test",
+  tags: ["adversarial-performance", "stress-test"],
+  project_number: <project number>
+})
+```
+
+### Phase 3 — Optimization Plan
+
+```
+create_entry({
+  content: "# Optimization Plan: [Repository Name]\n\n[disposition table + projected improvements]",
+  entry_type: "perf_optimization",
+  tags: ["adversarial-performance", "optimization"],
+  project_number: <project number>
+})
+```
+
+### Phase 4 — Copilot Validation
+
+```
+create_entry({
+  content: "# Copilot Performance Validation: [Repository Name]\n\n[copilot findings + final dispositions]",
+  entry_type: "perf_copilot",
+  tags: ["adversarial-performance", "copilot"],
+  project_number: <project number>
+})
+```
+
+### Final Summary
+
+```
+create_entry({
+  content: "# Performance Audit Complete: [Repository Name]\n\nScore: X/5.0 (Grade Y)\nCritical: N, High: N, Moderate: N, Low: N\n\n## Baselines\n- Build: Xs\n- Bundle: XMB\n- Dependencies: N direct / M transitive\n- Tests: Xs\n\n## Key Findings\n- [top 3 findings]\n\n## Projected Improvements\n- [accepted optimizations with estimates]",
+  entry_type: "perf_audit_complete",
+  tags: ["adversarial-performance", "audit-complete", "session-summary"],
+  project_number: <project number>
+})
+```
+
+## Linking Entries
+
+```
+link_entries({
+  from_entry_id: <stress_test_entry_id>,
+  to_entry_id: <profile_entry_id>,
+  relationship_type: "references",
+  description: "Stress test review of profiling baselines"
+})
+
+link_entries({
+  from_entry_id: <optimization_entry_id>,
+  to_entry_id: <stress_test_entry_id>,
+  relationship_type: "evolves_from",
+  description: "Optimization plan based on stress test findings"
+})
+
+link_entries({
+  from_entry_id: <implementation_entry_id>,
+  to_entry_id: <optimization_entry_id>,
+  relationship_type: "implements",
+  description: "Performance optimization implementation"
+})
+
+link_entries({
+  from_entry_id: <current_audit_id>,
+  to_entry_id: <prior_audit_id>,
+  relationship_type: "evolves_from",
+  description: "Follow-up audit tracking performance evolution"
+})
+```
+
+## Cross-Session Learning
+
+### Find Prior Audits
+
+```
+search_entries({
+  query: "<repository name>",
+  entry_type: "perf_profile",
+  tags: ["adversarial-performance"]
+})
+```
+
+### Track Performance Trends
+
+Compare baseline measurements across audits to detect regressions:
+
+```
+search_entries({
+  query: "<repository name> baseline",
+  entry_type: "perf_audit_complete",
+  tags: ["adversarial-performance", "audit-complete"]
+})
+```
+
+### Find Recurring Bottleneck Patterns
+
+```
+search_entries({
+  query: "<pattern, e.g., 'N+1 query'>",
+  entry_type: "perf_stress_test",
+  tags: ["adversarial-performance"]
+})
+```
+
+### Cross-Project Performance Patterns
+
+```
+get_cross_project_insights({
+  query: "performance bottleneck",
+  tags: ["adversarial-performance"]
+})
+```
+
+## Session Retrospective
+
+### Retrospective Template
+
+```
+create_entry({
+  content: "# Performance Audit Retrospective: [Repository Name]\n\n## Key Insights\n- [What the Profiler missed that the Stress Tester caught]\n- [What Copilot caught that internal review missed]\n- [Optimization patterns worth institutionalizing]\n- [Baselines that proved accurate vs. misleading]\n\n## Metrics\n- Initial performance score: X/5.0 (Grade Y)\n- Final performance score: X/5.0 (Grade Y)\n- Stress test passes: N\n- Critical findings: N (optimized: N, deferred: N)\n- Projected total improvement: [summary]\n\n## Baseline Comparison (vs. prior audit)\n- Build time: Xs → Ys (Δ Z%)\n- Bundle size: XMB → YMB (Δ Z%)\n- Test duration: Xs → Ys (Δ Z%)\n\n## Process Improvements\n- [Categories to emphasize next time]\n- [New measurement methods to add]",
+  entry_type: "retrospective",
+  tags: ["adversarial-performance", "retrospective", "session-summary"],
+  project_number: <project number>
+})
+```
+
+## Tag Convention
+
+| Tag                       | Purpose                                        |
+| ------------------------- | ---------------------------------------------- |
+| `adversarial-performance` | All entries from this skill (primary filter)   |
+| `profile`                 | Phase 1 output                                 |
+| `stress-test`             | Phase 2 output                                 |
+| `optimization`            | Phase 3 output                                 |
+| `copilot`                 | Phase 4 output                                 |
+| `audit-complete`          | Final consolidated summary                     |
+| `retrospective`           | Post-cycle review                              |
+| `session-summary`         | Enables retrieval via session summary searches |
+
+## Entry Type Reference
+
+| Entry Type            | Phase | Description                          |
+| --------------------- | ----- | ------------------------------------ |
+| `perf_profile`        | 1     | Baselines and existing optimizations |
+| `perf_stress_test`    | 2     | Stress test findings with scores     |
+| `perf_optimization`   | 3     | Optimization plan with dispositions  |
+| `perf_copilot`        | 4     | Copilot validation findings          |
+| `perf_audit_complete` | Final | Consolidated audit summary           |
+| `retrospective`       | Post  | Session retrospective with metrics   |

package/skills/adversarial-performance/references/multi-pass-performance-protocol.md

@@ -0,0 +1,398 @@
+# Multi-Pass Performance Protocol
+
+Detailed reference for the 4-phase adversarial performance audit workflow.
+Read this when executing the protocol for the full review dimensions, scoring
+system, and output templates.
+
+## Phase 1 — Profiling (Agent A: Profiler)
+
+### Inputs
+
+Before starting the profiling pass, gather context from these sources:
+
+1. **Repository structure** — build tooling (tsc, tsup, esbuild, webpack,
+   vite), test framework, output directory, entry points
+2. **Existing performance documentation** — READMEs, benchmarks, prior audit
+   results
+3. **Prior audits** — search the journal for related performance entries:
+   ```
+   search_entries({
+     query: "<repository name> performance",
+     entry_type: "perf_profile",
+     tags: ["adversarial-performance"]
+   })
+   ```
+4. **Dependency manifest** — `package.json` (dependency count, scripts),
+   `package-lock.json` (transitive depth)
+5. **Project profile** — auto-detect or use the explicit `PROJECT_PROFILE`
+   setting (see SKILL.md § Auto-Detection)
+
+### Measurement Methods
+
+If `RUN_COMMANDS` is `true`, execute these measurement commands. Otherwise,
+perform static analysis only and note measurements as "estimated" rather than
+"measured."
+
+| Category     | Command                                   | What It Measures                   |
+| ------------ | ----------------------------------------- | ---------------------------------- |
+| Build        | `npx tsc --noEmit --diagnostics`          | Compile time, file count, memory   |
+| Build        | `npm run build`                           | Bundle time, output size, warnings |
+| Bundle       | `du -sh dist/` (or PowerShell equivalent) | Total output size                  |
+| Dependencies | `npm ls --all --prod 2>$null`             | Dependency tree depth              |
+| Tests        | `npm test -- --reporter=verbose`          | Suite duration, slow tests         |
+
+### Profiling Structure
+
+Produce a Markdown document with these sections:
+
+```markdown
+# Performance Profile — [Repository Name]
+
+## Project Profile
+
+- **Type**: [auto-detected: mcp-server, web-app, cli-tool, library]
+- **Profiles**: [stacked: mcp-server + cli-tool + tested + containerized]
+- **Language/Runtime**: [e.g., TypeScript/Node.js 24]
+- **Build Tool**: [e.g., tsup, tsc, esbuild]
+- **Test Framework**: [e.g., Vitest, Playwright]
+- **Source Files**: [count]
+- **Dependencies**: [direct count / transitive count]
+
+## Baseline Measurements
+
+| Metric                  | Value                   | Method            |
+| ----------------------- | ----------------------- | ----------------- |
+| TypeScript compile time | Xs                      | tsc --diagnostics |
+| Bundle build time       | Xs                      | npm run build     |
+| Output size (dist/)     | X KB/MB                 | file system       |
+| Production dependencies | N direct / M transitive | npm ls            |
+| Test suite duration     | Xs                      | npm test          |
+| [etc.]                  |                         |                   |
+
+## Category Assessment (per Category)
+
+For each of the 7 audit categories (see audit-categories.md):
+
+- Current state and measurements
+- Existing optimizations in place
+- Initial efficiency rating: excellent / good / acceptable / poor
+
+## Hot Path Map
+
+Identify the performance-critical code paths:
+
+- Request handling pipeline (for servers)
+- Database query paths (for data-layer projects)
+- Build/compile pipeline
+- Test execution pipeline
+- Startup sequence
+
+## Optimization Opportunities (Preliminary)
+
+Initial hypotheses about where the biggest gains are. These are
+preliminary — Agent B will validate or refute them with stress scenarios.
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full profiling output>",
+  entry_type: "perf_profile",
+  tags: ["adversarial-performance", "profile"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 2 — Stress Test Review (Agent B: Stress Tester)
+
+Switch mental models. You are now a performance skeptic whose job is to find
+every bottleneck the Profiler missed or underestimated. Don't trust the
+baselines — probe their limits.
+
+### Review Dimensions
+
+Score each dimension on a 1–5 scale. Dimensions have different weights
+reflecting their relative importance for performance:
+
+| Dimension           | Weight | Focus Areas                                                                                                    |
+| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
+| **Impact**          | 4      | User-facing latency, throughput degradation, memory pressure, token waste. How much does this actually matter? |
+| **Frequency**       | 3      | How often does this hot path execute? Every request? Once at startup? Rare edge case?                          |
+| **Effort**          | 2      | How hard is the fix? Quick config change vs. architectural refactor?                                           |
+| **Regression Risk** | 1      | Could the optimization break existing behavior or introduce bugs?                                              |
+
+### Severity Mapping
+
+| Weighted Score | Severity | Meaning                                                 |
+| -------------- | -------- | ------------------------------------------------------- |
+| 4.0–5.0        | Critical | High-frequency bottleneck with major user-facing impact |
+| 3.0–3.9        | High     | Significant performance cost, noticeable in production  |
+| 2.0–2.9        | Moderate | Measurable inefficiency but limited blast radius        |
+| 1.0–1.9        | Low      | Optimization opportunity, defense-in-depth improvement  |
+
+### Depth Profiles
+
+The `AUDIT_DEPTH` configuration controls scrutiny level:
+
+- **Scan**: Categories 1 (Build), 3 (Dependencies), 4 (Runtime) only. Quick
+  bottleneck triage.
+- **Standard**: All 7 categories at stated weights. Default.
+- **Intensive**: All 7 categories + extended analysis:
+  - Big-O complexity analysis on identified hot paths
+  - Memory allocation pattern review (object churn in loops)
+  - Cold start vs. warm execution divergence
+  - Event loop blocking analysis (sync I/O, heavy computation)
+  - Concurrency ceiling estimation (worker pools, connection pools)
+  - Comparison against prior audit baselines (regression detection)
+
+### Critique Output Format
+
+```markdown
+## Stress Test Review — [Repository Name]
+
+**Overall Performance Score:** [weighted average] / 5.0
+**Performance Grade:** [A–F]
+
+### Grading Scale
+
+| Grade | Score Range | Meaning                                                  |
+| ----- | ----------- | -------------------------------------------------------- |
+| A     | 4.5–5.0     | Excellent — well-optimized, minimal waste                |
+| B     | 3.5–4.4     | Good — no critical bottlenecks, room for tuning          |
+| C     | 2.5–3.4     | Acceptable — measurable inefficiencies, worth addressing |
+| D     | 1.5–2.4     | Poor — significant bottlenecks impacting UX or cost      |
+| F     | 1.0–1.4     | Failing — severe performance issues, unusable at scale   |
+
+### Findings
+
+| #   | Category     | Severity | Finding                   | File:Line         | Impact             | Optimization                   |
+| --- | ------------ | -------- | ------------------------- | ----------------- | ------------------ | ------------------------------ |
+| 1   | Runtime      | Critical | N+1 query in list handler | src/foo.ts:42     | +200ms per request | Batch query with single SELECT |
+| 2   | Build        | High     | Dev deps in prod bundle   | tsup.config.ts:8  | +2MB output        | Add external[] config          |
+| 3   | Dependencies | Moderate | Duplicate lodash versions | package-lock.json | +400KB install     | npm dedupe                     |
+| ... |              |          |                           |                   |                    |                                |
+
+### Dimension Scores
+
+| Dimension       | Score | Weight | Weighted             |
+| --------------- | ----- | ------ | -------------------- |
+| Impact          | [1–5] | 4      | [score × 4]          |
+| Frequency       | [1–5] | 3      | [score × 3]          |
+| Effort          | [1–5] | 2      | [score × 2]          |
+| Regression Risk | [1–5] | 1      | [score × 1]          |
+| **Total**       |       | **10** | **[sum]/50 = [avg]** |
+
+### Category Breakdown
+
+| Category             | Findings | Worst Severity | Rating        |
+| -------------------- | -------- | -------------- | ------------- |
+| 1. Build Performance | 1        | High           | ⚠️ Needs work |
+| 2. Bundle & Output   | 0        | —              | ✅ Good       |
+| 3. Dependency Weight | 2        | Moderate       | ⚠️ Needs work |
+| ...                  |          |                |               |
+
+### Stress Scenarios
+
+For each critical/high finding, describe the stress scenario that reveals it:
+
+#### Scenario: [Finding Title]
+
+- **Trigger condition**: [What causes worst-case behavior]
+- **Scale factor**: [How performance degrades as N grows]
+- **Measured/estimated impact**: [Quantified: +Xms, +XMB, +X tokens]
+- **Breaking point**: [At what scale does this become unacceptable]
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full stress test critique>",
+  entry_type: "perf_stress_test",
+  tags: ["adversarial-performance", "stress-test"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 3 — Optimization Plan (Agent A: Profiler)
+
+Switch back to the Profiler role. Address every finding from the stress test
+review with an explicit disposition.
+
+### Disposition Table
+
+For each finding, record one of:
+
+| Disposition | Meaning                                                                                                   |
+| ----------- | --------------------------------------------------------------------------------------------------------- |
+| **Accept**  | Implement the suggested optimization                                                                      |
+| **Reject**  | Explain why the finding doesn't warrant optimization (acceptable cost, premature optimization, trade-off) |
+| **Modify**  | Accept the finding but implement a different optimization                                                 |
+| **Defer**   | Acknowledge the inefficiency but defer to a future milestone                                              |
+
+### Optimization Plan Output
+
+Produce the plan prioritized by impact × frequency (highest ROI first):
+
+```markdown
+## Optimization Plan — [Repository Name]
+
+### Disposition Summary
+
+| #   | Finding            | Severity | Disposition | Rationale                               |
+| --- | ------------------ | -------- | ----------- | --------------------------------------- |
+| 1   | N+1 query          | Critical | Accept      | Will batch into single SELECT           |
+| 2   | Dev deps in bundle | High     | Modify      | Using externals instead of tree-shaking |
+| 3   | Duplicate lodash   | Moderate | Defer       | Awaiting lodash-es migration in Q3      |
+
+### Quick Wins (< 1 hour, high impact)
+
+| #   | Finding | Optimization | Expected Improvement       |
+| --- | ------- | ------------ | -------------------------- |
+| ... | ...     | ...          | -Xms latency / -XMB bundle |
+
+### Targeted Improvements (1–4 hours)
+
+| #   | Finding | Optimization | Files Affected | Expected Improvement |
+| --- | ------- | ------------ | -------------- | -------------------- |
+| ... | ...     | ...          | ...            | ...                  |
+
+### Architectural Changes (requires design work)
+
+| #   | Finding | Approach | Effort | Expected Improvement |
+| --- | ------- | -------- | ------ | -------------------- |
+| ... | ...     | ...      | ...    | ...                  |
+
+### Accepted Trade-offs
+
+Findings explicitly rejected or deferred with justification:
+
+| #   | Finding | Disposition | Justification |
+| --- | ------- | ----------- | ------------- |
+| ... | ...     | ...         | ...           |
+
+### Projected Improvement
+
+| Metric                | Before | After (projected) | Improvement |
+| --------------------- | ------ | ----------------- | ----------- |
+| Build time            | Xs     | Xs                | -X%         |
+| Bundle size           | XMB    | XMB               | -X%         |
+| Request latency (p95) | Xms    | Xms               | -X%         |
+| Test suite duration   | Xs     | Xs                | -X%         |
+
+**Score**: Before [X]/5.0 (Grade [Y]) → After (projected) [X]/5.0 (Grade [Y])
+```
+
+### Iteration Control
+
+After optimization planning, check: has `MAX_AUDIT_PASSES` been reached?
+
+- **No** → return to Phase 2 for another stress test of the optimization
+  plan (do the fixes introduce new bottlenecks? Are there second-order
+  performance effects?)
+- **Yes** → proceed to Phase 4
+
+### Journal
+
+```
+create_entry({
+  content: "<optimization plan with dispositions>",
+  entry_type: "perf_optimization",
+  tags: ["adversarial-performance", "optimization"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 4 — Copilot Validation (External)
+
+If `COPILOT_VALIDATION` is enabled and the Copilot CLI is available, invoke
+it for an independent review.
+
+See [copilot-performance-prompts.md](copilot-performance-prompts.md) for
+prompt templates.
+
+After the Copilot pass, any new findings follow the same disposition process
+from Phase 3. The final audit report is then presented to the user.
+
+If Copilot CLI is not available, skip this phase gracefully:
+
+```markdown
+> **Phase 4 skipped**: Copilot CLI not available. The audit completed with
+> internal adversarial review only (Phases 1–3).
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<copilot findings + final dispositions>",
+  entry_type: "perf_copilot",
+  tags: ["adversarial-performance", "copilot"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Final Report Assembly
+
+After all phases complete, produce a consolidated report artifact:
+
+```markdown
+# Adversarial Performance Audit — [Repository Name]
+
+**Date**: [ISO date]
+**Audit Depth**: [scan | standard | intensive]
+**Project Profile**: [auto-detected profiles]
+**Passes Completed**: [N]
+**Copilot Validation**: [yes | skipped]
+**Commands Executed**: [yes | static analysis only]
+
+## Executive Summary
+
+[2–3 sentence summary: overall performance posture, critical bottleneck
+count, and top recommended optimization]
+
+**Performance Score**: [X] / 5.0 — Grade [A–F]
+
+## Baseline Measurements
+
+[Key metrics from Phase 1]
+
+## Findings Summary
+
+| Category             | Critical | High | Moderate | Low | Total |
+| -------------------- | -------- | ---- | -------- | --- | ----- |
+| 1. Build Performance | ...      |      |          |     |       |
+| ...                  |          |      |          |     |       |
+| **Total**            |          |      |          |     |       |
+
+## Top 3 Highest-Impact Optimizations
+
+1. [Most impactful finding + optimization + expected improvement]
+2. [Second most impactful]
+3. [Third most impactful]
+
+## Full Findings (by impact)
+
+[All findings from Phase 2, grouped by severity descending]
+
+## Optimization Plan
+
+[From Phase 3 — disposition table + quick wins + targeted + architectural]
+
+## Projected Improvement
+
+[Before/after metrics table]
+
+## Appendix: Profiling Data
+
+[Condensed Phase 1 output — measurements, hot path map]
+```

package/skills/adversarial-planner/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Multi-pass adversarial planning and review skill that improves agent-generated
   plans through structured critique stages. Combines an initial planning agent
   (structure, logic, task sequencing) with an adversarial review agent
-  (performance, security, maintainability) and a final Copilot CLI validation
+  (performance, security, maintainability) and a final Copilot extension validation
   pass. Use when creating implementation plans, designing architecture, planning
   roadmaps or milestones, or when the user says "plan this", "review my plan",
   "adversarial review", or "multi-pass plan".
@@ -26,64 +26,33 @@ Load this skill when any of these apply:
 - Designing multi-file refactors or system migrations
 - Planning project roadmaps, milestones, or sprint scopes
 - The user asks for an adversarial or multi-pass review of a plan
-- The user says "plan this", "review my plan", "critique this plan", or
-  "multi-pass plan"
+- The user says "plan this", "review my plan", "critique this plan",
+  "multi-pass plan", "architect this", "design this system", or "how should I build"
 - You want to reduce confirmation bias in your own planning output
 
-## Agent Roles
+## Adversarial Protocol
 
-This skill operates with two distinct mental models. You are both agents — you
-switch perspectives at phase boundaries.
+This skill follows the standard dual-agent adversarial pattern (Agent A: The Planner, Agent B: The Adversarial Reviewer).
+For the core pipeline rules, phase definitions, and agent switching protocols, read:
+**[../adversarial-security/references/adversarial-base-protocol.md](../adversarial-security/references/adversarial-base-protocol.md)**
 
-### Agent A — The Planner
+For the planner-specific protocol with review dimensions, scoring weights, and output templates, read:
+**[references/multi-pass-protocol.md](references/multi-pass-protocol.md)**
 
-**Mandate:** Produce a comprehensive, well-structured plan.
+## External Validation (Phase 4)
 
-- Gather requirements from user request, code context, and prior work
-- Structure the plan with clear scope, file changes, task ordering, and risk
-  assessment
-- Optimize for completeness and logical sequencing
-- Reference prior planning sessions via journal search before starting
-
-### Agent B — The Adversarial Reviewer
-
-**Mandate:** Find every weakness the Planner missed.
-
-- Switch to a skeptical senior reviewer mindset
-- Challenge assumptions, flag gaps, and identify risks
-- Score findings across weighted review dimensions (see protocol reference)
-- Provide concrete, actionable remediation suggestions — not vague concerns
-
-The reason for explicit role separation is that it counteracts the natural
-tendency to defend your own output. By formally switching perspective, you
-engage different evaluation criteria than the ones that guided the draft.
-
-## The Multi-Pass Protocol
-
-The protocol runs in 4 phases. Each phase produces a journaled artifact.
-
-| Phase                 | Agent        | Output                                 | Entry Type           | Tags                                |
-| --------------------- | ------------ | -------------------------------------- | -------------------- | ----------------------------------- |
-| 1. Plan Draft         | A (Planner)  | Structured plan document               | `plan_draft`         | `adversarial-planner`, `plan-draft` |
-| 2. Adversarial Review | B (Reviewer) | Critique table with severity ratings   | `adversarial_review` | `adversarial-planner`, `review`     |
-| 3. Plan Refinement    | A (Planner)  | Refined plan with disposition notes    | `plan_refinement`    | `adversarial-planner`, `refinement` |
-| 4. Copilot Validation | External     | Independent architecture/security pass | `copilot_validation` | `adversarial-planner`, `copilot`    |
-
-For the full protocol with review dimensions, scoring weights, and output
-templates, read [references/multi-pass-protocol.md](references/multi-pass-protocol.md).
-
-## Copilot Integration
-
-Phase 4 triggers an independent validation pass using the GitHub Copilot CLI.
-This provides a fundamentally different model's perspective on the plan,
+Phase 4 triggers an independent validation pass using the GitHub CLI (`gh copilot`).
+The `copilot` subcommand is built into modern `gh` CLI — no separate extension is
+needed. This provides a fundamentally different model's perspective on the plan,
 reducing confirmation bias that persists even after adversarial self-review.
 
 For Copilot-specific prompt templates and integration details, read
 [references/copilot-integration.md](references/copilot-integration.md).
 
-**Prerequisites:** The `github-copilot-cli` skill must be available for CLI
-setup and authentication. The `copilot-audit` workflow in `github-commander`
-handles full repo audits — this skill focuses on plan-specific review.
+**Prerequisites:** `gh` CLI v2.x+ with `gh auth status` passing. If `gh copilot`
+is not available, skip Phase 4 gracefully and note the skip in the journal entry.
+
+Read [references/copilot-usage.md](references/copilot-usage.md) for critical non-interactive execution requirements.
 
 ## Feedback Loop & Documentation
 
@@ -96,11 +65,11 @@ retrospective templates, read
 
 ## Configuration
 
-| Variable             | Default    | Description                                     |
-| -------------------- | ---------- | ----------------------------------------------- |
-| `MAX_PLAN_PASSES`    | `2`        | Maximum refinement cycles (phases 2–3 repeat)   |
-| `PLAN_REVIEW_DEPTH`  | `standard` | Review depth: `light`, `standard`, or `deep`    |
-| `COPILOT_VALIDATION` | `true`     | Enable/disable the Copilot CLI validation phase |
+| Variable             | Default    | Description                                           |
+| -------------------- | ---------- | ----------------------------------------------------- |
+| `MAX_PLAN_PASSES`    | `2`        | Maximum refinement cycles (phases 2–3 repeat)         |
+| `PLAN_REVIEW_DEPTH`  | `standard` | Review depth: `light`, `standard`, or `deep`          |
+| `COPILOT_VALIDATION` | `true`     | Enable/disable the Copilot extension validation phase |
 
 ### Review Depth Profiles
 
@@ -115,6 +84,6 @@ retrospective templates, read
 | Skill/Workflow                   | Relationship                                                                                                                                          |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `autonomous-dev`                 | The Generator/Evaluator pipeline in `autonomous-dev` applies at the code level; this skill applies the same adversarial pattern at the planning level |
-| `github-copilot-cli`             | Provides the CLI setup and auth required for Phase 4                                                                                                  |
+| GitHub CLI (`gh copilot`)        | Built-in `copilot` subcommand used for Phase 4 external validation                                                                                    |
 | `github-commander/copilot-audit` | Full repo/PR audit; this skill uses Copilot for plan-specific review instead                                                                          |
 | `skill-builder`                  | Use to refine this skill's instructions based on observed agent behavior                                                                              |