/greppable:discover — Full Codebase Scan

Scan the project structure and generate GDL artifacts that document the codebase.

Arguments

$ARGUMENTS contains optional path or focus area:

• Empty: scan entire codebase
• Path (e.g., src/auth/): focus scan on that directory
• Description (e.g., "authentication layer"): focus scan contextually

Pre-Flight

1. Read config from .claude/greppable.local.md to determine active layers and gdl_root. If no config, use defaults: all layers enabled, gdl_root=docs/gdl.

2. Run bridge detection pre-scanner:

   bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-prescan.sh" <target_dir> --json
   

   This detects which bridge tools can generate skeletons automatically (code maps via src2gdlc, schema maps via sql2gdls/prisma2gdls/db2gdls).

3. Report scope and bridge plan:

   Scanning project structure...
   
   Bridge detection found:
     - TypeScript: 142 files → src2gdlc (automatic code maps)
     - Python: 24 files → src2gdlc (automatic code maps)
     - SQL migrations: 3 files → sql2gdls (automatic schema maps)
     - OpenAPI specs: 2 files → openapi2gdla (automatic API contracts)
     - GraphQL schemas: 1 file → graphql2gdla (automatic API contracts)
   
   Discover will:
     1. Run bridge tools for automatic skeleton generation (fast, scripted)
     2. Agent enriches skeletons with descriptions and relationships
     3. Generate architecture diagrams (.gdld) from codebase understanding
     4. Synthesize: concept anchors, overview diagram, and proposed coding rules
   
   This is a token-intensive process. Proceed? [yes / cancel]
   

4. Run bridge tools (scripted, fast): For each bridge detected by prescan, execute the recommended command with actual paths substituted:

   # Example: Code maps
   bash "${CLAUDE_PLUGIN_ROOT}/scripts/src2gdlc.sh" <target_dir> --output=<gdl_root>/code --recursive --lang=typescript
   bash "${CLAUDE_PLUGIN_ROOT}/scripts/src2gdlc.sh" <target_dir> --output=<gdl_root>/code --recursive --lang=python
   # Example: Schema maps (iterate over individual files)
   for f in <migrations_dir>/*.sql; do bash "${CLAUDE_PLUGIN_ROOT}/scripts/sql2gdls.sh" "$f" --output=<gdl_root>/schema; done
   for f in <schema_dir>/*.prisma; do bash "${CLAUDE_PLUGIN_ROOT}/scripts/prisma2gdls.sh" "$f" --output=<gdl_root>/schema; done
   # Example: API contracts
   for f in <api_dir>/*.json <api_dir>/*.yaml; do bash "${CLAUDE_PLUGIN_ROOT}/scripts/openapi2gdla.sh" "$f" --output=<gdl_root>/api; done
   for f in <schema_dir>/*.graphql; do bash "${CLAUDE_PLUGIN_ROOT}/scripts/graphql2gdla.sh" "$f" --output=<gdl_root>/api; done
   

   Track failures: if a bridge fails, log warning and continue with remaining bridges. Report both successful and failed bridges before proceeding.

5. If confirmed, delegate to the discovery-agent with full context, including which skeletons were already generated by bridges (so the agent can focus on enrichment rather than generation).

Progress Reporting

Report progress at each major stage. Use this exact format so users can track the scan:

After pre-flight:

[1/5] Pre-flight complete — N bridge(s) detected

After each bridge tool runs:

[2/5] Bridge: src2gdlc — generated N code map(s)
[2/5] Bridge: sql2gdls — generated N schema map(s)

After skeleton generation is complete:

[3/5] Skeletons complete — N artifacts generated

During AI enrichment:

[4/5] Enriching: module_name.gdlc (N of M)

After completion:

[5/5] Discovery complete — N artifacts total (X new, Y updated)

Always report progress to the user directly in your response text. Do not suppress progress updates.

Post-Discovery

1. Run bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-lint.sh" --all <gdl_root> --strict on all generated files

2. Report: "Created X files across Y layers. Run /greppable:status to see inventory."

3. Generate seed memories — create 3-5 @memory records capturing:

   • Architecture observation: "Project uses [pattern/framework] — key modules are [X, Y, Z]"
   • Scale observation: "Codebase has [N] modules, [M] dependencies — [small/medium/large] scale"
   • Convention observation: "Project follows [naming/structure] convention — [specifics]"
   • Gap observation (if found): "No [type] coverage for [area] — candidate for future indexing"

   First ensure the memory directory and file exist: bash -c 'mkdir -p memory/active && touch memory/active/seed.gdlm'

   Then for each seed memory: bash -c 'source "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-tools.sh" && gdl_new memory --agent=discover --subject="[title]" --detail="[specifics]" --type=observation --tags=architecture,seed --file=memory/active/seed.gdlm --append'

   These seed memories bootstrap the memory layer so future agents have immediate context.

Note: Steps 4-5 only apply to full-project scans. If $ARGUMENTS specified a subdirectory or focus area, skip to the final report — the discovery agent will not have produced activation artifacts.

4. Handle proposed rules — Parse the agent's report for the PROPOSED_RULES: / END_RULES block. If rules were proposed, present them for user confirmation:

   The discovery agent proposed these coding rules based on observed conventions:
   
     1. [warn] *.ts: Prefer named exports over default exports
        Evidence: src/auth/oauth.ts, src/billing/stripe.ts, src/api/routes.ts
   
     2. [error] **/migrations/**: Never modify existing migrations — create new ones
        Evidence: src/db/migrations/001_users.sql, src/db/migrations/002_orders.sql
   
   Add these to rules.gdl? [all / pick / skip]
   

   • all: Write all proposed rules to <gdl_root>/data/rules.gdl
   • pick: Let user select which rules to add (numbered)
   • skip: Don't add any rules
   • Any other response: interpret conversationally (e.g., "yes" = all, "just the first one" = pick #1)

   If 0 rules were proposed, report: "No coding rules detected — add rules manually with the managing-gdl-rules skill."

   For confirmed rules, write using:

   mkdir -p <gdl_root>/data
   echo '@rule|scope:GLOB|severity:LEVEL|desc:TEXT' >> <gdl_root>/data/rules.gdl
   

   Then validate: bash "${CLAUDE_PLUGIN_ROOT}/scripts/gdl-lint.sh" <gdl_root>/data/rules.gdl

5. Report activation summary:

   Activation:
     - anchors.gdlm: N concept anchors (auth, billing, api, ...)
     - architecture-overview.gdld: overview diagram with N nodes
     - rules.gdl: N coding rules confirmed (or "skipped" / "none proposed")
   
   Next steps:
     - Review rules.gdl and adjust severity levels for your team
     - Enrich GDLS schema descriptions (discover generates skeletons only)
     - Run /greppable:status to see full inventory
   

Format Specs

Refer to specs/ for format details when generating artifacts.