| name | portfolio-setup |
| description | Stand up centralized multi-repo, multi-person activity tracking for a team. Use when a team works across several GitHub repos and needs one place to see who did what — and a supervisor needs a manage-the-team roll-up that a single-repo activity log can't provide. Walks choosing a hub repo, writing team-portfolio.json (repos + roster + cross-repo projects), wiring the scheduled GitHub Action and the on-demand command, picking a GitHub token, and optionally enabling a hand-maintained narrative layer. |
Skill: Portfolio setup
Goal: a working centralized tracker in well under an hour. The hard truth up front —
a per-repo activity log can never see the repo next door. GitHub already attributes
every commit, PR, and issue to a person across all repos; this plugin just reads it and
rolls it up. So the design is "one small hub that pulls from GitHub," not "a log inside
each repo."
Step 0 — Decide where the hub lives
The hub is one repo that holds the config + the generated reports + the dashboard. It
does not need to be a repo anyone codes in. Options, smaller-blast-radius first:
- A dedicated
team-portfolio repo (recommended) — clean, nothing else touches it,
easy to give a supervisor read access without granting anything else.
- An existing "home base" repo the team already reads.
The repos being tracked need no changes at all — they're read through the API.
Step 1 — Write the config
Copy templates/team-portfolio.json to the hub
repo root as team-portfolio.json and edit:
repos — every owner/name to monitor (public or private).team — one entry per person: login (GitHub username), name, optional role.supervisor — optional; frames the roll-up as a manage-the-team view.projects — cross-repo projects (see the cross-repo-project-tracking skill).window_days — default lookback for the weekly tracker (7 is typical).
Never put a token in this file. It is read from the environment only.
Step 2 — Pick a token
The collector reads PORTFOLIO_TOKEN → GITHUB_TOKEN → GH_TOKEN.
| Situation | Token |
|---|
| All tracked repos are public | the Action's built-in GITHUB_TOKEN is enough |
| Any private repo, or repos in another account/org | a fine-grained PAT with read on those repos, stored as the PORTFOLIO_TOKEN secret |
Least privilege: read-only, scoped to exactly the tracked repos.
Step 3 — Automate it (scheduled + on-demand)
- Scheduled: copy
templates/portfolio-tracker.yml
into the hub repo at .github/workflows/portfolio-tracker.yml. It refreshes weekly
(Mondays) + nightly and commits the reports + dashboard back — the diff is the record.
- On-demand: run
/portfolio-refresh (or the three scripts directly) anytime you want
the current picture.
Step 4 — Verify with the sample, then go live
Prove the renderers work before any token is involved, using the bundled fixture:
PLUGIN=~/RavenClaude/plugins/team-portfolio
python3 "$PLUGIN/scripts/portfolio-report.py" --activity "$PLUGIN/templates/sample-activity.json" --out-dir /tmp/reports
python3 "$PLUGIN/scripts/portfolio-dashboard.py" --activity "$PLUGIN/templates/sample-activity.json" --out /tmp/portfolio.html
Then do a real collect against your config (Step 1) with a token in the environment.
Step 5 — Optional narrative layer
If your manager wants context beyond the raw counts (decisions, blockers, "why"), set
narrative.enabled: true and drop one *.md per note into narrative.dir (template:
templates/activity-narrative.md). The report
generator folds them into the weekly tracker under a Notes heading. Leave it off to
stay purely GitHub-driven.
What the supervisor reads
reports/weekly-tracker.md — per-person, per-repo summary for the window.reports/project-status.md — cross-repo project roll-up.portfolio.html — interactive dashboard (open locally or publish to GitHub Pages).
Anti-patterns
- Putting a token in
team-portfolio.json (it goes in env/secrets — always).
- Adding a tracking log inside each tracked repo (the original problem — it can't see
across repos; that's the whole reason for the hub).
- A PAT with org-admin scope when read-only on a handful of repos is all that's needed.
