memory-journal-mcp 7.7.0 → 8.0.0

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

@@ -0,0 +1,308 @@
+# Audit Categories
+
+Detailed reference for the 8 per-skill and 4 directory-level quality
+categories. Agent A (Evaluator) uses this during Phase 1 profiling.
+Agent B (Adversarial User) uses it to construct stress scenarios in Phase 2.
+
+All quality standards are derived from the
+[skill-builder](../../skill-builder/SKILL.md) skill and its
+[checklist](../../skill-builder/checklist.md).
+
+---
+
+## Per-Skill Categories
+
+### Category 1 — Frontmatter & Triggering
+
+The most important category. A perfectly written skill that never triggers
+is worth nothing.
+
+**What to Evaluate:**
+
+- `name` is kebab-case and descriptive
+- `description` is present, assertive, and includes trigger keywords
+- `description` uses "Use when..." or "Also use when..." phrasing
+- `description` is under ~100 words (token budget)
+- `description` covers primary, secondary, and tertiary trigger phrasings
+- Optional frontmatter fields are used appropriately (`dependencies`,
+  `context`, `disable-model-invocation`, etc.)
+
+**Anti-Patterns:**
+
+| Pattern                       | Problem                                       |
+| ----------------------------- | --------------------------------------------- |
+| `description: Guide for X`    | Passive — agent won't trigger                 |
+| 3-word description            | Too vague — triggers on everything or nothing |
+| 200-word description          | Token waste — loaded on every conversation    |
+| Missing alternative phrasings | Agent only triggers on exact keywords         |
+| `name: my_skill`              | Not kebab-case                                |
+
+**Scoring Guide:**
+
+| Score | Criteria                                                                             |
+| ----- | ------------------------------------------------------------------------------------ |
+| 5     | Assertive description with 3+ trigger contexts, ~50–100 words, covers edge phrasings |
+| 4     | Good description, covers main triggers, minor phrasing gaps                          |
+| 3     | Present but passive or missing secondary triggers                                    |
+| 2     | Too vague or too long, unreliable triggering                                         |
+| 1     | Missing or broken frontmatter                                                        |
+
+---
+
+### Category 2 — Instruction Clarity
+
+**What to Evaluate:**
+
+- Instructions explain _why_, not just _what_ (reasoning helps agents
+  generalize to novel situations)
+- Uses imperative form ("Run X" not "You should run X")
+- No wall-of-MUSTs (excessive MUST/NEVER/ALWAYS in all-caps)
+- Steps are ordered logically with clear dependencies
+- Conditional logic is explicit ("If X, do Y. Otherwise, do Z.")
+- Ambiguous pronouns are avoided ("it", "this" — what does "it" refer to?)
+
+**Anti-Patterns:**
+
+| Pattern                       | Problem                                                         |
+| ----------------------------- | --------------------------------------------------------------- |
+| "MUST ALWAYS NEVER use X"     | All-caps overload — agent treats everything as equally critical |
+| "Consider using caching"      | Too passive — agent may skip entirely                           |
+| "Set up the project"          | No specifics — agent will hallucinate a setup process           |
+| "Handle errors appropriately" | Vague — what does "appropriately" mean?                         |
+| Steps without ordering        | Agent may execute in wrong sequence                             |
+
+**Scoring Guide:**
+
+| Score | Criteria                                                 |
+| ----- | -------------------------------------------------------- |
+| 5     | Clear, imperative, explains reasoning, no ambiguity      |
+| 4     | Mostly clear, minor vague spots                          |
+| 3     | Functional but has passive language or unclear sections  |
+| 2     | Multiple ambiguous instructions, agent likely to deviate |
+| 1     | Confusing, contradictory, or unusable instructions       |
+
+---
+
+### Category 3 — Structure & Progressive Disclosure
+
+**What to Evaluate:**
+
+- `SKILL.md` is under ~500 lines
+- Large reference content is in `references/` with clear pointers
+- SKILL.md has enough context to start working without reading references
+- Pointers to reference files include guidance on _when_ to read them
+- Reference depth is shallow (one hop from SKILL.md, not chains)
+- Directory uses kebab-case naming
+- Files are organized by functional purpose
+
+**Anti-Patterns:**
+
+| Pattern                                 | Problem                                |
+| --------------------------------------- | -------------------------------------- |
+| 800-line SKILL.md                       | Token overflow, agent may lose context |
+| No references for complex skill         | Everything crammed into SKILL.md       |
+| "Read references/setup.md" (no context) | Agent doesn't know when to read it     |
+| SKILL → ref-A → ref-B → ref-C           | Too many hops, agent gets lost         |
+| Flat directory with 10 files            | No organizational structure            |
+
+**Scoring Guide:**
+
+| Score | Criteria                                                               |
+| ----- | ---------------------------------------------------------------------- |
+| 5     | Clean 3-tier structure, SKILL.md < 500 lines, clear reference pointers |
+| 4     | Good structure, minor pointer gaps                                     |
+| 3     | Functional but SKILL.md is heavy or references are disorganized        |
+| 2     | Monolithic SKILL.md or confusing file layout                           |
+| 1     | No structure — single massive file or scattered fragments              |
+
+---
+
+### Category 4 — Output Formats & Templates
+
+**What to Evaluate:**
+
+- Output formats are explicitly defined with templates
+- Templates include example content (not just empty headings)
+- Structured outputs (tables, scorecards, reports) have clear schemas
+- The agent knows what "done" looks like
+
+**Anti-Patterns:**
+
+| Pattern                                      | Problem                                  |
+| -------------------------------------------- | ---------------------------------------- |
+| "Produce a report"                           | No format specified — agent invents one  |
+| Template with only headings, no example rows | Agent may misunderstand column semantics |
+| No success criteria                          | Agent doesn't know when to stop          |
+
+**Scoring Guide:**
+
+| Score | Criteria                                                           |
+| ----- | ------------------------------------------------------------------ |
+| 5     | Explicit templates with example content, clear completion criteria |
+| 4     | Templates present, minor gaps in examples                          |
+| 3     | Some format guidance but incomplete                                |
+| 2     | Vague output expectations                                          |
+| 1     | No output format defined — agent guesses                           |
+
+---
+
+### Category 5 — Edge Cases & Error Handling
+
+**What to Evaluate:**
+
+- Prerequisite failures are handled gracefully (missing tools, wrong
+  project type, missing files)
+- Edge cases are documented ("If X is not found, do Y")
+- The skill degrades gracefully rather than crashing
+- Error recovery guidance is provided
+
+**Scoring Guide:**
+
+| Score | Criteria                                                           |
+| ----- | ------------------------------------------------------------------ |
+| 5     | All prerequisites documented, graceful degradation, recovery paths |
+| 4     | Main failure cases handled, minor gaps                             |
+| 3     | Some error handling but missing common failure modes               |
+| 2     | Only happy path documented                                         |
+| 1     | No error handling — agent crashes on first edge case               |
+
+---
+
+### Category 6 — Security & Safety
+
+**What to Evaluate:**
+
+- No instructions to read or transmit secrets
+- Destructive skills use `disable-model-invocation: true`
+- Required tools/CLIs are documented
+- Third-party references are reviewed before inclusion
+- No instructions that bypass user consent or HITL gates
+- No instructions that modify agent config or other skills
+
+**Scoring Guide:**
+
+| Score | Criteria                                                              |
+| ----- | --------------------------------------------------------------------- |
+| 5     | All security checks pass, destructive actions gated, no secret access |
+| 4     | Mostly secure, minor documentation gaps                               |
+| 3     | Functional but missing safety gates on risky operations               |
+| 2     | Potential for unsafe behavior without HITL                            |
+| 1     | Actively unsafe — reads secrets, destructive without gates            |
+
+---
+
+### Category 7 — Token Efficiency
+
+**What to Evaluate:**
+
+- Description is ≤ ~100 words (always loaded, costs tokens every turn)
+- SKILL.md body is ≤ ~500 lines
+- Reference files have summaries at the top for skip-or-read decisions
+- No redundant content between SKILL.md and references
+- No copy-pasted documentation that could be linked instead
+- Instructions justify their token cost
+
+**Scoring Guide:**
+
+| Score | Criteria                                                               |
+| ----- | ---------------------------------------------------------------------- |
+| 5     | Lean description, compact SKILL.md, references loaded only when needed |
+| 4     | Mostly efficient, minor redundancy                                     |
+| 3     | Noticeable token waste but functional                                  |
+| 2     | Bloated description or SKILL.md, unnecessary content                   |
+| 1     | Massive token footprint with low value                                 |
+
+---
+
+### Category 8 — Maintenance & Versioning
+
+**What to Evaluate:**
+
+- Content is current (no references to deprecated APIs or tools)
+- Links and file references are valid
+- Version-sensitive instructions specify version requirements
+- Behavior changes are documented in commits
+- Breaking changes have migration notes
+
+**Scoring Guide:**
+
+| Score | Criteria                                                        |
+| ----- | --------------------------------------------------------------- |
+| 5     | Current content, all links valid, version requirements explicit |
+| 4     | Mostly current, minor staleness                                 |
+| 3     | Some outdated content but core instructions still work          |
+| 2     | Significantly outdated, references to deprecated tools          |
+| 1     | Stale — instructions reference non-existent APIs or tools       |
+
+---
+
+## Directory-Level Categories
+
+These categories assess the skills collection as a whole, not individual
+skills.
+
+### Category 9 — Cross-Skill Coherence
+
+**What to Evaluate:**
+
+- Consistent naming conventions across all skills
+- Similar structural patterns (SKILL.md layout, reference organization)
+- Consistent writing style (imperative, reasoning-first)
+- `README.md` inventory is complete and current
+- `package.json` `files` array is complete and current
+- Skill names follow a consistent scheme
+
+---
+
+### Category 10 — Trigger Collision Detection
+
+**What to Evaluate:**
+
+- No two skills claim the same trigger phrase without disambiguation
+- Related skills have clear boundary descriptions ("Use X for Y, use Z
+  for W")
+- Meta-groups of related skills (e.g., all Cloudflare skills) have clear
+  separation
+
+**How to Test:**
+
+Construct 10 ambiguous prompts and determine which skills would compete:
+
+```
+"Deploy my app"
+"Set up the database"
+"Write tests"
+"Build a server"
+"Set up CI/CD"
+"Optimize performance"
+"Fix security issues"
+"Create a new project"
+"Add authentication"
+"Migrate the database"
+```
+
+For each, list which skills would potentially trigger and whether the
+descriptions disambiguate.
+
+---
+
+### Category 11 — Coverage Gap Analysis
+
+**What to Evaluate:**
+
+- Are there common development tasks without skill coverage?
+- Are there skills referenced in synergy tables that don't exist?
+- Does the directory cover the user's technology stack adequately?
+- Are there tool/framework skills missing for frameworks in active use?
+
+---
+
+### Category 12 — Ecosystem Consistency
+
+**What to Evaluate:**
+
+- `package.json` (if present) is valid and version-matched
+- README and package.json inventory matches actual directory contents
+- No orphan directories (skill folders without `SKILL.md`)
+- No orphan references (reference files not pointed to from SKILL.md)
+- Consistent file naming across all skills

package/skills/adversarial-skill-audit/references/copilot-skill-prompts.md

@@ -0,0 +1,68 @@
+# Copilot Skill Prompts
+
+Reference for Phase 4 — independent validation via the GitHub Copilot CLI.
+
+## Prerequisites
+
+1. **GitHub CLI installed**: `gh --version` (v2.x+)
+2. **Authenticated**: `gh auth status` passing
+3. **Copilot available**: `gh copilot --version` — the `copilot` subcommand is built into modern `gh` CLI (no separate extension needed)
+
+If Copilot CLI is not available, skip Phase 4 gracefully.
+
+## Prompt Templates
+
+> **⚠️ 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 "<prompt>" --allow-tool "shell(find,cat,head,grep)"
+> ```
+>
+> The `--allow-tool` flag grants Copilot read access to the repository files.
+
+- Expect 60–120 seconds per prompt. In environments with hard synchronous timeouts (like Antigravity's 10s `WaitMsBeforeAsync` limit), allow the command to naturally fall into the background. Use the `schedule` tool or wait for the system notification to retrieve the results. Do not skip execution due to timeout constraints.
+
+**Skill Quality:**
+"You are an expert in AI agent instruction design. Review these agent skill files for quality. Evaluate each skill on:
+
+1. **Trigger reliability** — Will the description reliably trigger the skill for relevant user prompts?
+2. **Instruction clarity** — Are the instructions clear, unambiguous, and in imperative form?
+3. **Completeness** — Are edge cases handled? What happens when prerequisites are missing?
+4. **Token efficiency** — Is the description concise (~100 words)? Is the body under ~500 lines?
+5. **Security** — Are there any instructions that could cause unsafe agent behavior?"
+
+**Trigger Collision Analysis:**
+"You are an AI agent routing expert. Given these skill descriptions, identify which skills would compete to handle the same user prompt. For each collision, suggest how to disambiguate. Test these ambiguous prompts:
+
+- 'Deploy my app'
+- 'Set up the database'
+- 'Write tests for this'
+- 'Fix security issues'
+- 'Optimize performance'
+- 'Build a server'
+- 'Set up CI/CD'"
+
+**Ecosystem Consistency and Coverage Gap Analysis:**
+"You are an expert in developer tooling ecosystems. Evaluate the overall structure and coverage of this skills directory. Identify:
+
+1. Are there common development tasks or technologies relevant to modern Node/TypeScript/Cloudflare stacks that are missing skill coverage?
+2. Are there organizational or naming inconsistencies across the skills?
+3. Which skills should potentially be merged or deprecated due to high overlap?"
+
+## Parsing Copilot Output
+
+1. **Extract findings** — parse tables or numbered lists
+2. **Map to categories** — classify against the 8 per-skill or 4
+   directory-level categories
+3. **Deduplicate** — compare against Phase 2 findings
+4. **Disposition** — apply Accept/Reject/Modify/Defer from Phase 3
+
+## Prompt Selection Guide
+
+| Audit Depth | Prompts to Use                                            |
+| ----------- | --------------------------------------------------------- |
+| Surface     | Skill Quality only                                        |
+| Standard    | Skill Quality + Trigger Collision + Ecosystem Consistency |
+| Thorough    | All three prompts                                         |

package/skills/adversarial-skill-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-skill-audit/references/feedback-loop.md

@@ -0,0 +1,155 @@
+# Feedback Loop & Documentation
+
+Reference for journaling, cross-session learning, and retrospective patterns
+used throughout the adversarial skill audit protocol.
+
+## Journal Entry Templates
+
+### Phase 1 — Inventory & Profiling
+
+```
+create_entry({
+  content: "# Skill Audit Profile: [Directory]\n\nSkills audited: N\nAverage score: X.X/5.0\n\n[per-skill scorecards + directory overview]",
+  entry_type: "skill_audit_profile",
+  tags: ["adversarial-skill-audit", "profile"],
+  project_number: <project number>
+})
+```
+
+### Phase 2 — Adversarial User Review
+
+```
+create_entry({
+  content: "# Adversarial User Review: [Directory]\n\nOverall Score: X/5.0 — Grade Y\n\n[trigger tests + collision map + findings]",
+  entry_type: "skill_audit_stress",
+  tags: ["adversarial-skill-audit", "stress-test"],
+  project_number: <project number>
+})
+```
+
+### Phase 3 — Improvement Plan
+
+```
+create_entry({
+  content: "# Skill Improvement Plan: [Directory]\n\n[disposition table + priority tiers]",
+  entry_type: "skill_audit_remediation",
+  tags: ["adversarial-skill-audit", "remediation"],
+  project_number: <project number>
+})
+```
+
+### Phase 4 — Copilot Validation
+
+```
+create_entry({
+  content: "# Copilot Skill Validation: [Directory]\n\n[copilot findings + dispositions]",
+  entry_type: "skill_audit_copilot",
+  tags: ["adversarial-skill-audit", "copilot"],
+  project_number: <project number>
+})
+```
+
+### Final Summary
+
+```
+create_entry({
+  content: "# Skill Audit Complete: [Directory]\n\nDirectory Score: X.X/5.0 (Grade Y)\nSkills audited: N\nGrade distribution: A: N, B: N, C: N, D: N, F: N\n\n## Key Findings\n- [top 3 findings]\n\n## Improvements Planned\n- [accepted dispositions]\n\n## Trigger Collisions\n- [collision summary]",
+  entry_type: "skill_audit_complete",
+  tags: ["adversarial-skill-audit", "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: "Adversarial user review of skill inventory"
+})
+
+link_entries({
+  from_entry_id: <remediation_entry_id>,
+  to_entry_id: <stress_test_entry_id>,
+  relationship_type: "evolves_from",
+  description: "Improvement plan based on adversarial findings"
+})
+
+link_entries({
+  from_entry_id: <current_audit_id>,
+  to_entry_id: <prior_audit_id>,
+  relationship_type: "evolves_from",
+  description: "Follow-up audit tracking skill quality evolution"
+})
+```
+
+## Cross-Session Learning
+
+### Find Prior Skill Audits
+
+```
+search_entries({
+  query: "skill audit",
+  entry_type: "skill_audit_profile",
+  tags: ["adversarial-skill-audit"]
+})
+```
+
+### Track Quality Trends
+
+Compare scores across audits to measure improvement:
+
+```
+search_entries({
+  query: "skill audit complete",
+  entry_type: "skill_audit_complete",
+  tags: ["adversarial-skill-audit", "audit-complete"]
+})
+```
+
+### Find Recurring Skill Issues
+
+```
+search_entries({
+  query: "<issue type, e.g., 'trigger collision'>",
+  entry_type: "skill_audit_stress",
+  tags: ["adversarial-skill-audit"]
+})
+```
+
+## Session Retrospective
+
+```
+create_entry({
+  content: "# Skill Audit Retrospective: [Directory]\n\n## Key Insights\n- [What the Evaluator missed that the Adversarial User caught]\n- [Trigger collisions that surprised us]\n- [Patterns worth applying to all skills]\n\n## Metrics\n- Initial average score: X.X/5.0\n- Projected average score: X.X/5.0\n- Skills needing major work: N\n- Trigger collisions resolved: N/M\n- Coverage gaps identified: N\n\n## Process Improvements\n- [Categories to emphasize next time]\n- [New trigger test prompts to add]",
+  entry_type: "retrospective",
+  tags: ["adversarial-skill-audit", "retrospective", "session-summary"],
+  project_number: <project number>
+})
+```
+
+## Tag Convention
+
+| Tag                       | Purpose                                        |
+| ------------------------- | ---------------------------------------------- |
+| `adversarial-skill-audit` | All entries from this skill (primary filter)   |
+| `profile`                 | Phase 1 output                                 |
+| `stress-test`             | Phase 2 output                                 |
+| `remediation`             | 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                                         |
+| ------------------------- | ----- | --------------------------------------------------- |
+| `skill_audit_profile`     | 1     | Per-skill scorecards and directory overview         |
+| `skill_audit_stress`      | 2     | Trigger tests, collisions, instruction stress tests |
+| `skill_audit_remediation` | 3     | Improvement plan with dispositions                  |
+| `skill_audit_copilot`     | 4     | Copilot validation findings                         |
+| `skill_audit_complete`    | Final | Consolidated audit summary                          |
+| `retrospective`           | Post  | Session retrospective with metrics                  |