Discover

Front door for "I want HQ to know this repo." Acquires the repo at latest main, fans out parallel exploration, writes structured knowledge under the owning company (or standalone), and proposes scoped policies for crystal-clear conventions only. Phased ceremony with explicit gates — inspired by gstack.

Input

$ARGUMENTS may be:

• https://github.com/<org>/<name> or git@github.com:<org>/<name>.git
• <org>/<name> shorthand
• An absolute local path to an existing checkout

Optional flags: --company <slug>, --private, --no-policies.

Phase 1 — Acquire (idempotent)

Input shape	Action
Full git URL	Use as-is
<org>/<name> shorthand	Expand to https://github.com/<org>/<name>
Absolute local path	Skip clone; verify .git/ exists

1. Detect visibility + default branch:

   gh repo view <org>/<name> --json visibility,defaultBranchRef,owner,description,primaryLanguage
   

   Skip if already a local path.
2. Pick target: repos/public/<name> (PUBLIC) or repos/private/<name> (PRIVATE). --private forces private placement.
3. Clone (if absent):

   git clone --depth=50 --no-single-branch <url> repos/{pub|priv}/<name>
   

   Shallow is sufficient for discovery.
4. Sync (if present):
   • git -C <path> status --porcelain — bail loudly if dirty (NEVER reset --hard)
   • git -C <path> fetch origin
   • git -C <path> checkout <default_branch>
   • git -C <path> pull --ff-only
5. Capture head_sha, last_commit (ISO), file count, line count.

Phase 2 — Register (auto-detect company; never ask if any tier resolves)

Resolve owning company in priority order:

Tier	Source	Win condition
1	--company <slug> flag	Always wins if present
2	Active session: bash core/scripts/handoff-pointer-company.sh (reads workspace/threads/handoff.json .company, accepting a string, a one-element array, or the linked thread's metadata.company for older pointers), or $HQ_ACTIVE_COMPANY	Use if non-empty and present in companies/manifest.yaml
3	GitHub org match: owner login → companies/{co}.github_org in manifest	Single match auto-uses; multiple → AskUserQuestion
4	Path heuristic: target lives under companies/<co>/repos/...	Infer that company
5	Standalone	Knowledge writes to core/knowledge/public/repos/<name>/; manifest gets unaffiliated_repos[] append

Then:

1. Update companies/manifest.yaml: append target path to {company}.repos[] (idempotent, sorted, no-op if present). For standalone: append to top-level unaffiliated_repos[].
2. Register qmd collection:

   qmd collection add <path> --name <name> --mask "**/*.md" 2>/dev/null || true
   

3. Drift gate: if the repo path already exists under a different company, STOP and surface via AskUserQuestion before overwriting.

Phase 3 — Fan-out exploration (parallel Agent calls, subagent_type=Explore)

Spawn these IN A SINGLE MESSAGE so they run concurrently. Each returns ≤500 words under fixed headings — orchestrator collates, does NOT re-read source files.

Agent	Brief
Stack & architecture	Languages, frameworks (Next/Astro/Bun/Vite/Hono/Expo/etc.), entry points, package manager (lockfile-detected), build/test/lint commands, deploy target. Read package.json, pyproject.toml, Cargo.toml, go.mod, top-level configs.
Environment & services	.env.example keys grouped by external service (Stripe, Clerk, Vercel, AWS, Shopify, etc.). Cross-link to companies/{co}.services[] in manifest.
Conventions & operations	Test strategy (unit/E2E presence), CI workflows under .github/workflows/, branching/PR rules from CONTRIBUTING.md / README, husky/lefthook hooks, .editorconfig, .prettierrc.
Domain & purpose (skip if README < 30 lines)	What the product does, who it serves, public docs links, top-level modules.

Phase 4 — Synthesize knowledge

Target dir:

• Company-owned: companies/<co>/knowledge/repos/<name>/
• Standalone: core/knowledge/public/repos/<name>/

Write four files (overwrite on re-run; they're regenerated artifacts):

• overview.md — purpose, stack summary, scale signals (file/line counts, contributors), default branch + last-commit ISO
• architecture.md — entry points, top-level layout, key dependencies
• environment.md — env-var table, external services, links to manifest service entries
• conventions.md — test/lint/build commands, CI summary, branch model

Knowledge frontmatter (every file):

---
type: reference
domain: [engineering]
status: canonical
tags: [repo:<name>, discovered]
source: discover
generated_at: <ISO-8601 UTC>
head_sha: <sha>
relates_to: []
---

Phase 5 — Propose policies (conservative, user-gated)

Skip entirely if --no-policies. Otherwise propose ONLY when signal is unambiguous:

Signal	Draft rule
pnpm-lock.yaml exists, no package-lock.json / yarn.lock / bun.lock	Use pnpm; do not generate other lockfiles
bun.lock exists	Use bun
Husky pre-commit runs lint/typecheck/tests	Pre-commit hook is authoritative; do not pass --no-verify
Single .github/workflows/deploy*.yml with explicit deploy command	Deploy via <workflow> only; no manual vercel deploy / netlify deploy
engines.node pin in package.json, or .nvmrc, or .python-version	Use <version> for this repo

Scope auto-decision (no prompt unless ambiguous):

Heuristic	Scope chosen
Signal references repo-unique paths/workflows/scripts	repo → repos/{pub|priv}/<name>/.claude/policies/<id>.md
Same signal present in ≥2 sibling repos under {company}.repos[] (read-only, cap at 5 siblings)	company → companies/<co>/policies/<id>.md
Standalone repo (no company)	repo always
Tied / unclear	Default repo (narrower wins; widen later via /learn or /garden)

For each candidate, present via AskUserQuestion with options: Write, Edit then write, Skip. Never auto-write without confirmation.

Policy frontmatter (per core/knowledge/public/hq-core/policies-spec.md):

---
id: <scope-prefix>-<slug>          # e.g. <repo>-pnpm-only, <co>-pre-commit-authoritative
title: <short title>
scope: repo | company
trigger: <when this applies>
enforcement: soft                   # discover never produces hard policies — let user upgrade later
version: 1
created: <YYYY-MM-DD>
updated: <YYYY-MM-DD>
public: false                       # all discover-generated policies start private
source: discover
learned_from: discover/<repo>@<head_sha_short>
---

If ≥1 policy was written, stop — digests are retired. The next session will pick up new policies via inject-policy-on-trigger (SessionStart). Do not run build-policy-digest.sh (script removed).

Phase 6 — Index & report

1. qmd update 2>/dev/null || true
2. Print summary table:
   • Repo path, head SHA, default branch
   • Files written (count + paths)
   • Policies written (count + scopes)
   • Manifest changes (none / <co>.repos[] += / unaffiliated_repos[] +=)
3. Suggest next: /run dev-team context-manager for deeper analysis, or /prd to start a project against this repo.

Idempotence guarantees

Re-run behavior	Phase
Latest main pulled (no-op if up to date)	1
No manifest churn if already registered	2
Knowledge files overwritten with fresh generated_at + head_sha	4
Policies skipped if a file with same id already exists	5

Out of scope

• Auto-writing CLAUDE.md inside the discovered repo (user runs /init if desired)
• Spawning workers for the repo (/newworker)
• Branches other than default
• Cross-repo dependency graphs

Safety

• Never git reset --hard, never --force push, never delete files in target repo.
• Working-tree dirty in an existing clone → bail with a clear "stash or commit first" message.
• Drift between proposed and existing manifest entries → AskUserQuestion before overwrite.
• All proposed policies are enforcement: soft and public: false — the user explicitly upgrades later.