memory-journal-mcp 7.7.0 → 8.0.0

package/skills/adversarial-skill-audit/references/multi-pass-skill-protocol.md

@@ -0,0 +1,367 @@
+# Multi-Pass Skill Audit Protocol
+
+Detailed reference for the 4-phase adversarial skill quality audit. Read
+this for the full review dimensions, scoring system, and output templates.
+
+## Phase 1 — Inventory & Profiling (Agent A: Evaluator)
+
+### Inputs
+
+Before starting, gather context:
+
+1. **Skills directory listing** — enumerate all skill directories
+2. **`skill-builder` standards** — read `skill-builder/SKILL.md` and
+   `skill-builder/checklist.md` to calibrate quality expectations
+3. **Prior audits** — search the journal:
+   ```
+   search_entries({
+     query: "skill audit",
+     entry_type: "skill_audit_profile",
+     tags: ["adversarial-skill-audit"]
+   })
+   ```
+4. **README & Package inventory** — check if `README.md` lists all skills,
+   if `package.json` includes them in `files`, and whether they are current
+
+### Per-Skill Scorecard
+
+For each skill, produce a scorecard:
+
+```markdown
+### [skill-name]
+
+**Files**: SKILL.md (X lines, Y KB) + N reference files
+**Description**: [first 100 chars of description]
+
+| Category                              | Score (1–5) | Notes |
+| ------------------------------------- | ----------- | ----- |
+| 1. Frontmatter & Triggering           |             |       |
+| 2. Instruction Clarity                |             |       |
+| 3. Structure & Progressive Disclosure |             |       |
+| 4. Output Formats                     |             |       |
+| 5. Edge Cases & Errors                |             |       |
+| 6. Security & Safety                  |             |       |
+| 7. Token Efficiency                   |             |       |
+| 8. Maintenance                        |             |       |
+| **Average**                           | **X.X**     |       |
+
+**Top Issue**: [Single most impactful improvement]
+**Grade**: [A–F]
+```
+
+### Scoring Guide
+
+| Score | Meaning                                                  |
+| ----- | -------------------------------------------------------- |
+| 5     | Excellent — meets or exceeds all skill-builder standards |
+| 4     | Good — minor gaps, functional as-is                      |
+| 3     | Acceptable — noticeable issues but usable                |
+| 2     | Poor — significant gaps affecting agent behavior         |
+| 1     | Failing — broken, misleading, or unusable                |
+
+### Directory-Level Assessment
+
+After scoring all skills individually, produce a directory-level overview:
+
+```markdown
+## Directory Overview
+
+**Total Skills**: N
+**Average Quality Score**: X.X / 5.0
+**Grade Distribution**: A: N, B: N, C: N, D: N, F: N
+
+### Score Distribution
+
+| Grade       | Skills           |
+| ----------- | ---------------- |
+| A (4.5–5.0) | skill-a, skill-b |
+| B (3.5–4.4) | skill-c, skill-d |
+| C (2.5–3.4) | skill-e          |
+| D (1.5–2.4) | skill-f          |
+| F (1.0–1.4) | —                |
+
+### Cross-Skill Properties
+
+- **Potential overlaps**: [skills that cover similar domains]
+- **Coverage gaps**: [domains with no skill coverage]
+- **Consistency issues**: [naming conventions, structure differences]
+- **Inventory accuracy**: [is the README table and package.json current?]
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full inventory with all scorecards>",
+  entry_type: "skill_audit_profile",
+  tags: ["adversarial-skill-audit", "profile"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 2 — Adversarial User Review (Agent B: Adversarial User)
+
+Switch mental models. You are now a user who types imprecise, ambiguous
+prompts. Your job is to find where the skills fail — wrong skill triggers,
+no skill triggers, confusing output, or dangerous behavior.
+
+### Review Dimensions
+
+Score each dimension on a 1–5 scale:
+
+| Dimension                | Weight | Focus Areas                                                                                                      |
+| ------------------------ | ------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Trigger Reliability**  | 4      | Does the skill load when it should? Does it avoid loading when it shouldn't? Are trigger keywords comprehensive? |
+| **Instruction Fidelity** | 3      | Will an agent actually follow these instructions correctly? Are there ambiguous steps that invite hallucination? |
+| **Failure Graceful**     | 2      | What happens when prerequisites are missing, inputs are weird, or the project doesn't match assumptions?         |
+| **Token ROI**            | 1      | Is the token cost justified by the value provided? Could the same effect be achieved with fewer tokens?          |
+
+### Trigger Testing
+
+For each skill, construct 3 test prompts:
+
+1. **Direct trigger** — a prompt that obviously should load this skill
+2. **Oblique trigger** — a prompt that should load this skill but uses
+   different phrasing than the description
+3. **Anti-trigger** — a prompt that sounds related but should NOT load
+   this skill
+
+Evaluate each:
+
+```markdown
+### Trigger Test: [skill-name]
+
+| #   | Prompt                     | Should Trigger? | Would It? | Confidence                  |
+| --- | -------------------------- | --------------- | --------- | --------------------------- |
+| 1   | "Build an MCP server"      | Yes             | Yes       | High                        |
+| 2   | "Connect my API to Claude" | Yes             | Maybe     | Medium                      |
+| 3   | "Write a REST API"         | No              | Maybe     | Low — description too broad |
+```
+
+### Trigger Collision Map
+
+Identify prompts where multiple skills would compete to load:
+
+```markdown
+### Trigger Collisions
+
+| Prompt                 | Competing Skills                           | Winner  | Issue                 |
+| ---------------------- | ------------------------------------------ | ------- | --------------------- |
+| "Set up CI/CD"         | github-actions, docker, cloudflare         | Unclear | All three claim CI/CD |
+| "Deploy to production" | cloudflare, docker, workers-best-practices | Unclear | Ambiguous platform    |
+```
+
+### Instruction Stress Tests
+
+For each skill, identify instructions that an agent might:
+
+- **Misinterpret** — ambiguous phrasing that could lead to wrong behavior
+- **Skip** — low-priority-sounding steps that are actually critical
+- **Over-execute** — instructions that could cause an agent to do too much
+- **Hallucinate from** — vague instructions that invite fabrication
+
+```markdown
+### Instruction Issues: [skill-name]
+
+| Line/Section             | Issue                  | Type          | Example Failure                 |
+| ------------------------ | ---------------------- | ------------- | ------------------------------- |
+| "Consider using caching" | Vague — agent may skip | Skip risk     | Agent ignores caching entirely  |
+| "Set up the project"     | No specifics           | Hallucination | Agent invents project structure |
+```
+
+### Critique Output Format
+
+```markdown
+## Adversarial User Review — [Skills Directory]
+
+**Overall Quality Score:** [weighted average] / 5.0
+**Directory Grade:** [A–F]
+
+### Findings
+
+| #   | Skill         | Category   | Severity | Finding                           | Remediation                        |
+| --- | ------------- | ---------- | -------- | --------------------------------- | ---------------------------------- |
+| 1   | mcp-builder   | Triggering | High     | "Connect AI to API" won't trigger | Add to description keywords        |
+| 2   | docker        | Clarity    | Medium   | "Set up multi-stage" is ambiguous | Add concrete Dockerfile template   |
+| 3   | — (directory) | Collision  | High     | 3 skills fight over "deploy"      | Add disambiguation in descriptions |
+
+### Dimension Scores
+
+| Dimension            | Score | Weight | Weighted             |
+| -------------------- | ----- | ------ | -------------------- |
+| Trigger Reliability  | [1–5] | 4      | [score × 4]          |
+| Instruction Fidelity | [1–5] | 3      | [score × 3]          |
+| Failure Graceful     | [1–5] | 2      | [score × 2]          |
+| Token ROI            | [1–5] | 1      | [score × 1]          |
+| **Total**            |       | **10** | **[sum]/50 = [avg]** |
+
+### Blocking Issues
+
+Skills that are actively harmful, misleading, or security-risk.
+```
+
+### Journal
+
+```
+create_entry({
+  content: "<full adversarial review>",
+  entry_type: "skill_audit_stress",
+  tags: ["adversarial-skill-audit", "stress-test"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 3 — Improvement Plan (Agent A: Evaluator)
+
+Switch back to the Evaluator. Address every finding with a disposition.
+
+### Disposition Table
+
+| Disposition | Meaning                                           |
+| ----------- | ------------------------------------------------- |
+| **Accept**  | Implement the improvement                         |
+| **Reject**  | Finding doesn't apply or trade-off isn't worth it |
+| **Modify**  | Accept the spirit but implement differently       |
+| **Defer**   | Acknowledge but defer (document why)              |
+
+### Improvement Plan Output
+
+```markdown
+## Improvement Plan — [Skills Directory]
+
+### Disposition Summary
+
+| #   | Skill         | Finding                       | Disposition | Rationale                        |
+| --- | ------------- | ----------------------------- | ----------- | -------------------------------- |
+| 1   | mcp-builder   | Missing trigger keywords      | Accept      | Add 5 alternative phrasings      |
+| 2   | docker        | Ambiguous instruction         | Modify      | Add example instead of rewriting |
+| 3   | — (directory) | Trigger collision on "deploy" | Accept      | Add "NOT for..." clauses         |
+
+### Priority 1 — Quick Wins (per skill)
+
+| Skill | Fix | Effort  |
+| ----- | --- | ------- |
+| ...   | ... | <15 min |
+
+### Priority 2 — Structural Improvements
+
+| Skill | Fix | Effort    |
+| ----- | --- | --------- |
+| ...   | ... | 30–60 min |
+
+### Priority 3 — New Skills Needed
+
+| Gap | Suggested Skill | Rationale |
+| --- | --------------- | --------- |
+| ... | ...             | ...       |
+
+### Skills to Deprecate or Merge
+
+| Skill | Action       | Rationale          |
+| ----- | ------------ | ------------------ |
+| ...   | Merge into X | 90% overlap with X |
+
+### Projected Quality Improvement
+
+| Metric             | Before | After |
+| ------------------ | ------ | ----- |
+| Average score      | X.X    | X.X   |
+| Skills graded A/B  | N/M    | N/M   |
+| Trigger collisions | N      | N     |
+| Coverage gaps      | N      | N     |
+```
+
+### Iteration Control
+
+Check: has `MAX_AUDIT_PASSES` been reached?
+
+- **No** → return to Phase 2 (stress-test the improvement plan itself)
+- **Yes** → proceed to Phase 4
+
+### Journal
+
+```
+create_entry({
+  content: "<improvement plan with dispositions>",
+  entry_type: "skill_audit_remediation",
+  tags: ["adversarial-skill-audit", "remediation"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Phase 4 — Copilot Validation (External)
+
+If available, invoke Copilot CLI. See
+[copilot-skill-prompts.md](copilot-skill-prompts.md).
+
+If unavailable, skip gracefully.
+
+### Journal
+
+```
+create_entry({
+  content: "<copilot findings + final dispositions>",
+  entry_type: "skill_audit_copilot",
+  tags: ["adversarial-skill-audit", "copilot"],
+  project_number: <project number>
+})
+```
+
+---
+
+## Final Report Assembly
+
+```markdown
+# Adversarial Skill Audit — [Skills Directory]
+
+**Date**: [ISO date]
+**Audit Depth**: [surface | standard | thorough]
+**Skills Audited**: N
+**Passes Completed**: N
+**Copilot Validation**: [yes | skipped]
+
+## Executive Summary
+
+[2–3 sentences: overall quality, critical issues, top recommendation]
+
+**Directory Quality Score**: [X.X] / 5.0 — Grade [A–F]
+
+## Skill Scoreboard
+
+| Skill               | Score | Grade | Top Issue                          |
+| ------------------- | ----- | ----- | ---------------------------------- |
+| adversarial-planner | 4.5   | A     | —                                  |
+| docker              | 3.2   | C     | Ambiguous multi-stage instructions |
+| ...                 |       |       |                                    |
+
+## Top 5 Improvements (by impact)
+
+1. [Highest-impact fix]
+2. ...
+
+## Trigger Collision Map
+
+[From Phase 2]
+
+## Coverage Gap Analysis
+
+[Domains without skill coverage]
+
+## Full Findings (by severity)
+
+[All findings from Phase 2]
+
+## Improvement Plan
+
+[From Phase 3]
+
+## Per-Skill Scorecards
+
+[From Phase 1 — all individual scorecards]
+```

package/skills/adversarial-skill-audit/scripts/check-skills.ps1

@@ -0,0 +1,48 @@
+param (
+    [Parameter(Mandatory=$false)]
+    [switch]$FormatJson
+)
+
+# Resolve the skills root directory, assuming the script is in skills/adversarial-skill-audit/scripts
+$targetDir = Resolve-Path "$PSScriptRoot\..\.."
+$skills = Get-ChildItem -Path $targetDir -Directory | Where-Object Name -notin 'bin', 'node_modules', '.git', '.agents'
+
+$results = @()
+
+foreach ($skill in $skills) {
+    $skillFile = Join-Path $skill.FullName "SKILL.md"
+    if (Test-Path $skillFile) {
+        $content = Get-Content $skillFile -Raw
+        $lines = ($content -split "`n").Count
+        $hasName = $content -match "name:.*"
+        $hasDesc = $content -match "description:.*"
+        $descMatches = [regex]::Match($content, 'description:\s*\|?([^#]*)---', [System.Text.RegularExpressions.RegexOptions]::Singleline)
+        $desc = if ($descMatches.Success) { $descMatches.Groups[1].Value.Trim() -replace "`r", "" -replace "`n", " " } else { "None" }
+        $descWords = ($desc -split "\s+").Count
+        
+        $obj = [PSCustomObject]@{
+            Name = $skill.Name
+            Lines = $lines
+            HasName = $hasName
+            HasDesc = $hasDesc
+            DescWords = $descWords
+            DescPreview = if ($desc.Length -gt 150) { $desc.Substring(0, 150) + "..." } else { $desc }
+        }
+        $results += $obj
+    } else {
+        $results += [PSCustomObject]@{
+            Name = $skill.Name
+            Lines = 0
+            HasName = $false
+            HasDesc = $false
+            DescWords = 0
+            DescPreview = "MISSING SKILL.md"
+        }
+    }
+}
+
+if ($FormatJson) {
+    $results | ConvertTo-Json -Depth 2
+} else {
+    $results | Format-Table -Property Name, Lines, DescWords, DescPreview
+}

package/skills/adversarial-skill-audit/scripts/run-copilot.ps1

@@ -0,0 +1,52 @@
+param (
+    [Parameter(Mandatory=$false)]
+    [string]$TargetSkill = ""
+)
+
+# Resolve the skills root directory
+$skillsDir = Resolve-Path "$PSScriptRoot\..\.."
+
+# Ensure gh CLI is available
+if (-not (Get-Command "gh" -ErrorAction SilentlyContinue)) {
+    Write-Error "GitHub CLI (gh) is required but not installed."
+    exit 1
+}
+
+# Determine which skills to run against
+if ($TargetSkill) {
+    $targetPath = Join-Path $skillsDir $TargetSkill
+    if (-not (Test-Path $targetPath)) {
+        Write-Error "Skill directory '$TargetSkill' not found in $skillsDir"
+        exit 1
+    }
+    $skills = @(Get-Item $targetPath)
+} else {
+    $skills = Get-ChildItem -Path $skillsDir -Directory | Where-Object Name -notin 'bin', 'node_modules', '.git', '.agents'
+}
+
+foreach ($skill in $skills) {
+    $skillFile = Join-Path $skill.FullName "SKILL.md"
+    if (Test-Path $skillFile) {
+        Write-Host "==========================================" -ForegroundColor Cyan
+        Write-Host "Validating: $($skill.Name)" -ForegroundColor Cyan
+        Write-Host "==========================================" -ForegroundColor Cyan
+        
+        $content = Get-Content $skillFile -Raw
+        
+        $prompt = "You are an expert in AI agent instruction design. Review this agent skill file for quality. `n"
+        $prompt += "Evaluate it on:`n1. Trigger reliability`n2. Instruction clarity`n3. Completeness`n4. Token efficiency`n5. Security`n`n"
+        $prompt += "File: $($skill.Name)/SKILL.md`n`n"
+        $prompt += $content
+        $prompt += "`n`nOutput a Markdown table with columns: #, Category, Severity, Finding, Suggestion."
+        
+        # Trim prompt to avoid max command line length issues (approx 8191 chars on Windows)
+        $maxLength = 7800
+        if ($prompt.Length -gt $maxLength) {
+            $prompt = $prompt.Substring(0, $maxLength) + "`n... [CONTENT TRUNCATED FOR LENGTH]"
+        }
+        
+        # Execute gh copilot in non-interactive mode with -p
+        gh copilot -s -p $prompt
+        Write-Host "`n"
+    }
+}

package/skills/adversarial-workflow-audit/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: adversarial-workflow-audit
+description: |
+  Multi-pass adversarial quality audit for flat markdown workflow files. 
+  Combines structured evaluation (Agent A) with adversarial stress-testing (Agent B) 
+  to assess sequential clarity, prerequisite validation, HITL (Human-in-the-loop) safety gates, 
+  loop prevention, and formatting. Use when auditing workflow scripts (e.g., slash-commands like /bump-deploy),
+  or when the user asks to review or improve operational playbooks.
+---
+
+# Adversarial Workflow Audit
+
+A multi-pass quality auditing system adapted specifically for manual markdown workflows.
+Unlike agent skills (which trigger automatically), workflows are manually invoked by users
+and execute sequentially. This audit ensures they are deterministic, safe, and robust.
+
+## When to Load
+
+Load this skill when any of these apply:
+
+- Auditing an entire workflows directory for quality and safety.
+- Reviewing a new workflow before finalizing it.
+- The user asks for a workflow quality check or playbook review.
+- The user says "audit this workflow", "review this runbook", "check my playbook", or "review this slash command".
+
+## Adversarial Protocol
+
+This skill follows the standard dual-agent adversarial pattern (Agent A: The Evaluator, Agent B: The Adversarial Tester).
+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)**
+
+## Deep References
+
+For the specific audit categories and rubric, read:
+
+- **[Audit Categories Reference](references/audit-categories.md)**
+
+## External Validation (Phase 4)
+
+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 workflow
+quality, catching ambiguous steps and missing safety gates that internal review
+normalizes.
+
+**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
+
+Every phase creates a journal entry for future retrieval. Ensure the `entry_type` and tags map to the protocol table above.
+
+### Journal Opt-Out
+
+See `../adversarial-security/references/journal-opt-out.md` for instructions on how to handle explicit opt-outs from journaling.
+
+## Scripts
+
+- `scripts/check-workflows.ps1`: Gathers baseline structural metrics across a workflows directory.
+
+## Configuration
+
+| Variable             | Default    | Description                                       |
+| -------------------- | ---------- | ------------------------------------------------- |
+| `MAX_AUDIT_PASSES`   | `2`        | Maximum stress-test cycles (phases 2–3 repeat)    |
+| `AUDIT_DEPTH`        | `standard` | Depth: `surface`, `standard`, or `thorough`       |
+| `COPILOT_VALIDATION` | `true`     | Enable/disable Copilot extension validation phase |
+
+### Audit Depth Profiles
+
+- **Surface**: Review structure, linear step numbering, and obvious prerequisites. Quick scan for workflow injection vectors.
+- **Standard**: Full audit with all review dimensions and Phase 2 stress testing. Default for most workflows.
+- **Thorough**: Full audit plus cross-workflow impact analysis, ecosystem comparisons, and rigorous infinite loop boundary testing.
+
+## Synergies
+
+| Skill/Workflow        | Relationship                                                                       |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| `adversarial-planner` | Parent pattern; this skill adapts it for manual execution workflows.               |
+| `/doc-audit`          | Audits documentation repositories, but not specifically executable workflow steps. |

package/skills/adversarial-workflow-audit/references/audit-categories.md

@@ -0,0 +1,28 @@
+# Workflow Audit Categories
+
+The workflow evaluator and adversarial tester score the workflow against 5 major categories.
+
+## 1. Safety Gates (HITL)
+
+- **Evaluator**: Are destructive actions (git push, merge, deploy, npm publish, database migrations) explicitly marked with HITL gates (e.g. `STOP HERE. Ask the user for confirmation`)?
+- **Adversarial**: Could an over-eager agent chain tool calls together to bypass a confirmation? Are the stop instructions assertive enough?
+
+## 2. Pre-Flight & Prerequisites
+
+- **Evaluator**: Does the workflow begin with an explicit step to check prerequisites (e.g., "Run `/security-audit` first" or "Verify tests pass")?
+- **Adversarial**: What if the prerequisite fails? Is there an instruction on what the agent should do, or does it blindly proceed to step 2?
+
+## 3. Execution Determinism & Loop Prevention
+
+- **Evaluator**: Are instructions explicit and imperative? Is there any ambiguous "try to fix this" wording that lacks boundaries?
+- **Adversarial**: If a tool call (like `npm run build`) fails, does the workflow cap retry attempts or define an escalation path? Vague instructions like "fix errors until it passes" cause expensive infinite loops.
+
+## 4. State Management
+
+- **Evaluator**: If the workflow spans multiple steps, does it instruct the agent to journal or track state?
+- **Adversarial**: If the user leaves and returns the next day, will the agent know where it left off?
+
+## 5. Formatting & Token Efficiency
+
+- **Evaluator**: Is the workflow concise? Does it avoid monolithic, repetitive examples? Are code blocks minimized?
+- **Adversarial**: Are there markdown formatting bugs that could break an agent's markdown parser or regex?

package/skills/adversarial-workflow-audit/references/copilot-usage.md

@@ -0,0 +1,16 @@
+# GitHub Copilot External Validation
+
+> **⚠️ CRITICAL — Non-Interactive Mode**: The `gh copilot` CLI must be run in
+> non-interactive mode using the `-p` (or `--prompt`) flag. Interactive mode
+> will hang indefinitely in an automated agent context. Use:
+>
+> ```
+> gh copilot -p "Considering these standards from Phase 0 research: [insert findings]. <prompt>" --allow-tool "shell(find,cat,head,grep)"
+> ```
+>
+> The `--allow-tool` flag grants Copilot read access to the repository files.
+> Always `Set-Location` (or `cd`) to the target repository before invoking.
+>
+> **⚠️ TIMEOUT GUIDANCE**: Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts, use the `-s` flag or allow the command to naturally fall into the background.
+
+> **⚠️ CRITICAL — No Fabrication**: You MUST actually execute `gh copilot` commands. Do NOT fabricate or predict what Copilot would say.

package/skills/adversarial-workflow-audit/scripts/check-workflows.ps1

@@ -0,0 +1,24 @@
+$targetDir = "C:\Users\chris\Desktop\adamic\.agents\workflows"
+$workflows = Get-ChildItem -Path $targetDir -Filter *.md
+
+$results = @()
+
+foreach ($wf in $workflows) {
+    $content = Get-Content $wf.FullName -Raw
+    $lines = ($content -split "`n").Count
+    $hasDesc = $content -match "description:.*"
+    $descMatches = [regex]::Match($content, 'description:\s*\|?([^#]*)---', [System.Text.RegularExpressions.RegexOptions]::Singleline)
+    $desc = if ($descMatches.Success) { $descMatches.Groups[1].Value.Trim() -replace "`r", "" -replace "`n", " " } else { "None" }
+    $descWords = ($desc -split "\s+").Count
+    
+    $obj = [PSCustomObject]@{
+        Name = $wf.BaseName
+        Lines = $lines
+        HasDesc = $hasDesc
+        DescWords = $descWords
+        DescPreview = if ($desc.Length -gt 150) { $desc.Substring(0, 150) + "..." } else { $desc }
+    }
+    $results += $obj
+}
+
+$results | ConvertTo-Json -Depth 2