oss-scout: Instructions file for Claude Code

CLAUDE.md

Project Overview

oss-scout is a standalone tool for finding open source issues personalized to your contribution history. Ships as CLI, library, MCP server, and Claude Code plugin. Published as @oss-scout/core and @oss-scout/mcp on npm.

Architecture

pnpm monorepo with two packages:

1. packages/core (@oss-scout/core) — Library + CLI. Multi-strategy search engine, issue vetting, viability scoring, and the OssScout public API class.

2. packages/mcp-server (@oss-scout/mcp) — MCP server exposing search, scout-features, vet, skip, config, config-set, and sync tools plus scout:// resources.

Key Design Decisions

• No singletons in public API. OssScout accepts config via constructor injection. Implements ScoutStateReader to bridge state with the search engine.
• Two persistence modes: 'gist' (standalone, state in private GitHub gist) and 'provided' (library, caller provides state — used by OSS Autopilot).
• Extracted from OSS Autopilot. Search modules refactored to remove StateManager singleton. OSS Autopilot imports @oss-scout/core as a dependency.
• 4-phase search with configurable strategy selection (merged, starred, broad, maintained).
• Error strategy: Auth/rate-limit errors propagate. Cache/filesystem errors degrade gracefully with warn logging. Documented in errors.ts.

File Structure

packages/core/src/
├── index.ts              # Public API exports
├── scout.ts              # OssScout class + createScout() factory
├── cli.ts                # Commander CLI (10 top-level commands)
├── commands/             # CLI subcommands
│   ├── setup.ts          # Interactive first-run configuration
│   ├── config.ts         # View/update preferences
│   ├── search.ts         # Multi-strategy search with result persistence
│   ├── features.ts       # Feature opportunities in anchor repos
│   ├── sync.ts           # Reconcile tracked open PRs (merged/closed)
│   ├── vet.ts            # Single issue vetting
│   ├── vet-list.ts       # Batch re-vetting of saved results
│   ├── skip.ts           # Manage the skip list
│   ├── results.ts        # View/clear saved search results
│   ├── command-scout.ts  # Build a scout honoring the persistence preference
│   ├── with-scout.ts     # Shared create/persist scaffolding for commands
│   └── validation.ts     # URL validation helpers
├── core/                 # Domain logic
│   ├── schemas.ts        # Zod schemas for ScoutState, ScoutPreferences
│   ├── types.ts          # Ephemeral types, config interfaces
│   ├── issue-discovery.ts # 4 extracted phase functions + orchestrator
│   ├── issue-vetting.ts  # Parallel vetting pipeline + ScoutStateReader/Writer
│   ├── issue-eligibility.ts # PR existence, claim detection, requirements
│   ├── issue-scoring.ts  # Viability scoring (pure functions, 0-100)
│   ├── issue-filtering.ts # Spam detection, doc-only filtering
│   ├── anti-llm-policy.ts # Detect repos with anti-AI contribution policies
│   ├── feature-discovery.ts # `scout features` anchor + broad discovery
│   ├── personalization.ts # preferLanguages/preferRepos sort boosts + diversity
│   ├── linked-pr.ts      # Stalled linked-PR detection (revive opportunities)
│   ├── roadmap.ts        # ROADMAP.md issue-reference scraping
│   ├── slm-triage.ts     # Optional Ollama SLM pre-triage during vetting
│   ├── preference-fields.ts # Shared config-set field map (CLI + MCP)
│   ├── search-phases.ts  # Search helpers, caching, batched search
│   ├── search-budget.ts  # Rate limit management (30 req/min sliding window)
│   ├── issue-graphql.ts  # GraphQL broad search + batched merged-PR prefetch
│   ├── repo-health.ts    # Project health checks, CONTRIBUTING.md parsing
│   ├── probe-repo-file.ts # Cheap existence probes for repo files
│   ├── category-mapping.ts # Project categories → GitHub topics
│   ├── github.ts         # Throttled Octokit client
│   ├── http-cache.ts     # ETag response caching, in-flight deduplication
│   ├── gist-state-store.ts # Gist-backed persistence with conflict resolution
│   ├── local-state.ts    # Local file persistence (~/.oss-scout/state.json)
│   ├── bootstrap.ts      # First-run: fetch starred repos + PR history
│   ├── utils.ts          # URL parsing, token detection, extractRepoFromUrl
│   ├── logger.ts         # Debug/info/warn logger (stderr)
│   ├── errors.ts         # Error hierarchy + strategy documentation
│   └── pagination.ts     # Auto-pagination helper
├── formatters/
│   ├── json.ts           # JSON output formatter (--json envelope)
│   ├── human.ts          # Human-readable terminal output
│   └── markdown.ts       # Markdown output (results --markdown; used by action.yml)
├── e2e/
│   └── search-flow.test.ts # End-to-end search flow (only Octokit mocked)
└── eval/                 # Vet eval suite (eval:vet scripts; excluded from dist)

packages/mcp-server/src/
├── index.ts              # Library entry: createServer wiring (side-effect free)
├── bin.ts                # Stdio executable entry point
├── tools.ts              # 7 tools: search, scout-features, vet, skip, config, config-set, sync
└── resources.ts          # 3 resources: scout://config, results, scores

Plugin (repo root):
├── commands/scout.md, scout-setup.md
├── agents/issue-scout.md, repo-evaluator.md
├── skills/oss-search/SKILL.md
├── hooks/                # hooks.json + session-start, git guard, auto-format
├── .claude-plugin/       # plugin.json, marketplace.json
├── action.yml            # Composite GitHub Action (scheduled digest issue)
└── examples/             # Example workflows (weekly digest)