memory-journal-mcp 6.1.2 → 6.2.1

package/skills/github-commander/workflows/code-quality-audit.md

@@ -0,0 +1,80 @@
+# Code Quality Audit
+
+Run a comprehensive code quality audit as a static analysis pass. No code
+changes are made until the human approves the findings.
+
+## Prompt
+
+Perform a comprehensive code quality audit of the target project. For each
+finding, report the file path, line range, severity (critical / moderate / low),
+and a concrete fix suggestion. Group findings by category:
+
+1. **Dead & unreachable code** — unused exports, unreachable branches, vestigial
+   feature flags
+2. **Duplication** — repeated logic that should be extracted into shared helpers
+3. **Import hygiene** — unused imports, missing imports, circular dependencies
+4. **Type safety** — `any` usage, loose type assertions (`as`), missing return
+   types on exported functions
+5. **Error handling** — typed error classes with descriptive messages including
+   context. Propagate with stack traces; never silently swallow exceptions
+6. **Logging** — centralized logger with structured payloads. Module-prefixed
+   codes. Severity: error | warning | info
+7. **Complexity** — functions exceeding ~40 lines, files exceeding ~500 lines,
+   high branching depth. Large files should be split into subdirectories with
+   barrel re-exports
+8. **Naming & consistency** — files/folders should follow project conventions.
+   Flag unclear variable names and inconsistent naming
+9. **Magic values** — hardcoded strings, numbers, or timeouts that should be
+   named constants
+10. **Stale markers** — TODO, FIXME, HACK, XXX comments; outdated JSDoc;
+    comments that contradict the code
+11. **Security** — unsanitized input, missing validation, overly permissive
+    schemas
+12. **Performance** — unnecessary allocations in hot paths, missing early
+    returns, redundant queries
+13. **Dependency hygiene** — unused dependencies, unlisted peer dependencies
+14. **Accessibility** — if any UI/HTML output exists, verify proper labeling,
+    semantic structure, keyboard operability, contrast, and ARIA attributes
+
+## Execution
+
+1. Scan the project source directory systematically
+2. Journal each finding:
+   ```
+   create_entry({
+     content: "Code quality finding: [<category>] <severity> — <description>. File: <path>:<lines>.",
+     entry_type: "audit_finding",
+     tags: ["commander", "code-quality", "<category>"],
+   })
+   ```
+3. Produce a summary table:
+   | Category | Findings | Critical | Moderate | Low |
+   |---|---|---|---|---|
+4. Assign an overall quality score (A–F)
+
+## HITL Checkpoint
+
+Present findings to the human:
+
+- Summary table with counts per category
+- Overall quality score
+- Top critical findings with fix suggestions
+
+Wait for approval before applying any fixes.
+
+## Apply Fixes
+
+After human approval:
+
+1. Fix critical issues first, then moderate, then low
+2. Run validation gates after all fixes:
+   - Gate 1: Lint + Typecheck
+   - Gate 2: Build
+   - Gate 3: Tests
+3. Update changelog with audit fixes
+4. Commit with descriptive message:
+   ```bash
+   git add <fixed files> <changelog>
+   git diff --cached --stat
+   git commit -m "chore: code quality audit fixes"
+   ```

package/skills/github-commander/workflows/full-audit.md

@@ -0,0 +1,134 @@
+# Full Audit
+
+Run a unified code quality + performance + security audit in a single pass with
+cross-reference analysis. Use for codebases that are already in good shape.
+
+> **When to use**: For established codebases that have likely passed individual
+> audits before. This prevents the "fix cascade" where a security fix introduces
+> a quality regression, or a performance optimization weakens validation.
+
+> **Do not use for**: First-time audits on codebases with many known issues.
+> Run the individual workflows (`code-quality-audit.md`, `perf-audit.md`,
+> `security-audit.md`) separately and fix iteratively instead.
+
+## Phase 1 — Collect Findings (Read-Only)
+
+Run all three audits as **read-only analysis** — no fixes yet. Tag each finding
+by its source domain.
+
+### 1a. Code Quality Scan
+
+Follow `code-quality-audit.md` categories 1–14. Tag every finding with `[CQ]`.
+
+### 1b. Performance Scan
+
+Follow `perf-audit.md` sections 1–6. Tag every finding with `[PERF]`.
+
+### 1c. Security Scan
+
+Follow `security-audit.md` phases 2–7. Tag every finding with `[SEC]`.
+
+### 1d. Raw Findings Ledger
+
+Produce **one** consolidated table sorted by severity:
+
+| #   | Tag | Severity | File | Lines | Finding | Suggested Fix |
+| --- | --- | -------- | ---- | ----- | ------- | ------------- |
+
+**Do not apply any fixes yet.**
+
+## Phase 2 — Cross-Reference Analysis
+
+Review the raw ledger and identify findings that interact across domains.
+
+### Conflict Types
+
+| Type                       | Example                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------- |
+| **Security ↔ Quality**     | A `[SEC]` fix (adding validation) could introduce duplication flagged by `[CQ]` |
+| **Security ↔ Performance** | A `[SEC]` fix (parameterized queries, hashing) could degrade `[PERF]`           |
+| **Performance ↔ Quality**  | A `[PERF]` fix (inlining, caching) could increase complexity flagged by `[CQ]`  |
+| **Performance ↔ Security** | A `[PERF]` fix (caching, skipping validation) could weaken a `[SEC]` boundary   |
+| **Shared Root Cause**      | Multiple findings trace to the same underlying issue                            |
+| **Fix Dependency**         | One finding must be fixed before another                                        |
+
+### Cross-Reference Table
+
+| Linked Findings | Conflict Type | Resolution Strategy |
+| --------------- | ------------- | ------------------- |
+
+If no cross-references are found, state that explicitly.
+
+## Phase 3 — Prioritized Fix Plan
+
+Produce an **ordered fix plan** that avoids cascading regressions:
+
+### Ordering Rules
+
+1. **Shared root causes first** — a single fix resolves multiple findings
+2. **Fix dependencies next** — structural changes that unblock later fixes
+3. **Security-critical** — critical/high `[SEC]` findings
+4. **Cross-referenced fixes** — unified resolution strategies from Phase 2
+5. **Remaining findings** — in severity order
+
+### Fix Plan Table
+
+| Order | Finding(s) | Fix Description | Domains Resolved |
+| ----- | ---------- | --------------- | ---------------- |
+
+## HITL Gate — User Approval
+
+**Stop here.** Present the Phase 2 cross-reference analysis and Phase 3 fix
+plan to the human for review. Do not proceed until explicitly approved.
+
+Journal the audit state:
+
+```
+create_entry({
+  content: "Full audit complete. Findings: <N total> (<CQ count> CQ, <PERF count> PERF, <SEC count> SEC). Cross-references: <N>. Awaiting approval for fix plan.",
+  entry_type: "audit_finding",
+  tags: ["commander", "full-audit", "summary"],
+})
+```
+
+## Phase 4 — Apply Fixes & Verify
+
+Apply fixes in the approved order. After **all** fixes:
+
+Run validation gates:
+
+- Gate 1: Lint + Typecheck
+- Gate 2: Build
+- Gate 3: Tests
+
+If any validation fails, identify which fix group caused it and revise.
+
+## Phase 5 — Final Report
+
+### Summary Table
+
+| Domain       | Score (A–F) | Findings | Critical | Cross-Referenced |
+| ------------ | ----------- | -------- | -------- | ---------------- |
+| Code Quality |             |          |          |                  |
+| Performance  |             |          |          |                  |
+| Security     |             |          |          |                  |
+
+### Metrics
+
+- **Total findings**: _N_
+- **Cross-referenced findings**: _N_
+- **Cascading fixes avoided**: _N_
+
+### Overall Score
+
+Assign an **overall health score (A–F)** considering all three domains.
+
+## Post-Audit
+
+1. Update changelog with fixes
+2. Commit:
+   ```bash
+   git add <fixed files> <changelog>
+   git diff --cached --stat
+   git commit -m "chore: unified audit fixes"
+   ```

package/skills/github-commander/workflows/issue-triage.md

@@ -0,0 +1,239 @@
+# Issue Triage
+
+Fix a single assigned GitHub issue end-to-end — from context gathering through
+validated PR submission.
+
+## Phase 1 — Gather Context
+
+1. Read `memory://briefing` for session context
+2. Fetch the assigned issue:
+   ```
+   get_github_issue({ issue_number: <N> })
+   ```
+3. Search journal for related prior work:
+   ```
+   semantic_search({ query: "<issue title/description>" })
+   search_entries({ tags: ["commander"] })
+   ```
+4. Check knowledge graph for linked specs/implementations:
+   ```
+   visualize_relationships({ format: "mermaid" })
+   ```
+5. Journal the triage start:
+   ```
+   create_entry({
+     content: "Triaging issue #<N>: <title>. Related entries: <ids>. Prior context: <summary>.",
+     entry_type: "triage",
+     tags: ["commander", "triage"],
+     issue_number: <N>
+   })
+   ```
+
+## Phase 2 — Implement Fix
+
+1. Analyze the issue and implement the fix
+2. Follow existing project conventions (check journal for patterns, rules, etc.)
+3. Journal the implementation:
+   ```
+   create_entry({
+     content: "Implemented fix for #<N>: <description of changes>. Files modified: <list>.",
+     entry_type: "implementation",
+     tags: ["commander", "fix"],
+     issue_number: <N>
+   })
+   ```
+
+## Phase 3 — Validation Gates
+
+Run gates sequentially. Each must pass before the next. Skip gates where the
+command is empty or not configured.
+
+### Gate 1: Lint + Typecheck
+
+Run `PROJECT_LINT_CMD` (default: `npm run lint`).
+Run `PROJECT_TYPECHECK_CMD` (default: `npm run typecheck`).
+
+On failure:
+
+- Attempt auto-fix (run lint with `--fix` if available)
+- Re-run the gate
+- If still failing after 2 attempts → **HITL checkpoint**
+
+Journal result:
+
+```
+create_entry({
+  content: "Gate 1 (Lint + Typecheck): PASSED/FAILED. Details: <output>.",
+  entry_type: "gate_pass" or "gate_fail",
+  tags: ["commander", "validation", "lint"],
+  issue_number: <N>
+})
+```
+
+### Gate 2: Build
+
+Run `PROJECT_BUILD_CMD` (default: `npm run build`).
+Skip if not configured (empty string).
+
+On failure → attempt fix → **HITL checkpoint** after 2 attempts.
+
+### Gate 3: Unit/Integration Tests
+
+Run `PROJECT_TEST_CMD` (default: `npm run test`).
+
+On failure:
+
+- Analyze test output to determine if failure is related to the fix
+- If related: attempt to fix the test or the code
+- If unrelated (pre-existing failure): journal and flag for human
+- After 2 fix attempts → **HITL checkpoint**
+
+### Gate 4: E2E Tests
+
+Run `PROJECT_E2E_CMD` (default: empty = skip).
+Skip if not configured. Same failure handling as Gate 3.
+
+### Gate 5: Security Scans
+
+Run auto-detected security scanning tools (see SKILL.md § Security Tool
+Auto-Detection). For each available tool:
+
+1. Run the scan
+2. Parse output for findings with severity levels
+3. Journal each finding:
+   ```
+   create_entry({
+     content: "Security finding (<tool>): <severity> - <description>",
+     entry_type: "security_finding",
+     tags: ["commander", "security", "<tool-name>"],
+     issue_number: <N>
+   })
+   ```
+4. **Critical/High findings → HITL checkpoint** (present findings, ask how to proceed)
+5. Missing tools → skip with journal note:
+   ```
+   create_entry({
+     content: "Security scan: <tool> not available — skipped.",
+     entry_type: "gate_pass",
+     tags: ["commander", "validation", "security-skip"],
+     issue_number: <N>
+   })
+   ```
+
+#### npm audit
+
+```bash
+npm audit --json
+```
+
+Parse JSON output. Report vulnerabilities by severity.
+
+#### CodeQL (if available)
+
+```bash
+codeql database create /tmp/codeql-db --language=javascript --overwrite
+codeql database analyze /tmp/codeql-db --format=sarif-latest --output=/tmp/codeql-results.sarif
+```
+
+Or via GitHub Actions (if running in CI context).
+
+#### Trivy (if available)
+
+```bash
+trivy fs --severity HIGH,CRITICAL --format json .
+```
+
+For Docker projects (`PROJECT_HAS_DOCKERFILE=true`):
+
+```bash
+trivy image --severity HIGH,CRITICAL --format json <image-name>
+```
+
+#### Docker Scout (if available)
+
+```bash
+docker scout cves <image-name> --format json --only-severity critical,high
+```
+
+#### Gitleaks (if available)
+
+```bash
+gitleaks detect --source . --report-format json --report-path /tmp/gitleaks.json
+```
+
+#### TruffleHog (if available)
+
+```bash
+trufflehog filesystem . --json --only-verified
+```
+
+## Phase 4 — Human Checkpoint
+
+**Always pause before submitting a PR.** Present to the human:
+
+1. Summary of changes (files modified, lines added/removed)
+2. All gate results (pass/fail with details)
+3. Any security findings
+4. All journal entries created during this workflow
+
+**Additional HITL triggers** (pause earlier if any apply):
+
+- Changes touch more files than `COMMANDER_HITL_FILE_THRESHOLD` (default: 10)
+- Any critical or high security findings
+- Test failures that couldn't be auto-fixed
+
+Wait for human approval before proceeding to Phase 5.
+
+## Phase 5 — Submit PR
+
+1. Create a feature branch:
+
+   ```bash
+   git checkout -b <COMMANDER_BRANCH_PREFIX>/issue-<N>
+   ```
+
+2. Stage changed files selectively (**never `git add -A`**):
+
+   ```bash
+   git add <file1> <file2> ...
+   ```
+
+3. Verify staged files:
+
+   ```bash
+   git diff --cached --stat
+   ```
+
+4. Commit with descriptive message:
+
+   ```bash
+   git commit -m "fix: <description> (closes #<N>)"
+   ```
+
+5. Push and create PR:
+
+   ```bash
+   git push origin <COMMANDER_BRANCH_PREFIX>/issue-<N>
+   gh pr create --base main --title "fix: <description>" --body "Closes #<N>\n\n<summary of changes>"
+   ```
+
+6. Journal the PR:
+   ```
+   create_entry({
+     content: "Submitted PR #<pr_number> for issue #<N>: <description>. Gates: all passed.",
+     entry_type: "pr_submitted",
+     tags: ["commander", "pr"],
+     issue_number: <N>,
+     pr_number: <pr_number>
+   })
+   ```
+
+## Phase 6 — Session Summary
+
+Run `/session-summary` to capture:
+
+- Issue triaged and fixed
+- All gate results
+- Security findings (if any)
+- PR link and status
+- Any pending items for next session

package/skills/github-commander/workflows/milestone-sprint.md

@@ -0,0 +1,81 @@
+# Milestone Sprint
+
+Work through open issues in a GitHub milestone sequentially, applying the
+issue-triage workflow to each.
+
+## Phase 1 — Load Milestone
+
+1. Read `memory://briefing` for session context
+2. Fetch milestone details:
+   ```
+   get_github_milestone({ milestone_number: <N> })
+   ```
+3. List open issues in the milestone, sorted by priority labels:
+   ```
+   get_github_issues({ milestone: <N>, state: "open" })
+   ```
+4. Journal sprint start:
+   ```
+   create_entry({
+     content: "Starting milestone sprint: <title>. Open issues: <count>. Completion: <percent>%.",
+     entry_type: "milestone_sprint_start",
+     tags: ["commander", "milestone"],
+   })
+   ```
+
+## Phase 2 — Triage Issues
+
+For each open issue in the milestone (in priority order):
+
+1. **HITL checkpoint**: Present the next issue to the human:
+   - Issue number, title, labels
+   - Estimated complexity (based on description and labels)
+   - Ask: "Proceed with this issue?" / "Skip?" / "Stop sprint?"
+
+2. If human approves: run the full **issue-triage.md** workflow for this issue
+
+3. After each issue is complete, update the sprint progress:
+
+   ```
+   get_github_milestone({ milestone_number: <N> })
+   ```
+
+   Report updated completion percentage.
+
+4. Repeat for next issue until:
+   - All issues are complete
+   - Human chooses to stop
+   - Session time/token limits are approached
+
+## Phase 3 — Sprint Summary
+
+After all issues are processed (or sprint is stopped):
+
+1. Aggregate results across all triaged issues:
+   - Issues attempted vs. completed
+   - Gate results summary (total passes/fails)
+   - Security findings across all issues
+   - PRs submitted
+
+2. Report milestone delta:
+
+   ```
+   get_github_milestone({ milestone_number: <N> })
+   ```
+
+   Show completion percentage before and after sprint.
+
+3. Journal sprint summary:
+
+   ```
+   create_entry({
+     content: "Milestone sprint complete: <title>. Issues fixed: <N>/<total>. Milestone: <before>% → <after>%. PRs: <list>.",
+     entry_type: "milestone_sprint_start",
+     tags: ["commander", "milestone", "summary"],
+   })
+   ```
+
+4. Run `/session-summary` with:
+   - All issues triaged in this sprint
+   - Remaining issues for next session
+   - Any blockers or findings requiring human attention

package/skills/github-commander/workflows/perf-audit.md

@@ -0,0 +1,142 @@
+# Performance Audit
+
+Run a comprehensive performance audit covering build times, bundle size, runtime
+patterns, test suite speed, and database/IO efficiency.
+
+## 1. Build Performance
+
+Measure compilation speed and identify bottlenecks.
+
+For TypeScript projects:
+
+```bash
+npx tsc --noEmit --diagnostics
+```
+
+If a bundler is configured, also run `PROJECT_BUILD_CMD` and report build time.
+
+Report:
+
+- Total compilation time
+- Files compiled, lines of code
+- Memory usage
+- Any abnormally slow type-resolution (deep generics, circular types)
+
+## 2. Bundle & Output Analysis
+
+Analyze the compiled output for size and optimization opportunities:
+
+- Count total output files and aggregate size
+- Identify the largest output files (top 5 by size)
+- Check for accidental bundling of dev dependencies or test fixtures
+- Flag output files that include source maps in production builds
+
+For frontend projects, additionally check:
+
+- Code-splitting effectiveness
+- Asset optimization (images, fonts, CSS)
+- Tree-shaking gaps
+
+## 3. Dependency Weight
+
+Audit dependency footprint:
+
+```bash
+# npm
+npm ls --all --prod 2>/dev/null | tail -1
+
+# yarn
+yarn list --prod
+
+# pnpm
+pnpm list --prod
+```
+
+Report:
+
+- Total production dependency count (direct + transitive)
+- Top 5 heaviest dependencies
+- Duplicate packages (different versions of same dep)
+- Dependencies replaceable with lighter alternatives
+- devDependencies accidentally listed in dependencies
+
+## 4. Runtime Performance
+
+Static analysis pass for runtime performance issues:
+
+- **Hot-path allocations** — object/array creation inside tight loops, repeated
+  `JSON.parse`/`JSON.stringify`, unnecessary spread in iteration
+- **Missing early returns** — expensive work before guard conditions
+- **Redundant computation** — values computed multiple times when cacheable
+- **Blocking operations** — synchronous I/O, CPU-intensive loops without
+  yielding, serial `await` where parallel is safe
+- **Memory leaks** — event listeners not cleaned up, growing collections
+  without eviction, closures capturing large scopes
+- **Startup cost** — heavy top-level initialization, eager loading of
+  rarely-used modules
+
+## 5. Test Suite Performance
+
+Run tests with verbose output:
+
+```bash
+<PROJECT_TEST_CMD> -- --reporter=verbose
+```
+
+Report:
+
+- Total suite duration
+- Top 5 slowest test files
+- Top 5 slowest individual tests
+- Tests doing real I/O without mocking
+- Parallelization opportunities
+
+## 6. Database & I/O Performance
+
+If the project interacts with databases or performs significant I/O:
+
+- **Query patterns** — N+1 queries, missing indexes, unbounded queries,
+  sequential queries that could be batched
+- **Connection management** — pool sizing, connection leak risks, missing
+  timeouts
+- **Caching** — repeated identical queries without caching, stale TTLs
+- **Serialization** — excessive object transformation between layers
+
+## Findings Report
+
+Journal each finding:
+
+```
+create_entry({
+  content: "Performance finding: <severity> — <description>. File: <path>:<lines>. Expected improvement: <estimate>.",
+  entry_type: "audit_finding",
+  tags: ["commander", "performance", "<category>"],
+})
+```
+
+Produce a structured summary:
+
+| Category            | Score (A–F) | Findings | Critical |
+| ------------------- | ----------- | -------- | -------- |
+| Build Performance   |             |          |          |
+| Bundle & Output     |             |          |          |
+| Dependency Weight   |             |          |          |
+| Runtime Performance |             |          |          |
+| Test Suite Speed    |             |          |          |
+| Database & I/O      |             |          |          |
+
+Assign an **overall performance score (A–F)** and list the top 3 highest-impact
+improvements.
+
+## HITL Checkpoint
+
+Present findings to the human. Wait for approval before applying any fixes.
+
+## Apply Fixes
+
+After approval:
+
+1. Apply fixes in impact order (highest improvement first)
+2. Run validation gates
+3. Update changelog
+4. Commit