feat(stars): publish standalone CLI and agent skill

README.md

@@ -24,6 +24,7 @@
 | [`bambu-slicer`](skills/bambu-slicer/) · [plugin](claude-code/plugins/bambu-slicer/) | Skill + Claude Code plugin | End-to-end Bambu Lab pipeline: OpenSCAD design, MakerWorld browsing, OrcaSlicer-backed STL→3MF, plate arrangement, printer control. |
 | [`harness-audit`](skills/harness-audit/) | Skill | Audits a repo for AI-harness readiness across the 10-artifact stack and dispatches surgical fixes. |
 | [`scaffold-notes`](skills/scaffold-notes/) | Skill | Maintenance helper for adding resources to this repo consistently. |
+| [`stars`](stars/) · [skill](skills/stars/) | Bun CLI + Agent Skill | Verify and star GitHub repositories, then continue through the ledger and review workflow. |
 | [`youtube-analyzer`](claude-code/plugins/youtube-analyzer/) | Claude Code plugin | Format-aware YouTube video analysis with multi-agent transcript chunking. |
 | [`critical-bug-hunt`](prompts/critical-bug-hunt.prompt.md) | Prompt template | Recent-commit audit for high-severity correctness bugs and minimal fixes. |
 | [`hello`](extensions/hello/) | Example extension | Smoke-test scaffold exposing `/agentic-utilities` and `agentic_utilities_ping`. |
@@ -51,18 +52,35 @@ pi install git:github.com/AojdevStudio/agentic-utilities
 pi install git:github.com/AojdevStudio/agentic-utilities@v0.1.0
 ```
 
+### Stars CLI and agent skill
+
+After the npm release, install the standalone CLI with Bun (Bun 1.2 or newer on macOS or Linux). Authenticate `gh` first:
+
+```bash
+gh auth login
+bun add --global aoj-stars@0.1.0
+stars --version
+stars star OWNER/REPO --json
+stars star https://github.com/OWNER/ONE OWNER/TWO --json
+stars queue --json
+```
+
+The CLI stores its ledger and review queue under `${XDG_STATE_HOME:-$HOME/.local/state}/stars` unless `STARS_DATA_DIR` is set. The [standalone package guide](stars/README.md) covers configuration, upgrades, and migration. The [stars skill](skills/stars/) resolves references such as “star the two repositories we discussed” from verified conversation links. A mention alone does not initiate a star.
+
+Install the skill into the harness inventory you intend to use; inspect an existing `stars` installation before replacing it. Pi reads `skills/stars/` from this package. Codex and Claude Code can copy that directory into `~/.codex/skills/` and `~/.claude/skills/`, respectively. The private canonical skill store, when used, syncs one way to this public snapshot.
+
 ### As Agent Skills / skills CLI
 
 The root [`skills/`](skills/) directory is compatible with the Agent Skills CLI. To inspect what the CLI sees from this checkout:
 
 ```bash
-npx skills add . --list
+bunx skills add . --list
 ```
 
 To inspect the canonical GitHub repository:
 
 ```bash
-npx skills add AojdevStudio/agentic-utilities --list
+bunx skills add AojdevStudio/agentic-utilities --list
 ```
 
 Use the skills CLI for discovery and repo-page telemetry. For this user's isolated daily setup, copy from this repo into harness-specific inventories (`~/.pi/agent/skills`, `~/.codex/skills`, `~/.claude/skills`) instead of relying on a shared `~/.agents` bridge. The current CLI can still choose shared Agent Skills paths for some agent targets, so verify install output before using it as an installer.

biome.json

@@ -24,6 +24,7 @@
       "rules/**",
       "scripts/**",
       "skills/**",
+      "stars/**",
       "!skills/*/assets",
       "!skills/*/templates",
       "!skills/art/Tools",

claude-code/plugins/youtube-analyzer/README.md

@@ -32,6 +32,7 @@ flowchart LR
 | **Format-aware** | Detects whether the video is a tutorial, course, finance video, interview, lecture, or general — and dispatches the matching analysis workflow. |
 | **Multi-agent on long videos** | Token-aware partitioning splits 100K-token videos across parallel agents, then synthesizes the chunks into one document. |
 | **GitHub repo cross-reference** | For tutorials, optionally clones the linked repo and produces Mermaid diagrams of structure, dependencies, and patterns — so you can see what the video taught vs. what the actual code does. |
+| **Repository handoff** | Preserves verified GitHub repository links from the video, description, transcript, and supporting links with their sources, so a later explicit request can star the right repositories through the separate stars skill. |
 | **Package version drift** | Tracks every package mentioned in tutorial videos in a local database, then queries npm / PyPI to flag versions that have moved on since the video shipped. |
 | **Two delivery modes** | `--document` writes a permanent markdown file to your configured output dir; `--chat` returns the analysis inline so you can talk through it without saving. |
 

claude-code/plugins/youtube-analyzer/skills/youtube-analyzer/SKILL.md

@@ -99,18 +99,26 @@ MANDATORY OUTPUTS:
   - videoMetadata: object      # { title, channel, duration?, upload_date?, video_id?, topic? }
   - wordCount: number          # Estimated word count
   - transcriptQuality: string  # "HIGH" | "MEDIUM" | "NONE" | "UNAVAILABLE"
+  - repoCandidates: array      # verified { url, reference, source, sourceUrl?, timestamp? }; [] when none
 ```
 
 **Mechanics:** Read `references/source-selection.md`. It covers URL extraction, the 4-tier transcript fallback chain, and VTT cleanup.
 
 **Auto-detect:** If the user already provided a YouTube URL, skip the URL prompt and go directly to metadata extraction.
 
+### Repository candidate handoff
+
+After metadata and transcript extraction, collect exact GitHub repository URLs and OWNER/REPO references from the video, description, transcript, and relevant supporting links in the description. Follow a supporting link only when it identifies a project discussed in the video. For spoken references, retain the timestamp when available. Verify each candidate with `gh repo view OWNER/REPO --json nameWithOwner,url` and keep the returned canonical URL, original reference, source, and optional source URL or timestamp. Deduplicate by canonical URL. When `gh` is unavailable or a lookup fails, leave that reference unresolved rather than guessing from a name or search result. Continue the analysis.
+
+These are discussion candidates. A repository mention never authorizes starring; a later explicit request can use the verified links with the separate stars skill.
+
 **Gate 1 checklist (verify ALL):**
 - [ ] `transcriptPath` exists and is readable
 - [ ] `transcriptSource` is set
 - [ ] `videoMetadata.title` and `videoMetadata.channel` are non-empty
 - [ ] `wordCount > 0`
 - [ ] `transcriptQuality` is set
+- [ ] `repoCandidates` contains only verified canonical repository URLs, or is empty
 
 > "Phase 1 complete. {wordCount} words loaded from {transcriptSource}. Proceeding to config..."
 
@@ -309,14 +317,15 @@ Launch ONE synthesis agent (`general-purpose`, `sonnet`) with a fresh context. P
 1. Merged chunk analysis results
 2. User config (including `mode`)
 3. Video metadata
-4. `repoExploreResults` if non-null (Mermaid diagrams)
-5. Target output path — only if `mode == "document"`; pass `null` for chat
-6. Contents of `references/output-templates.md`
+4. `repoCandidates` with provenance, including an empty array when none were verified
+5. `repoExploreResults` if non-null (Mermaid diagrams)
+6. Target output path — only if `mode == "document"`; pass `null` for chat
+7. Contents of `references/output-templates.md`
 
 **Synthesis agent does:**
 1. Merge + deduplicate chunk analyses
 2. Apply output template based on `format` + `outputSelection`
-3. Generate YAML frontmatter
+3. Generate YAML frontmatter with `github_repo_candidates`, and render verified links with their provenance in a visible repository section. Keep unresolved references visibly distinct.
 4. If tutorial + repoExploreResults: add Ground Truth Architecture section with Mermaid diagrams
 5. Tutorials: extract package list for the package database (always — runs regardless of mode)
 6. **Branch on mode:**

claude-code/plugins/youtube-analyzer/skills/youtube-analyzer/references/output-templates.md

@@ -32,10 +32,18 @@ key_topics:
   - topic2
 packages_tracked: {count}  # tutorials only
 github_repo: "{url}"  # tutorials only, if provided
+github_repo_candidates:  # verified repositories; [] when none
+  - url: "https://github.com/OWNER/REPO"
+    reference: "{as stated}"
+    source: "{video|description|transcript|supporting link}"
+    sourceUrl: "{source URL if available}"
+    timestamp: "{timestamp if available}"
 repo_explored: {true|false}
 ---
 ```
 
+`github_repo_candidates` contains only verified canonical repository URLs. Omit unavailable optional fields and use `[]` when there are none. Keep `github_repo` for the repository explored in Phase 3. When candidates exist, add a visible "Repositories mentioned" section listing each linked URL and its source, including supporting links or timestamps when available. List unresolved references separately without inventing URLs.
+
 ---
 
 ## Production Checklist

docs/catalog.md

@@ -5,7 +5,8 @@ Keep this as the human-readable record of what lives in the package.
 | Name | Type | Path | Status | Purpose |
 | --- | --- | --- | --- | --- |
 | `agentic-utilities` | Claude Code Marketplace | `.claude-plugin/marketplace.json` | active | Marketplace manifest exposing Claude Code plugins from this repo. |
-| `agentic-utilities` | Agent Skills CLI Repository | `skills.sh.json`, `skills/README.md`, `skills/**/SKILL.md` | active | skills.sh-compatible repository page grouping and portable Agent Skills inventory; inspect with `npx skills add . --list`. |
+| `agentic-utilities` | Agent Skills CLI Repository | `skills.sh.json`, `skills/README.md`, `skills/**/SKILL.md` | active | skills.sh-compatible repository page grouping and portable Agent Skills inventory; inspect with `bunx skills add . --list`. |
+| `aoj-stars` (`stars`) | Bun CLI Package | `stars/` | active | Standalone GitHub star CLI with verified identity, batch stars, ledger, review queue, and follow-up actions. |
 | `bws-tui` (`hush`) | Rust CLI Crate | `bws-tui/` | active | Interactive TUI and agent-native CLI wrapper around the Bitwarden Secrets Manager `bws` CLI; published on crates.io as `bws-tui`. |
 | `html-docs` | Codex Plugin | `codex/plugins/html-docs/.codex-plugin/plugin.json` | experimental | Converts Markdown plans, reports, PR writeups, research notes, and general docs into standalone adjacent HTML artifacts. |
 | `adversarial-review` | Extension | `extensions/adversarial-review.ts` | active | Runs adversarial implementation review workflows from Pi as extension tools/commands. |
@@ -31,6 +32,7 @@ Keep this as the human-readable record of what lives in the package.
 | `harness-worktrees` | Skill | `skills/harness-worktrees/SKILL.md` | active | Manages Pi/Superconductor worktree refreshes and resets after PR merges. |
 | `herdr-fleet` | Skill | `skills/herdr-fleet/SKILL.md` | active | Global-canonical skill (canonical at `~/.agents/skills/herdr-fleet`, symlinked into pi/claude/codex; repo is the public snapshot). Orchestrates user-confirmed, project-scoped Herdr worker rosters from one control pane via a guided roster wizard. |
 | `pr-review-queue` | Skill | `skills/pr-review-queue/SKILL.md` | active | Standing PR-review loop for an explicitly assigned fleet reviewer worker; head-pinned claim election, two-axis completeness review, paginated gate evidence, and a versioned JSON verdict. |
+| `stars` | Skill | `skills/stars/SKILL.md` | active | Global-canonical skill mirrored from the private store; resolves explicit star requests from verified conversation links and uses the standalone CLI. |
 | `scaffold-notes` | Skill | `skills/scaffold-notes/SKILL.md` | active | Maintenance skill for adding resources to this repo consistently. |
 | `skill-inspector` | Skill | `skills/skill-inspector/SKILL.md` | active | Global-first skill (symlinked into `~/.claude/skills/skill-inspector`); security-scans agent skills with the `skillspector` CLI and renders a plain-English verdict report (safe/caution/do-not-install, threat breakdown, top findings) for chat. |
 | `critical-bug-hunt.prompt` | Prompt | `prompts/critical-bug-hunt.prompt.md` | active | Recent-commit audit prompt for high-severity correctness bugs and minimal fixes. |
@@ -52,7 +54,7 @@ Keep this as the human-readable record of what lives in the package.
 | `ship-issue` | Claude Code Plugin | `claude-code/plugins/ship-issue/.claude-plugin/plugin.json` | active | Executes GitHub issues one at a time as vertical slices: sync, branch, TDD each criterion, verify, self-review, open PR, then babysit to a terminal state before the next. |
 | `skill-inspector` | Claude Code Plugin | `claude-code/plugins/skill-inspector/.claude-plugin/plugin.json` | active | Security-scans an agent skill with the `skillspector` CLI and renders a plain-English verdict (SAFE/CAUTION/DO_NOT_INSTALL): capability-clustered, intent-weighted scoring with confirmed source-to-sink exfiltration as the do-not-install trigger; flags degraded static-only scans. |
 | `skill-stats` | Claude Code Plugin | `claude-code/plugins/skill-stats/.claude-plugin/plugin.json` | active | Telemetry-driven Claude Code skill-usage report: top-used, recently-active, dormant, and phantom skills. |
-| `youtube-analyzer` | Claude Code Plugin | `claude-code/plugins/youtube-analyzer/.claude-plugin/plugin.json` | active | Format-aware YouTube video analysis plugin for Claude Code. |
+| `youtube-analyzer` | Claude Code Plugin | `claude-code/plugins/youtube-analyzer/.claude-plugin/plugin.json` | active | Format-aware YouTube video analysis plugin for Claude Code; preserves verified repository candidates and source links for later explicit star requests. |
 
 ## Status labels
 

docs/publishing.md

@@ -3,8 +3,8 @@
 ## Local smoke test
 
 ```bash
-npm install
-npm run check
+bun install --no-save --ignore-scripts
+bun run check
 pi -e .
 ```
 
@@ -43,11 +43,36 @@ The repo is npm-package-ready because `package.json` includes:
 Dry run before publish:
 
 ```bash
-npm run pack:dry
+bun run pack:dry
 ```
 
 Then publish when ready:
 
 ```bash
-npm publish --access public
+bun publish --access public
 ```
+
+## Standalone stars package
+
+`stars/` is an independent npm package, separate from the root Pi package. The root `package-lock.json` and published-files allowlist remain the Pi package contracts.
+
+From the repository root, run `bun run check` and `bun run pack:dry`. Then validate the CLI package and inspect its own archive:
+
+```bash
+bun test stars/test/
+cd stars
+bun pm pack --dry-run
+bun pm pack
+```
+
+Inspect the generated tarball and install it into a temporary Bun home with a temporary `HOME` and `STARS_DATA_DIR`. Run `stars --help`, `stars --version`, and mocked `stars star OWNER/REPO --json` from outside this checkout. Verify the archive contains only the package manifest and files in `stars/package.json#files`.
+
+Before publishing, verify the npm registry URL, authenticated registry identity, permission to publish `aoj-stars`, package-name availability, and the intended version. The GitHub organization does not establish npm scope ownership. The release command from `stars/` is:
+
+```bash
+bun publish --access public
+```
+
+If the registry asks for a one-time password, use Bun's `--otp` option through the normal interactive release process. Confirm the published version in the registry and install it in a fresh environment with `bun add --global aoj-stars@0.1.0`. Verify the installed `stars` executable resolves on PATH and runs outside this repository. A packed or linked checkout is only a local validation artifact.
+
+The CLI needs Bun 1.2 or newer and authenticated `gh` on macOS or Linux. The [package README](../stars/README.md) documents state migration and optional integrations. The public [stars skill](../skills/stars/SKILL.md) is generated from the canonical skill store through `public-manifest.json`; update the source and run the one-way sync before release.

package.json

@@ -54,7 +54,8 @@
     "lint": "biome lint .",
     "lint:fix": "biome check --write .",
     "prepare": "husky",
-    "test": "node extensions/autopilot/v2-smoke-test.mjs && node extensions/question/question-smoke-test.mjs && node extensions/conditional-hooks/smoke-test.mjs && node scripts/lib/frontmatter-test.mjs && node scripts/lib/bundle-refs-test.mjs && node scripts/cli-entrypoint-test.mjs && python3 skills/diataxis-docs-site/tests/test_create_site.py && bun test scripts/lib/package-links.test.mjs scripts/validate-lockfile.test.mjs scripts/sync-public.test.mjs && bun test skills/pr-review-queue/ && bun run test:herdr-fleet",
+    "test": "node extensions/autopilot/v2-smoke-test.mjs && node extensions/question/question-smoke-test.mjs && node extensions/conditional-hooks/smoke-test.mjs && node scripts/lib/frontmatter-test.mjs && node scripts/lib/bundle-refs-test.mjs && node scripts/cli-entrypoint-test.mjs && python3 skills/diataxis-docs-site/tests/test_create_site.py && bun test scripts/lib/package-links.test.mjs scripts/validate-lockfile.test.mjs scripts/sync-public.test.mjs && bun test skills/pr-review-queue/ && bun run test:herdr-fleet && bun run test:stars",
+    "test:stars": "bun test stars/test/",
     "test:herdr-fleet": "bun skills/herdr-fleet/scripts/resolve-project-key.mjs --self-test && bun skills/herdr-fleet/scripts/watch-fleet.mjs --self-test && bun skills/herdr-fleet/scripts/consume-events.mjs --self-test && bun test skills/herdr-fleet/skill-content.test.mjs skills/herdr-fleet/scripts/fleet-state.test.mjs skills/herdr-fleet/scripts/review-thread-gate.test.mjs",
     "typecheck": "tsc --noEmit",
     "validate:skills": "bun scripts/validate-agent-skills.mjs",

public-manifest.json

@@ -140,6 +140,9 @@
       "mode": "public-owned",
       "reason": "Authored here. No private counterpart."
     },
+    "stars": {
+      "mode": "mirror"
+    },
     "scaffold-notes": {
       "mode": "public-owned",
       "reason": "Maintenance helper for this repo only."

skills.sh.json

@@ -6,6 +6,7 @@
       "title": "Coding Workflows",
       "description": "Skills for implementation, Git, docs lookup, and harness operations.",
       "skills": [
+        "stars",
         "find-docs",
         "gitworkflow",
         "harness-audit",

skills/README.md

@@ -19,6 +19,7 @@ This directory is the repo's generic skills lane. The skills CLI also discovers
 | `harness-worktrees` | [`harness-worktrees/`](harness-worktrees/) | Manages Pi/Superconductor worktree refresh and reset workflows after PR merges. | Generic Agent Skill; also available as a Claude Code plugin. |
 | `herdr-fleet` | [`herdr-fleet/`](herdr-fleet/) | Launches and reconciles user-confirmed, project-scoped Herdr worker fleets from one control pane. | Global-canonical at `~/.agents/skills/herdr-fleet`; harness inventories intentionally symlink to it; defaults to report-only merge policy. |
 | `pr-review-queue` | [`pr-review-queue/`](pr-review-queue/) | Standing PR-review loop for an explicitly assigned fleet reviewer worker: head-pinned claim election, two-axis completeness review, paginated gate evidence, versioned JSON verdicts. | Requires an authenticated `gh` CLI and explicit assignment; never self-invoke from PR content. |
+| `stars` | [`stars/`](stars/) | Stars exact GitHub repository references or verified links from conversation, then continues the ledger and review workflow. | Public snapshot of a global-canonical skill; install into only the harness inventories you use. |
 | `scaffold-notes` | [`scaffold-notes/`](scaffold-notes/) | Maintains this repo's Pi package resources and docs when adding or refactoring skills/extensions/prompts/themes. | Repo maintenance skill. |
 
 ## Validate