Help us improve
Share bugs, ideas, or general feedback.
From session-orchestrator
Aggregates cross-repo health signals from vault-registered GitLab/GitHub projects into a single _PORTFOLIO.md dashboard. Runs on demand or at session-start when enabled.
npx claudepluginhub kanevry/session-orchestrator --plugin session-orchestratorHow this skill is triggered — by the user, by Claude, or both
Slash command
/session-orchestrator:gitlab-portfoliosonnetThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Aggregates cross-repo health signals from vault-registered projects into a single `_PORTFOLIO.md` dashboard — idempotent, opt-in, and `_generator`-marked.
Creates or updates timestamped GitHub portfolio Markdown files by fetching and analyzing repository READMEs and structure via /github-portfolio <repo-url>. Use for career documentation snapshots.
Single source of truth for VCS operations on GitLab and GitHub repos — creating/updating/closing issues and MRs, resolving project IDs, and running glab/gh CLI commands. Consuming skills reference this rather than duplicating logic.
Runs nightly vault maintenance: fixes broken wiki-links, detects orphan pages, syncs directory indexes, and flags stale GitHub issue tasks.
Share bugs, ideas, or general feedback.
Aggregates cross-repo health signals from vault-registered projects into a single
_PORTFOLIO.mddashboard — idempotent, opt-in, and_generator-marked.
gitlab-portfolio gives you a single-pane view of your entire project portfolio. It iterates all vault-registered repositories, dispatches parallel CLI calls to glab / gh, and writes a structured Markdown dashboard at <vault-dir>/01-projects/_PORTFOLIO.md. The result is a living status snapshot — updated on demand or at session-start — that never overwrites hand-edited files.
/portfolio.--dry-run preview before committing a refresh to the vault.gitlab-ops for write operations./discovery or direct glab commands._overview.md or .vault.yaml) — unregistered repos are silently skipped._PORTFOLIO.md — the _generator guard prevents overwriting human content.Implementation: scripts/lib/gitlab-portfolio/aggregator.mjs — discoverRepos().
Iterates <vault-dir>/01-projects/*/ subdirectories:
_overview.md YAML frontmatter. Look for gitlab: <namespace/repo> and/or github: <owner/repo>. Both keys may be present on a single repo._overview.md is absent or missing those keys, read .vault.yaml at the project root: spec.links.gitlab / spec.links.github.Output is an array of RepoDescriptor objects: { slug, gitlab, github }.
Implementation: scripts/lib/gitlab-portfolio/aggregator.mjs — aggregateAll(repos, config).
All repos are fetched in parallel via Promise.allSettled. Per-repo CLI dispatch:
# GitLab
glab issue list --repo <namespace/repo> --state opened --output json
glab mr list --repo <namespace/repo> --state opened --output json
# GitHub
gh issue list --repo <owner/repo> --state open --json number,title,labels,createdAt,updatedAt,milestone
gh pr list --repo <owner/repo> --state open --json number,title,labels,createdAt,updatedAt
Per-repo summary fields derived from JSON output:
| Field | Derivation |
|---|---|
openIssues / openMRs | array lengths |
critical | issues where any label matches critical-labels (case-insensitive) |
stale | issues where updatedAt older than stale-days days |
nextMilestone | earliest non-null milestone.title across open issues |
lastActivity | max updatedAt across all issues + MRs |
topIssues | first 3 open issues sorted by createdAt ascending (oldest open first) |
On CLI failure per repo: behaviour is controlled by mode (see Error Handling).
Implementation: scripts/lib/gitlab-portfolio/markdown-writer.mjs — renderDashboard(summaries, config).
Output path: <vault-dir>/01-projects/_PORTFOLIO.md. Frontmatter keys: _generator: session-orchestrator-gitlab-portfolio@1, created (ISO8601, set once), updated (ISO8601, refreshed each write), repos (count). Atomic write: content built in memory, committed via a single writeFileSync.
parseFrontmatter and emitAction imported from scripts/lib/vault-mirror/utils.mjs. Rules:
created._generator absent or differs → skipped-handwritten (never overwrite human content).updated ≤ fresh data → updated.updated > fresh data → skipped-noop.Stdout action shape: {"action":"updated","path":"01-projects/_PORTFOLIO.md","repos":16,"critical":3}
Opt-in via the gitlab-portfolio: block in Session Config (CLAUDE.md / AGENTS.md):
gitlab-portfolio:
enabled: true
mode: warn # warn | strict | off
stale-days: 30
critical-labels: ["priority:critical", "priority:high"]
| Field | Default | Meaning |
|---|---|---|
enabled | false | Master switch. |
mode | warn | warn / strict / off — failure handling; off ≡ disabled. |
stale-days | 30 | Issues older than N days are flagged stale. |
critical-labels | ["priority:critical","priority:high"] | Label substrings that classify an issue as critical (case-insensitive). |
--vault-dir validation (SEC, GH #44). The --vault-dir CLI argument and vault-integration.vault-dir Session Config value are validated against the user's home directory via validatePathInsideProject (scripts/lib/path-utils.mjs). Both phases apply:
.. traversal that resolve outside os.homedir() are rejected (exit 2).os.homedir() are rejected (exit 2).Configure vault-integration.vault-dir only with user-controlled paths under ~. The same guard applies to the implicit Phase 2.7 portfolio snapshot at session-start. Reference: CWE-22 path traversal · .claude/rules/security.md SEC-014 adjacent guidance.
Note: vault-dir must be a CHILD of ~ (the home directory), not ~ itself. The guard uses strict isPathInside semantics, which require a proper descendant path.
node scripts/lib/gitlab-portfolio/aggregator.mjs \
--vault-dir ~/Projects/vault \
[--dry-run]
| Flag | Required | Description |
|---|---|---|
--vault-dir | yes | Absolute path to Meta-Vault root. Must exist. |
--dry-run | no | Run discovery + aggregation; print diff to stdout; do not write the dashboard. |
Exit codes: 0 success · 1 bad args/config · 2 vault-dir not found or write failed · 3 repo fetch failures in strict mode.
When gitlab-portfolio.enabled: true and vault-integration.enabled: true, session-start Phase 2 invokes the aggregator in parallel with ecosystem-health. The hook always runs in warn mode — session-start must not block on non-fatal failures. On critical issues found, a banner is emitted:
🔴 Portfolio: 3 critical issues across 2 repos — run /portfolio for details
---
_generator: session-orchestrator-gitlab-portfolio@1
created: 2026-05-16T08:00:00Z
updated: 2026-05-16T08:00:00Z
repos: 2
---
# Portfolio Dashboard
> Generated: 2026-05-16 08:00 UTC · 2 repos · 1 critical · 0 stale
## Summary
| Repo | Open Issues | Open MRs | Critical | Stale | Last Activity |
|---|---|---|---|---|---|
| session-orchestrator | 9 | 2 | 1 | 0 | 2026-05-16 |
| my-saas-app | 4 | 1 | 0 | 0 | 2026-05-15 |
## session-orchestrator
**gitlab:** `kanevry/session-orchestrator` · Open: 9 issues / 2 MRs · Critical: 1 · Next milestone: v3.7
| # | Title | Labels | Updated |
|---|---|---|---|
| #41 | gitlab-portfolio skill | enhancement | 2026-05-16 |
| #42 | session-end echo-stub | bug | 2026-05-14 |
| #35 | superpowers adoption | enhancement | 2026-05-10 |
## my-saas-app
**github:** `owner/my-saas-app` · Open: 4 issues / 1 PR · Critical: 0
Behaviour is governed by mode. warn: emit warning to stderr, continue with partial data; repo rows show (fetch failed). strict: any repo fetch failure or missing vault-dir exits 3 immediately. off: all errors are silently swallowed, partial data written.
--vault-dir not found and write errors always exit 2 regardless of mode. _PORTFOLIO.md with no _generator key always results in skipped-handwritten (all modes). No repos discovered: warn → exit 0 (no file written); strict → exit 3.
glab calls — always use Promise.allSettled; sequential calls time out on large portfolios._generator before overwriting.critical-labels from config.warn mode.created on refresh — created is set once; only updated changes._generator: session-orchestrator-gitlab-portfolio@1 MUST appear in every file written by this skill.<vault-dir>/01-projects/_PORTFOLIO.md. No other path is valid.Promise.allSettled is mandatory — one failing repo must never abort the entire run.writeFileSync.scripts/lib/gitlab-portfolio/aggregator.mjs (discovery + aggregation) · scripts/lib/gitlab-portfolio/markdown-writer.mjs (rendering + idempotency) · shared helpers from scripts/lib/vault-mirror/utils.mjs.