Neotex Codebase Onboarding

Automatically scan a codebase and generate organizational knowledge for neotex. Uses parallel exploration and scoring to capture what matters.

Prerequisites

ls .neotex/config.yaml 2>/dev/null || neotex init

PHASE 1: MEASURE & SPAWN (Immediate)

1.1 Measure Project Scale

Run these commands to understand project size:

# Total files (excluding node_modules, .git, vendor)
find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' | wc -l

# Directory depth distribution
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | awk -F/ '{print NF-1}' | sort -n | uniq -c

# Files per directory (top 20)
find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -20

# Detect languages
ls *.go go.mod 2>/dev/null && echo "GO"
ls package.json 2>/dev/null && echo "JS/TS"
ls *.py pyproject.toml setup.py 2>/dev/null && echo "PYTHON"
ls Cargo.toml 2>/dev/null && echo "RUST"

1.2 Spawn Background Agents (IMMEDIATELY)

CRITICAL: Fire these agents in parallel BEFORE doing anything else. Use Task tool with run_in_background: true.

Base agents (always spawn):

Agent 1: "Explore anti-patterns: Search for 'DO NOT', 'NEVER', 'ALWAYS', 'DEPRECATED', 'TODO', 'FIXME', 'HACK' in comments. Report forbidden patterns and technical debt."

Agent 2: "Explore entry points: Find main files, CLI entrypoints, API routes, event handlers. Report non-standard organization."

Agent 3: "Explore conventions: Sample 5-10 source files. Report naming patterns, error handling style, logging approach, test organization. Focus on DEVIATIONS from language defaults."

Dynamic agents (spawn based on scale):

PHASE 2: STRUCTURE ANALYSIS (Main Session)

While agents explore, analyze structure yourself:

2.1 Read Key Files

# Identity
cat README.md 2>/dev/null | head -100
cat package.json go.mod Cargo.toml pyproject.toml 2>/dev/null | head -50

# Build/Dev
cat Makefile docker-compose.yaml .env.example 2>/dev/null

# CI/CD
cat .github/workflows/*.yml .gitlab-ci.yml 2>/dev/null | head -100

2.2 Score Directories

For each major directory, calculate a score:

Decision thresholds:

• Score >15 → Document as separate learning
• Score 8-15 → Document if distinct domain
• Score <8 → Skip (parent covers it)

PHASE 3: COLLECT & GENERATE

3.1 Collect Background Results

Wait for all background agents to complete. Gather their findings.

3.2 Generate Learnings

For each discovery, save to neotex. For multiple items, use JSONL streaming:

# Single item
echo '{"type":"TYPE","title":"TITLE","body_md":"BODY"}' | neotex add --output

# Multiple items (JSONL streaming - memory efficient)
cat <<'EOF' | neotex add --batch --format jsonl --stream --output
{"type":"decision","title":"Title 1","body_md":"..."}
{"type":"guideline","title":"Title 2","body_md":"..."}
{"type":"learning","title":"Title 3","body_md":"..."}
EOF

Prefer JSONL streaming when generating multiple learnings to reduce API calls.

Learning Templates

Architecture Decision:

{
  "type": "decision",
  "title": "Uses {pattern} for {purpose}",
  "body_md": "## Context\n{What problem this solves}\n\n## Decision\n{What was chosen}\n\n## Consequences\n{Trade-offs, implications}"
}

Code Guideline:

{
  "type": "guideline",
  "title": "{Action verb} {what} {how}",
  "body_md": "## Rule\n{The convention}\n\n## Rationale\n{Why this exists}\n\n## Examples\n```{lang}\n{good example}\n```\n\n## Anti-patterns\n```{lang}\n{bad example}\n```"
}

Domain Learning:

{
  "type": "learning",
  "title": "{Entity/concept}: {key insight}",
  "body_md": "## Overview\n{What this is}\n\n## Key Files\n- `{path}`: {purpose}\n\n## Relationships\n{How it connects to other parts}"
}

Command Snippet:

{
  "type": "snippet",
  "title": "{Action}: {command}",
  "body_md": "## Command\n```bash\n{command}\n```\n\n## When to Use\n{Context}\n\n## Notes\n{Gotchas, options}"
}

Type Mapping

PHASE 4: QUALITY GATES

Before saving each learning, verify:

1. Not generic - Would this apply to ANY project? Skip it.
2. Not obvious - Would a senior dev assume this? Skip it.
3. Actionable - Does it help someone DO something? Keep it.
4. Specific - Does it reference actual files/patterns? Keep it.

Examples to SKIP:

• "Use meaningful variable names"
• "Write tests for your code"
• "Handle errors appropriately"

Examples to KEEP:

• "Error responses use api.Error(w, code, msg) - never write JSON directly"
• "All repository methods take ctx context.Context as first param"
• "Tests use testify/assert not standard library"

PHASE 5: SUMMARY REPORT

After all learnings saved, output:

## Neotex Onboarding Complete

Scanned {FILE_COUNT} files across {DIR_COUNT} directories.
Spawned {AGENT_COUNT} exploration agents.
Generated {LEARNING_COUNT} learnings.

### Architecture & Decisions ({N})
| Title | Type |
|-------|------|
{list}

### Guidelines & Conventions ({N})
| Title | Type |
|-------|------|
{list}

### Domain & Structure ({N})
| Title | Type |
|-------|------|
{list}

### Commands & Snippets ({N})
| Title | Type |
|-------|------|
{list}

---

**Next steps:**
- `neotex search "type:guideline <query>"` - Find specific knowledge (inline filters supported)
- `neotex search "<query>" --source asset` - Find assets
- `neotex pull` - Sync to local .neotex/index.json
- Review and delete any unwanted learnings via web UI

ERROR HANDLING

• If neotex add fails → Log error, continue with others
• If background agent fails → Note in summary, continue
• If file unreadable → Skip silently
• If project too small (<10 files) → Generate minimal learnings, note in summary

GUIDELINES

• Deviations over defaults - Only document what's different from standard practices
• Specific over generic - Reference actual files, actual patterns
• Actionable over descriptive - Help someone DO something
• Parallel over sequential - Spawn agents immediately, collect later
• Score before documenting - Don't document everything, document what matters
• Never include secrets - Skip any file with credentials, keys, tokens