# DevCard v2 — The Definitive Plan

> "Agent Card is how agents introduce themselves. DevCard is how developers introduce themselves — to agents, recruiters, and each other."

---

## The Pitch (30 seconds)

**DevCard** auto-generates a rich, structured, beautiful developer identity from any GitHub username. No sign-up. No LLM. No effort from the target developer. Just paste a username — get a full profile card with tech stack, coding patterns, expertise domains, and quality signals.

It outputs three things simultaneously:
1. **A visual card** (SVG/HTML) — the hook, shareable, embeddable
2. **A structured JSON** (`devcard.json`) — the protocol, agent-consumable
3. **A markdown summary** — the utility, pasteable anywhere

The JSON schema becomes the standard. The visual card drives adoption.

---

## Why This, Why Now

**The gap is real and widening:**

| Who needs it | What they do today | Pain |
|---|---|---|
| AI hiring agents | Scrape GitHub + guess | Every agent rebuilds the same parsing logic |
| Recruiters using AI tools | Read resumes + stalk LinkedIn | Can't programmatically assess technical depth |
| OSS maintainers | Manually review contributor profiles | No quick way to assess PR author quality |
| Team leads | Interview + hope | No structured signal on how someone actually codes |
| Developers themselves | Maintain a README nobody reads | No canonical, auto-updating identity |

**Timing convergence:**
- A2A protocol just shipped → agents need to understand humans, not just other agents
- MCP ecosystem is exploding → tools that plug in get instant distribution
- GitHub Copilot / coding agents are mainstream → the "developer identity for machines" concept clicks immediately
- `llms.txt` normalized the idea of "machine-readable identity files" → DevCard is the obvious next step for *people*

---

## The Anti-Cold-Start Strategy

The other LLM's feedback was right: "CLI that generates JSON" doesn't spread.

Here's how we solve cold start — **developers don't need to do anything for DevCard to work on them.**

### Key insight: DevCard is not opt-in. It's opt-*out*.

Unlike `llms.txt` (you must create it), DevCard works on ANY public GitHub profile. The developer doesn't generate their card — **anyone can generate a card for any developer.** The developer can later claim and customize it, but the default experience requires zero effort from them.

This means:
- Day 1: we pre-generate cards for 50 famous developers
- Day 1: anyone can generate a card for anyone
- Week 2: developers discover their own cards exist and want to customize them
- Month 2: developers start putting `devcard.json` in their repos voluntarily

**This is the Gravatar model**, not the LinkedIn model.

---

## Three Layers, One Repo

```
┌─────────────────────────────────────────────────┐
│                 LAYER 3: ECOSYSTEM              │
│  MCP Server · GitHub Action · API · Embeds      │
│  (how agents and tools consume DevCards)         │
├─────────────────────────────────────────────────┤
│                 LAYER 2: VISUAL                 │
│  SVG Card · HTML Profile · Terminal Rich Output │
│  (the hook — what makes people share it)        │
├─────────────────────────────────────────────────┤
│                 LAYER 1: SCHEMA + ENGINE        │
│  devcard.json · Extractors · Analyzers          │
│  (the protocol — what makes it useful long-term)│
└─────────────────────────────────────────────────┘
```

Most OSS projects build Layer 1 and hope Layer 3 emerges.
We build all three from day one. Layer 2 is what 99% of projects skip — and it's the entire distribution strategy.

---

## The Visual Card (THE Hook)

This is the single most important feature for adoption. Without it, DevCard is another smart-but-invisible JSON standard.

### What the card looks like:

```
╔══════════════════════════════════════════════════════╗
║  🪪 DEVCARD                                         ║
╠══════════════════════════════════════════════════════╣
║                                                      ║
║  ⬡ Linus Torvalds              @torvalds             ║
║  ─────────────────────────────────────                ║
║  Type: Systems / Kernel Engineer                      ║
║  Since: 2011  ·  Mass: 1.2k repos  ·  ⭐ 203k       ║
║                                                      ║
║  LANGUAGE DNA                                         ║
║  ████████████████░░░░░░  C         72.3%             ║
║  ████░░░░░░░░░░░░░░░░░░  Shell     14.1%             ║
║  ██░░░░░░░░░░░░░░░░░░░░  Makefile   8.2%             ║
║                                                      ║
║  STACK                                                ║
║  ┌──────────┐ ┌──────────┐ ┌──────────┐              ║
║  │   Make   │ │   GCC    │ │   Git    │              ║
║  └──────────┘ └──────────┘ └──────────┘              ║
║                                                      ║
║  QUALITY SIGNALS                                      ║
║  Tests: ██████████ 92%    CI: █████████░ 88%          ║
║  Docs:  ████████░░ 78%    License: ██████████ 100%    ║
║                                                      ║
║  FOCUS AREAS                                          ║
║  ◉ operating-systems (0.95)                           ║
║  ◉ version-control (0.88)                             ║
║  ◉ systems-programming (0.82)                         ║
║                                                      ║
║  ACTIVITY                                             ║
║  Mon ░░██░░░░░░░░░░░░░░░░░░░░░░                      ║
║  Tue ░░░░██████░░░░░░░░░░░░░░░░                      ║
║  Wed ░░░░░░████████░░░░░░░░░░░░                      ║
║  ...                                                  ║
║                                                      ║
║  ──────────────────────────────────                   ║
║  generated by devcard · v1.0 · 2026-04-25             ║
╚══════════════════════════════════════════════════════╝
```

### Output formats for the visual:
1. **SVG** — embeddable in GitHub READMEs, websites, anywhere
2. **HTML** — standalone profile page, shareable link
3. **Terminal** — rich output via `rich` library when running CLI
4. **PNG** — for social sharing (Twitter/X cards, LinkedIn posts)

### Why this works:
- **GitHub README embedding** — developers put SVG cards in their profile README. This is proven (GitHub stats cards have 70k+ stars).
- **Social sharing** — "Here's my DevCard" is a tweet/post. The PNG has a card design that looks good on social media.
- **Vanity drives adoption** — developers don't care about JSON schemas. They care about looking cool. The visual card is the Trojan horse that carries the schema to adoption.

---

## The Schema (devcard.json v1) — Refined

```jsonc
{
  // ── Meta ──────────────────────────────────────────
  "$schema": "https://devcard.dev/schema/v1.json",
  "version": "1.0.0",
  "generated_at": "2026-04-25T12:00:00Z",
  "generator": { "name": "devcard-cli", "version": "0.1.0" },

  // ── Identity ──────────────────────────────────────
  "identity": {
    "github_username": "torvalds",
    "name": "Linus Torvalds",
    "bio": "Creator of Linux and Git",
    "location": "Portland, OR",
    "company": "@linux-foundation",
    "website": "https://lkml.org",
    "social": {
      "twitter": null,
      "mastodon": null,
      "linkedin": null
    },
    "avatar_url": "https://avatars.githubusercontent.com/u/1024025",
    "joined_github": "2011-09-03",
    "public_repos": 7,
    "followers": 230000,
    "following": 0
  },

  // ── Language DNA ──────────────────────────────────
  // Weighted by bytes across all non-fork repos
  "languages": [
    { "name": "C", "percentage": 72.3, "bytes": 892341234, "repo_count": 4 },
    { "name": "Shell", "percentage": 14.1, "bytes": 174234234, "repo_count": 3 },
    { "name": "Makefile", "percentage": 8.2, "bytes": 101234234, "repo_count": 4 }
  ],

  // ── Tech Stack ────────────────────────────────────
  // Inferred from dependency files (package.json, requirements.txt, etc.)
  "stack": {
    "frameworks": [],
    "databases": [],
    "cloud_infra": ["Docker"],
    "testing": ["kunit"],
    "build_tools": ["Make", "GCC", "CMake"],
    "ai_ml": [],
    "other": ["Git"]
  },

  // ── Developer Type ────────────────────────────────
  "profile_type": {
    "primary": "systems-engineer",
    // Enum: frontend, backend, fullstack, systems-engineer,
    //       devtools, ml-engineer, data-engineer, mobile,
    //       devops-infra, security, embedded, game-dev
    "focus_areas": [
      { "area": "operating-systems", "confidence": 0.95 },
      { "area": "version-control", "confidence": 0.88 },
      { "area": "systems-programming", "confidence": 0.82 }
    ]
  },

  // ── Activity ──────────────────────────────────────
  "activity": {
    "status": "active",               // active, moderate, sporadic, dormant
    "commits_last_year": 3200,
    "avg_commits_per_week": 61.5,
    "active_days_per_week": 6.8,
    "peak_hours_utc": [16, 17, 18],
    "timezone_estimate": "UTC-8",
    "longest_streak_days": 120,
    "last_pushed": "2026-04-24",
    "most_active_day": "Tuesday",
    // Heatmap data: 7 days × 24 hours normalized intensity
    "weekly_heatmap": [
      [0,0,0,0,0,0,0,0.1,0.3,0.5,0.8,0.9,0.7,0.6,0.8,0.9,1.0,0.8,0.5,0.3,0.1,0,0,0],
      // ... 6 more rows (Mon-Sun)
    ]
  },

  // ── Top Projects ──────────────────────────────────
  // Ranked by: stars×3 + forks×2 + recency_bonus
  "top_projects": [
    {
      "name": "linux",
      "description": "Linux kernel source tree",
      "url": "https://github.com/torvalds/linux",
      "primary_language": "C",
      "stars": 189000,
      "forks": 55000,
      "topics": ["linux", "kernel", "operating-system"],
      "classification": "application",  // library, application, tool, framework, config, docs, learning
      "status": "active",               // active (<30d), maintained (<90d), stale (<1y), archived
      "maturity": {
        "has_tests": true,
        "has_ci": true,
        "has_docs": true,
        "has_license": true,
        "has_contributing": true,
        "commit_count": 1200000,
        "contributors": 5000
      },
      "last_commit": "2026-04-24"
    }
  ],

  // ── Collaboration ─────────────────────────────────
  "collaboration": {
    "external_prs_count": 0,
    "external_issues_count": 0,
    "organizations": ["linux-foundation"],
    "sponsorable": false,
    "contribution_style": "maintainer"  // maintainer, contributor, solo-builder, explorer
  },

  // ── Quality Signals ───────────────────────────────
  // Percentages across original (non-fork) repos
  "quality": {
    "tests_ratio": 0.92,
    "ci_ratio": 0.88,
    "docs_ratio": 0.78,
    "license_ratio": 1.0,
    "linter_ratio": 0.45,
    "avg_readme_bytes": 12400,
    "overall_score": 0.87  // Weighted composite
  },

  // ── Influence ─────────────────────────────────────
  "influence": {
    "total_stars": 203000,
    "total_forks": 58000,
    "followers": 230000,
    "top_repo_stars": 189000,
    "repos_with_100plus_stars": 2
  },

  // ── LLM Enrichment (optional) ─────────────────────
  "enriched": null
  // When present:
  // {
  //   "summary": "...",
  //   "skill_levels": { "C": "expert", "Shell": "advanced" },
  //   "model": "gpt-4o-mini",
  //   "generated_at": "..."
  // }
}
```

---

## Architecture — Revised for Virality

```
devcard/
│
├── schema/
│   ├── devcard.v1.schema.json              # Formal JSON Schema
│   └── examples/
│       ├── torvalds.devcard.json
│       ├── karpathy.devcard.json
│       ├── guido.devcard.json
│       ├── sindresorhus.devcard.json
│       └── minimal.devcard.json
│
├── gallery/                                 # Pre-generated visual cards
│   ├── torvalds.svg
│   ├── karpathy.svg
│   ├── guido.svg
│   └── ...                                 # 30-50 famous developers
│
├── src/devcard/
│   ├── __init__.py
│   ├── cli.py                              # Typer CLI
│   ├── config.py                           # Config + env vars
│   │
│   ├── github/
│   │   ├── client.py                       # Async, rate-limited, cached
│   │   ├── models.py                       # Pydantic models for API
│   │   └── cache.py                        # diskcache wrapper
│   │
│   ├── extractors/                         # Each returns a Pydantic model
│   │   ├── __init__.py
│   │   ├── identity.py                     # Profile info
│   │   ├── languages.py                    # Language DNA (weighted bytes)
│   │   ├── stack.py                        # Dependency file → tech stack
│   │   ├── activity.py                     # Commit patterns + heatmap
│   │   ├── projects.py                     # Repo ranking + classification
│   │   ├── collaboration.py               # External PRs, orgs, style
│   │   ├── quality.py                      # Tests/CI/docs/license ratios
│   │   └── expertise.py                    # Domain inference
│   │
│   ├── analyzers/
│   │   ├── developer_type.py               # Classify dev archetype
│   │   ├── project_classifier.py           # Classify repos
│   │   ├── contribution_style.py           # maintainer/contributor/solo/explorer
│   │   └── scoring.py                      # Confidence + quality scores
│   │
│   ├── enrichment/                         # Optional LLM layer
│   │   ├── litellm_client.py
│   │   ├── summarizer.py
│   │   └── skill_assessor.py
│   │
│   ├── renderers/                          # THE VIRAL LAYER
│   │   ├── __init__.py
│   │   ├── svg_card.py                     # Beautiful SVG card (embeddable)
│   │   ├── html_profile.py                 # Full HTML profile page
│   │   ├── terminal.py                     # Rich terminal output
│   │   ├── markdown.py                     # Markdown summary
│   │   ├── png.py                          # PNG export for social sharing
│   │   └── themes/
│   │       ├── default.py
│   │       ├── dark.py
│   │       ├── minimal.py
│   │       ├── neon.py
│   │       └── terminal_green.py
│   │
│   ├── output/
│   │   ├── json_output.py
│   │   └── yaml_output.py
│   │
│   └── validators/
│       └── schema_validator.py
│
├── mappings/                               # The heuristic brain
│   ├── dependencies.yaml                   # 500+ dependency → category mappings
│   ├── topics_to_domains.yaml              # GitHub topics → expertise domains
│   ├── file_patterns.yaml                  # File presence → signals
│   └── dev_type_rules.yaml                 # Decision tree for developer type
│
├── tests/
│   ├── fixtures/                           # Mock GitHub API responses
│   │   ├── users/
│   │   ├── repos/
│   │   └── events/
│   ├── test_extractors/
│   ├── test_analyzers/
│   ├── test_renderers/
│   └── test_cli.py
│
├── action/                                 # GitHub Action
│   ├── action.yml
│   └── entrypoint.sh
│
├── mcp/                                    # MCP Server wrapper
│   ├── server.py
│   └── README.md
│
├── docs/
│   ├── SCHEMA.md                           # Full schema docs
│   ├── AGENTS.md                           # "How to consume DevCards in your agent"
│   ├── THEMES.md                           # How to create custom themes
│   └── HEURISTICS.md                       # How the no-LLM extraction works
│
├── .github/
│   ├── workflows/
│   │   ├── ci.yml
│   │   ├── generate-gallery.yml            # Auto-regenerate gallery weekly
│   │   └── release.yml
│   └── ISSUE_TEMPLATE/
│
├── pyproject.toml
├── README.md
├── LICENSE                                 # Apache 2.0
├── CHANGELOG.md
└── ROADMAP.md
```

---

## CLI Interface — Revised

```bash
# ═══════════════════════════════════════════════════
# CORE COMMANDS
# ═══════════════════════════════════════════════════

# Generate a DevCard (default: JSON + terminal visual)
devcard generate torvalds

# With GitHub token (recommended — 5000 req/hr vs 60)
devcard generate torvalds --token ghp_xxx
# or via env var
export GITHUB_TOKEN=ghp_xxx
devcard generate torvalds

# ═══════════════════════════════════════════════════
# OUTPUT FORMATS
# ═══════════════════════════════════════════════════

# JSON (the schema — for agents)
devcard generate torvalds --format json -o torvalds.devcard.json

# SVG card (the hook — for sharing)
devcard generate torvalds --format svg -o torvalds.svg

# HTML profile page
devcard generate torvalds --format html -o torvalds.html

# PNG (for social media sharing)
devcard generate torvalds --format png -o torvalds.png

# Markdown summary
devcard generate torvalds --format markdown

# ALL formats at once
devcard generate torvalds --format all --output-dir ./cards/

# ═══════════════════════════════════════════════════
# THEMES (for visual outputs)
# ═══════════════════════════════════════════════════

devcard generate torvalds --format svg --theme dark
devcard generate torvalds --format svg --theme neon
devcard generate torvalds --format svg --theme minimal
devcard generate torvalds --format svg --theme terminal-green

# ═══════════════════════════════════════════════════
# COMPARE (the killer feature for virality)
# ═══════════════════════════════════════════════════

# Side-by-side comparison of two developers
devcard compare torvalds guido
# Outputs a combined SVG/terminal view showing:
# - Language DNA overlap
# - Stack differences
# - Activity patterns
# - Quality scores head-to-head

# ═══════════════════════════════════════════════════
# LLM ENRICHMENT (optional)
# ═══════════════════════════════════════════════════

devcard generate torvalds --enrich --model gpt-4o-mini
# Requires: LITELLM_API_KEY or OPENAI_API_KEY env var

# ═══════════════════════════════════════════════════
# UTILITY
# ═══════════════════════════════════════════════════

# Validate a devcard.json against the schema
devcard validate ./my-devcard.json

# Serve as local API (for MCP/agent integration)
devcard serve --port 8080
# GET http://localhost:8080/card/torvalds
# GET http://localhost:8080/card/torvalds?format=svg

# Batch generate
devcard batch usernames.txt --output-dir ./cards/

# Self-generate (uses current git user)
devcard me
```

---

## The Dependency → Stack Mapping (Core Heuristic)

This is the engine that makes DevCard genuinely useful without an LLM.
The `mappings/dependencies.yaml` file is the soul of the project.

```yaml
# mappings/dependencies.yaml
# Format: package_name → { category, display_name, ?aliases }

# ═══ PYTHON ═══════════════════════════════════════

# Frameworks
fastapi:        { category: framework, name: "FastAPI" }
django:         { category: framework, name: "Django" }
flask:          { category: framework, name: "Flask" }
starlette:      { category: framework, name: "Starlette" }
tornado:        { category: framework, name: "Tornado" }
sanic:          { category: framework, name: "Sanic" }
litestar:       { category: framework, name: "Litestar" }
quart:          { category: framework, name: "Quart" }
streamlit:      { category: framework, name: "Streamlit" }
gradio:         { category: framework, name: "Gradio" }

# Databases
sqlalchemy:     { category: database, name: "SQLAlchemy" }
psycopg2:       { category: database, name: "PostgreSQL" }
pymongo:        { category: database, name: "MongoDB" }
redis:          { category: database, name: "Redis" }
motor:          { category: database, name: "MongoDB (async)" }
tortoise-orm:   { category: database, name: "Tortoise ORM" }
peewee:         { category: database, name: "Peewee ORM" }
sqlmodel:       { category: database, name: "SQLModel" }
prisma:         { category: database, name: "Prisma" }
alembic:        { category: database, name: "Alembic (migrations)" }
elasticsearch:  { category: database, name: "Elasticsearch" }
cassandra-driver: { category: database, name: "Cassandra" }
neo4j:          { category: database, name: "Neo4j" }
clickhouse-driver: { category: database, name: "ClickHouse" }

# AI/ML
langchain:      { category: ai_ml, name: "LangChain" }
langchain-core: { category: ai_ml, name: "LangChain" }
llama-index:    { category: ai_ml, name: "LlamaIndex" }
openai:         { category: ai_ml, name: "OpenAI SDK" }
anthropic:      { category: ai_ml, name: "Anthropic SDK" }
transformers:   { category: ai_ml, name: "Hugging Face" }
torch:          { category: ai_ml, name: "PyTorch" }
pytorch:        { category: ai_ml, name: "PyTorch" }
tensorflow:     { category: ai_ml, name: "TensorFlow" }
keras:          { category: ai_ml, name: "Keras" }
scikit-learn:   { category: ai_ml, name: "scikit-learn" }
numpy:          { category: ai_ml, name: "NumPy" }
pandas:         { category: ai_ml, name: "Pandas" }
scipy:          { category: ai_ml, name: "SciPy" }
jax:            { category: ai_ml, name: "JAX" }
mlflow:         { category: ai_ml, name: "MLflow" }
wandb:          { category: ai_ml, name: "W&B" }
crewai:         { category: ai_ml, name: "CrewAI" }
autogen:        { category: ai_ml, name: "AutoGen" }
pydantic-ai:    { category: ai_ml, name: "PydanticAI" }
instructor:     { category: ai_ml, name: "Instructor" }
litellm:        { category: ai_ml, name: "LiteLLM" }
chromadb:       { category: ai_ml, name: "ChromaDB" }
pinecone-client: { category: ai_ml, name: "Pinecone" }
weaviate-client: { category: ai_ml, name: "Weaviate" }
qdrant-client:  { category: ai_ml, name: "Qdrant" }

# Cloud/Infra
boto3:          { category: cloud, name: "AWS" }
google-cloud-storage: { category: cloud, name: "GCP" }
azure-storage-blob: { category: cloud, name: "Azure" }
kubernetes:     { category: cloud, name: "Kubernetes" }
docker:         { category: cloud, name: "Docker SDK" }
terraform:      { category: cloud, name: "Terraform" }
pulumi:         { category: cloud, name: "Pulumi" }

# Testing
pytest:         { category: testing, name: "pytest" }
unittest:       { category: testing, name: "unittest" }
hypothesis:     { category: testing, name: "Hypothesis" }
tox:            { category: testing, name: "tox" }
nox:            { category: testing, name: "nox" }
coverage:       { category: testing, name: "Coverage.py" }

# ═══ JAVASCRIPT / TYPESCRIPT ═════════════════════

# Frameworks
react:          { category: framework, name: "React" }
next:           { category: framework, name: "Next.js" }
vue:            { category: framework, name: "Vue.js" }
nuxt:           { category: framework, name: "Nuxt" }
svelte:         { category: framework, name: "Svelte" }
angular:        { category: framework, name: "Angular" }
"@angular/core": { category: framework, name: "Angular" }
express:        { category: framework, name: "Express" }
fastify:        { category: framework, name: "Fastify" }
hono:           { category: framework, name: "Hono" }
remix:          { category: framework, name: "Remix" }
astro:          { category: framework, name: "Astro" }
gatsby:         { category: framework, name: "Gatsby" }
nestjs:         { category: framework, name: "NestJS" }
"@nestjs/core": { category: framework, name: "NestJS" }
solid-js:       { category: framework, name: "SolidJS" }
qwik:           { category: framework, name: "Qwik" }
htmx:           { category: framework, name: "htmx" }
"react-native": { category: framework, name: "React Native" }
expo:           { category: framework, name: "Expo" }
electron:       { category: framework, name: "Electron" }
tauri:          { category: framework, name: "Tauri" }

# Databases
mongoose:       { category: database, name: "MongoDB" }
pg:             { category: database, name: "PostgreSQL" }
mysql2:         { category: database, name: "MySQL" }
"@prisma/client": { category: database, name: "Prisma" }
drizzle-orm:    { category: database, name: "Drizzle ORM" }
typeorm:        { category: database, name: "TypeORM" }
sequelize:      { category: database, name: "Sequelize" }
ioredis:        { category: database, name: "Redis" }
knex:           { category: database, name: "Knex.js" }
"better-sqlite3": { category: database, name: "SQLite" }
"@supabase/supabase-js": { category: database, name: "Supabase" }
firebase:       { category: database, name: "Firebase" }

# AI/ML
"@langchain/core": { category: ai_ml, name: "LangChain.js" }
ai:             { category: ai_ml, name: "Vercel AI SDK" }
openai:         { category: ai_ml, name: "OpenAI SDK" }
"@anthropic-ai/sdk": { category: ai_ml, name: "Anthropic SDK" }
"@google/generative-ai": { category: ai_ml, name: "Gemini SDK" }
"@huggingface/inference": { category: ai_ml, name: "Hugging Face" }
replicate:      { category: ai_ml, name: "Replicate" }
"@modelcontextprotocol/sdk": { category: ai_ml, name: "MCP SDK" }

# Testing
jest:           { category: testing, name: "Jest" }
vitest:         { category: testing, name: "Vitest" }
mocha:          { category: testing, name: "Mocha" }
"@playwright/test": { category: testing, name: "Playwright" }
cypress:        { category: testing, name: "Cypress" }
"@testing-library/react": { category: testing, name: "Testing Library" }

# Build tools
vite:           { category: build_tool, name: "Vite" }
webpack:        { category: build_tool, name: "Webpack" }
esbuild:        { category: build_tool, name: "esbuild" }
turbo:          { category: build_tool, name: "Turborepo" }
nx:             { category: build_tool, name: "Nx" }
tsup:           { category: build_tool, name: "tsup" }

# ═══ GO ═══════════════════════════════════════════
"github.com/gin-gonic/gin":     { category: framework, name: "Gin" }
"github.com/gofiber/fiber":     { category: framework, name: "Fiber" }
"github.com/labstack/echo":     { category: framework, name: "Echo" }
"github.com/gorilla/mux":       { category: framework, name: "Gorilla Mux" }
"gorm.io/gorm":                 { category: database, name: "GORM" }
"github.com/jackc/pgx":         { category: database, name: "PostgreSQL" }
"go.mongodb.org/mongo-driver":  { category: database, name: "MongoDB" }
"github.com/redis/go-redis":    { category: database, name: "Redis" }
"github.com/stretchr/testify":  { category: testing, name: "Testify" }

# ═══ RUST ═════════════════════════════════════════
actix-web:      { category: framework, name: "Actix Web" }
axum:           { category: framework, name: "Axum" }
rocket:         { category: framework, name: "Rocket" }
warp:           { category: framework, name: "Warp" }
tokio:          { category: cloud, name: "Tokio (async runtime)" }
diesel:         { category: database, name: "Diesel ORM" }
sqlx:           { category: database, name: "SQLx" }
sea-orm:        { category: database, name: "SeaORM" }

# ... 300+ more mappings across Ruby, Java, PHP, C#, Swift, Kotlin, etc.
```

---

## File Pattern → Signal Mapping

```yaml
# mappings/file_patterns.yaml
# Detect engineering practices from file presence

ci_indicators:
  - ".github/workflows/*.yml"
  - ".gitlab-ci.yml"
  - "Jenkinsfile"
  - ".circleci/config.yml"
  - ".travis.yml"
  - "azure-pipelines.yml"
  - "bitbucket-pipelines.yml"

test_indicators:
  - "tests/"
  - "test/"
  - "__tests__/"
  - "spec/"
  - "*_test.go"
  - "*_test.py"
  - "*.test.ts"
  - "*.test.js"
  - "*.spec.ts"
  - "*.spec.js"
  - "pytest.ini"
  - "jest.config.*"
  - "vitest.config.*"

docs_indicators:
  - "docs/"
  - "doc/"
  - "documentation/"
  - "wiki/"
  - "CONTRIBUTING.md"
  - "CHANGELOG.md"
  - "API.md"
  - "mkdocs.yml"
  - "docusaurus.config.*"

containerization:
  - "Dockerfile"
  - "docker-compose.yml"
  - "docker-compose.yaml"
  - ".dockerignore"
  - "kubernetes/"
  - "k8s/"
  - "helm/"
  - "Chart.yaml"

linter_indicators:
  - ".eslintrc*"
  - ".prettierrc*"
  - "biome.json"
  - ".flake8"
  - "pyproject.toml[tool.ruff]"
  - ".rubocop.yml"
  - ".golangci.yml"
  - "clippy.toml"

iac_indicators:
  - "terraform/"
  - "*.tf"
  - "pulumi/"
  - "Pulumi.yaml"
  - "ansible/"
  - "playbook.yml"
  - "cloudformation/"
```

---

## Developer Type Classification (Decision Tree)

```yaml
# mappings/dev_type_rules.yaml
# Heuristic decision tree for developer type classification

rules:
  # Check in order — first match wins for primary type
  - type: "ml-engineer"
    conditions:
      - ai_ml_deps_count >= 3
      - languages_include_any: ["Python", "R", "Julia"]
      - has_topics_any: ["machine-learning", "deep-learning", "ai", "nlp", "computer-vision"]

  - type: "data-engineer"
    conditions:
      - has_deps_any: ["apache-spark", "airflow", "dbt", "prefect", "dagster", "kafka"]
      - languages_include_any: ["Python", "SQL", "Scala"]

  - type: "mobile"
    conditions:
      - has_deps_any: ["react-native", "expo", "flutter", "swift", "kotlin"]
      - languages_include_any: ["Swift", "Kotlin", "Dart"]

  - type: "devops-infra"
    conditions:
      - iac_file_count >= 2
      - has_deps_any: ["terraform", "ansible", "pulumi", "kubernetes"]
      - languages_include_any: ["Shell", "HCL", "Python", "Go"]

  - type: "embedded"
    conditions:
      - languages_include_any: ["C", "C++", "Assembly", "Rust"]
      - has_topics_any: ["embedded", "iot", "firmware", "microcontroller", "rtos"]

  - type: "systems-engineer"
    conditions:
      - language_primary_any: ["C", "C++", "Rust"]
      - language_primary_percentage > 60
      - has_topics_any: ["kernel", "os", "compiler", "runtime", "systems"]

  - type: "security"
    conditions:
      - has_topics_any: ["security", "cryptography", "pentest", "ctf", "vulnerability"]

  - type: "game-dev"
    conditions:
      - has_deps_any: ["unity", "godot", "unreal", "bevy", "pygame"]
      - languages_include_any: ["C#", "C++", "GDScript"]

  - type: "frontend"
    conditions:
      - frontend_framework_count >= 2
      - language_percentage["TypeScript"] + language_percentage["JavaScript"] > 60
      - backend_framework_count == 0

  - type: "backend"
    conditions:
      - backend_framework_count >= 1
      - frontend_framework_count == 0
      - languages_exclude_dominant: ["TypeScript", "JavaScript"]

  - type: "devtools"
    conditions:
      - cli_tool_count >= 2
      - library_repo_count >= 3
      - has_npm_or_pypi_publishing_signals: true

  - type: "fullstack"
    conditions:
      - frontend_framework_count >= 1
      - backend_framework_count >= 1
    # Default fallback if nothing else matches
```

---

## Contribution Style Classification

```python
# Not just "what they code" but "how they code"

def classify_contribution_style(data):
    """
    Classify how a developer contributes to the ecosystem.

    maintainer:   Owns popular repos, receives many PRs, low external PR count
    contributor:  High external PR count, contributes to others' projects
    solo-builder: Many original repos, few external contributions, few incoming PRs
    explorer:     Many forks, learning repos, broad but shallow
    """
    external_prs = data.external_prs_count
    owned_repo_stars = data.total_stars
    original_ratio = data.original_repo_ratio
    fork_ratio = 1 - original_ratio
    avg_commits_per_repo = data.total_commits / max(data.repo_count, 1)

    if owned_repo_stars > 1000 and external_prs < 20:
        return "maintainer"
    elif external_prs > 30:
        return "contributor"
    elif fork_ratio > 0.5 and avg_commits_per_repo < 15:
        return "explorer"
    else:
        return "solo-builder"
```

---

## Implementation Phases — Revised for Impact

### Phase 0: Foundation (Days 1-3)
- [ ] Project scaffolding (pyproject.toml, directory structure, CI)
- [ ] `devcard.v1.schema.json` — formal JSON Schema
- [ ] GitHub API client (async httpx, rate limiting, caching)
- [ ] Pydantic models for all API responses and DevCard sections
- [ ] 3 example `devcard.json` files (handcrafted for torvalds, karpathy, guido)

### Phase 1: Core Engine — Zero LLM (Days 4-10)
- [ ] **identity.py** — Profile extraction
- [ ] **languages.py** — Weighted language analysis
- [ ] **stack.py** — Dependency file parsing + `dependencies.yaml` (200+ entries)
- [ ] **activity.py** — Commit patterns, heatmap, streaks
- [ ] **projects.py** — Repo ranking + classification
- [ ] **quality.py** — Tests/CI/docs/license detection
- [ ] **collaboration.py** — External PRs, orgs
- [ ] **expertise.py** — Domain inference from topics + deps
- [ ] **developer_type.py** — Archetype classification
- [ ] **contribution_style.py** — How they contribute
- [ ] CLI: `devcard generate <username>` → JSON output
- [ ] CLI: rich terminal output showing card in terminal

### Phase 2: The Visual Layer — THE VIRAL FEATURE (Days 11-16)
- [ ] **SVG card renderer** — beautiful, GitHub-README-embeddable card
- [ ] **5 themes** — default, dark, minimal, neon, terminal-green
- [ ] **PNG export** — for social media cards (Open Graph compatible)
- [ ] **HTML profile page** — standalone shareable page
- [ ] **Markdown output** — clean pasteable summary
- [ ] **`devcard compare`** — side-by-side visual comparison
- [ ] **Gallery** — pre-generate SVGs for 30-50 famous developers

### Phase 3: Ecosystem Hooks (Days 17-22)
- [ ] **GitHub Action** — auto-generate + commit devcard.json weekly
- [ ] **`devcard serve`** — lightweight API server
- [ ] **MCP server wrapper** — so agents can call `get_devcard(username)`
- [ ] **LLM enrichment** — `--enrich` flag via LiteLLM
- [ ] **Schema validator** — `devcard validate`
- [ ] **Batch generation** — `devcard batch`

### Phase 4: Launch (Days 23-28)
- [ ] **README** — polished, with embedded SVG examples
- [ ] **PyPI publishing** — `pip install devcard`
- [ ] **docs/** — Schema docs, agent guide, theme guide, heuristics guide
- [ ] **Blog post / HN post** — with gallery of famous dev cards
- [ ] **Tweet thread** — showing comparisons of famous devs

---

## Distribution Strategy (How This Doesn't Die)

### Launch Day Assets:
1. **Gallery of 30-50 famous developer cards** in the repo
   - Linus Torvalds, Guido van Rossum, Andrej Karpathy, Sindre Sorhus, Evan You,
     DHH, TJ Holowaychuk, Guillermo Rauch, Mitchell Hashimoto, Kelsey Hightower,
     Dan Abramov, Ryan Dahl, Rich Harris, Theo Browne, etc.
   - Each one is a visual SVG card that looks stunning
   - People will share these comparing their faves

2. **"Generate your own" one-liner** in README:
   ```bash
   pipx run devcard generate YOUR_USERNAME --format svg
   ```

3. **Compare feature highlighted**:
   ```bash
   devcard compare torvalds guido --theme dark
   ```
   This is inherently social. People will compare themselves to friends, to famous devs.

### Week 1 Distribution:
- Post to HN: "Show HN: DevCard – Agent-readable developer profiles from GitHub"
- Post to Reddit: r/programming, r/Python, r/github
- Post to X/Twitter with SVG card images of famous devs
- Tag famous devs: "Here's your DevCard, @kaborat" — engagement bait that actually works

### Month 1 Network Effect:
- Developers embed SVG cards in their GitHub profile READMEs
- Each embedded card has `generated by devcard` → repo discovery
- Compare feature creates organic sharing
- GitHub Action means cards auto-update → ongoing presence

### Month 2+ Agent Ecosystem:
- MCP server → any agent can call `get_devcard()`
- Hiring agents start consuming devcard.json
- OSS projects use it to evaluate contributor applications
- Convention: `devcard.json` in profile repos alongside `llms.txt`

---

## README Structure (for the repo)

```markdown
# 🪪 DevCard

**Agent-readable developer identity, generated from GitHub.**

> The `llms.txt` is for code. DevCard is for the coder.

[One-liner about what it does]

[3 beautiful SVG card examples side by side: torvalds, karpathy, sindresorhus]

## Quick Start
pip install devcard
devcard generate YOUR_USERNAME

## What It Generates
[Show the 3 outputs: terminal screenshot, SVG card, JSON snippet]

## Gallery
[Link to gallery/ with 30+ pre-generated cards]

## Compare Developers
devcard compare dev1 dev2
[Show a comparison visual]

## How Agents Use DevCard
[Brief section for agent developers: fetch from well-known path, MCP, API]

## The Schema
[Link to schema docs, brief field overview]

## Themes
[Show all 5 themes for the same developer]

## GitHub Action
[How to auto-generate and embed in your profile]

## No LLM Required
[Explain the heuristic approach, link to HEURISTICS.md]

## LLM Enrichment (Optional)
[How to use --enrich with LiteLLM]

## License
Apache 2.0
```

---

## Agent Prompt for Building This

```markdown
# Task: Build DevCard — Agent-Readable Developer Identity from GitHub

You are building **DevCard**, an open-source Python CLI + schema that
auto-generates structured, agent-readable developer profiles from any
public GitHub username. No LLM required by default.

## Project philosophy:
- ZERO LLM by default. All extraction is GitHub API + heuristics.
- LLM enrichment is OPTIONAL via LiteLLM, activated with `--enrich`.
- The visual card (SVG) is equally important as the JSON schema.
  Without the visual, this project won't get adoption.
- The JSON schema (`devcard.json`) is the long-term protocol.
- Apache 2.0 license.

## Tech stack:
- Python 3.11+
- `typer` for CLI
- `httpx` for async HTTP
- `pydantic` v2 for all models
- `diskcache` for caching
- `rich` for terminal output
- `litellm` as optional dependency for enrichment
- `cairosvg` or `playwright` for PNG export (optional)
- `pyyaml` for mapping files
- `pytest` for testing
- Package manager: `uv`

## Build order (critical — do not skip steps):

### 1. Scaffold the project
Create directory structure:
```
devcard/
├── schema/devcard.v1.schema.json
├── src/devcard/
│   ├── cli.py
│   ├── config.py
│   ├── github/ (client.py, models.py, cache.py)
│   ├── extractors/ (identity, languages, stack, activity, projects,
│   │                collaboration, quality, expertise)
│   ├── analyzers/ (developer_type, project_classifier,
│   │               contribution_style, scoring)
│   ├── enrichment/ (litellm_client, summarizer, skill_assessor)
│   ├── renderers/ (svg_card, html_profile, terminal, markdown, themes/)
│   ├── output/ (json_output, yaml_output)
│   └── validators/ (schema_validator)
├── mappings/ (dependencies.yaml, topics_to_domains.yaml,
│              file_patterns.yaml, dev_type_rules.yaml)
├── tests/fixtures/
├── gallery/
├── action/
├── mcp/
└── docs/
```

Set up pyproject.toml with:
- Project name: "devcard"
- Entry point: `devcard = "devcard.cli:app"`
- Dependencies: typer, httpx, pydantic, diskcache, rich, pyyaml, jsonschema
- Optional deps [enrich]: litellm
- Optional deps [png]: cairosvg OR pillow
- Optional deps [dev]: pytest, pytest-asyncio, ruff

### 2. Create the JSON Schema
Write `schema/devcard.v1.schema.json` — formal JSON Schema Draft 2020-12.
Sections: identity, languages, stack, profile_type, activity, top_projects,
collaboration, quality, influence, enriched (optional).
All fields must have descriptions.
Create 3 example files in schema/examples/.

### 3. GitHub API Client
`src/devcard/github/client.py`:
- Async httpx client
- Rate limit handling (read X-RateLimit-Remaining, sleep when needed)
- Local disk caching (diskcache, 1hr TTL)
- Support unauthenticated (60 req/hr) and token auth (5000 req/hr)
- Token from --token flag, GITHUB_TOKEN env var, or gh CLI auth
- Endpoints needed:
  - GET /users/{username}
  - GET /users/{username}/repos?per_page=100 (paginate ALL)
  - GET /repos/{owner}/{repo}/languages
  - GET /repos/{owner}/{repo}/contents/{path} (for dep files)
  - GET /repos/{owner}/{repo}/topics
  - GET /users/{username}/events/public
  - GET /repos/{owner}/{repo}/commits?per_page=1 (for last commit date)
  - GET /repos/{owner}/{repo} (for individual repo details)

### 4. Mapping Files
Create `mappings/dependencies.yaml` with 400+ entries mapping package names
to { category, display_name } across Python, JS/TS, Go, Rust, Ruby, Java,
PHP, C#, Swift, Kotlin ecosystems. Categories: framework, database, cloud,
ai_ml, testing, build_tool, other.

Create `mappings/topics_to_domains.yaml` mapping GitHub topics to expertise
domains (e.g., "machine-learning" → "ai-ml", "kubernetes" → "devops-infra").

Create `mappings/file_patterns.yaml` mapping file/dir presence to signals
(CI, tests, docs, containers, IaC, linters).

Create `mappings/dev_type_rules.yaml` — ordered decision rules for
classifying developer type.

### 5. Extractors
Each extractor is a module in `src/devcard/extractors/` that:
- Takes the GitHub client + user data as input
- Returns a Pydantic model
- Is async
- Handles errors gracefully (missing data → null, not crash)

Build in this order:
1. identity.py — straightforward profile extraction
2. languages.py — fetch languages for each non-fork repo, weight by bytes,
   aggregate, calculate percentages, separate primary (>15%) vs secondary
3. stack.py — for each non-fork repo, check for dep files
   (package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml,
   Gemfile, pom.xml, composer.json, etc.), fetch content,
   parse deps, map via dependencies.yaml. THIS IS THE HARDEST EXTRACTOR.
   Handle: base64 decoding from GitHub contents API, TOML/JSON/text parsing,
   graceful failures on private/empty repos.
4. activity.py — analyze events for commit timestamps,
   calculate weekly heatmap, streaks, peak hours, timezone estimate
5. projects.py — rank by stars*3 + forks*2 + recency_bonus,
   classify type (library/app/tool/etc), detect status, check maturity signals
6. collaboration.py — count PushEvent/PullRequestEvent to non-owned repos,
   list orgs, classify contribution style
7. quality.py — for each original repo, check file patterns from yaml,
   calculate ratios
8. expertise.py — combine topics, dep categories, and language distribution
   to infer domains with confidence scores

### 6. Analyzers
- developer_type.py — implement the decision tree from dev_type_rules.yaml
- project_classifier.py — heuristic repo classification
- contribution_style.py — maintainer/contributor/solo-builder/explorer
- scoring.py — overall quality score (weighted composite)

### 7. CLI (core commands)
Using typer, implement:
- `devcard generate <username>` — run all extractors, build DevCard,
  output JSON to stdout or file, show rich terminal card
- `devcard validate <file>` — validate against schema
- `devcard compare <user1> <user2>` — generate both, show comparison
- `devcard me` — detect current git user, generate
- Flags: --token, --format (json|yaml|markdown|svg|html|png|all),
  --output/-o, --theme, --enrich, --model, --no-cache

### 8. SVG Card Renderer (CRITICAL FOR ADOPTION)
`src/devcard/renderers/svg_card.py`:
Build a beautiful SVG card that can be embedded in GitHub READMEs.
The card should show:
- Avatar (as embedded base64 or linked)
- Name + username + bio
- Developer type badge
- Language DNA bars (colored, proportional)
- Top 3-5 stack items as pills/badges
- Quality radar or bar indicators
- Activity status indicator
- Focus areas as tags
- "generated by devcard" footer with link

Must support themes via a theme dict that controls:
colors, fonts, border style, background.

Themes to implement:
- default (light, clean, GitHub-like)
- dark (dark background, light text)
- minimal (monochrome, no fills)
- neon (dark bg, bright accent colors)
- terminal-green (black bg, green monospace text)

SVG must be:
- Self-contained (no external resources)
- GitHub-README compatible (no foreignObject, no scripts)
- Responsive-ish (viewBox-based)
- Under 50KB typically

### 9. Other Renderers
- terminal.py — rich library panels showing the card in terminal
- markdown.py — clean markdown summary
- html_profile.py — standalone HTML page with embedded CSS
- png.py — convert SVG to PNG (for social sharing, Open Graph)

### 10. LLM Enrichment (optional)
Only runs with --enrich flag.
Uses litellm to call any LLM provider.
Generates:
- Natural language summary of the developer
- Skill level assessments (beginner/intermediate/advanced/expert)
Adds `enriched` section to devcard.json.
Default model: gpt-4o-mini.

### 11. Gallery
Pre-generate devcard.json + SVG for 30+ famous developers:
torvalds, gvanrossum, karpathy, sindresorhus, yyx990803 (Evan You),
dhh, tj, rauchg, mitchellh, kelseyhightower, dan-abramov,
ry (Ryan Dahl), Rich-Harris, antirez, fabpot, taylorotwell,
defunkt, mojombo, mdo, addyosmani, getify, mpj, ThePrimeagen,
teej_dv, etc.

Store in gallery/ with both .devcard.json and .svg files.

### 12. GitHub Action
Create action/action.yml that:
- Installs devcard
- Generates devcard.json + SVG for repo owner
- Optionally commits to the repo
- Can be triggered on schedule or manually

### 13. MCP Server
Create mcp/server.py — a minimal MCP server that exposes:
- Tool: get_devcard(username) → returns devcard.json content
- Tool: compare_devs(user1, user2) → returns comparison data

### 14. API Server
`devcard serve --port 8080` spins up a lightweight FastAPI/Starlette server:
- GET /card/{username} → devcard.json
- GET /card/{username}?format=svg → SVG card
- GET /card/{username}?format=html → HTML profile
- GET /compare/{user1}/{user2} → comparison JSON

### 15. README
Write an excellent README.md with:
- Hero: 3 SVG cards side by side (torvalds, karpathy, sindresorhus)
- One-liner + value prop
- Quick start (pipx run devcard generate YOUR_NAME)
- What it generates (screenshots of all 3 outputs)
- Compare feature with example
- Gallery link
- Themes showcase
- "For Agent Developers" section
- Schema overview
- GitHub Action setup
- "No LLM Required" section
- Contributing guide
- Apache 2.0 license badge

### 16. Tests
- Unit tests for each extractor with fixture-based mock API responses
- Unit tests for analyzers
- Unit tests for SVG renderer (output is valid SVG)
- Integration test: generate card for a known user, validate against schema
- CLI tests with typer's testing utilities

## Key technical decisions:
- All extractors are async and run concurrently where possible
  (fan out language + stack + activity extraction across repos)
- Use connection pooling in httpx client
- Cache aggressively — GitHub API responses cached for 1 hour locally
- Graceful degradation — if any extractor fails, the card still generates
  with available data (null fields, not crashes)
- SVG must NOT use foreignObject (GitHub strips it)
- SVG must NOT use external fonts (embed or use system fonts)
- All type hints, all docstrings on public functions
- Pydantic v2 models with Field descriptions for all fields
```

---

## What Makes This Survive Scrutiny

| Concern | Answer |
|---------|--------|
| "GitHub could ship this" | GitHub won't — they don't standardize *interpretive* profiles. They provide raw data. DevCard is the interpretation layer. Also, devcard.json could become the community standard that GitHub eventually supports, like how .github/ conventions emerged bottom-up. |
| "Why would developers use it?" | Vanity first (SVG cards in READMEs), utility second (agents consume it). Same adoption path as GitHub README stats (70k+ stars). |
| "No LLM = limited intelligence?" | The dependency mapping heuristic is actually MORE useful than LLM inference for this task. It's deterministic, reproducible, free, and fast. The LLM option exists for people who want richer summaries. |
| "How is this different from GitHub README stats?" | README stats show *activity metrics*. DevCard shows *identity* — what you build with, how you think, what domains you operate in. It's a semantic layer, not a metrics dashboard. |
| "Who consumes devcard.json?" | Today: developers (vanity), recruiters (evaluation). Tomorrow: AI hiring agents, OSS contribution matchers, team formation tools, code review assignment systems. The schema is future-proof. |
| "Cold start?" | No cold start. Works on anyone's profile without their involvement. Pre-generated gallery of 50 famous devs ships day 1. Compare feature drives organic sharing. |

---

*DevCard Project Plan v2 — Built for scrutiny, designed for virality.*
*Apache 2.0 · For Chirag · April 25, 2026*