asepharyana/docs/superpowers/specs/2026-07-03-profile-readme-design.md

GitHub Profile README — Ultimate Dynamic Design

Overview

Create a highly dynamic and visually stunning GitHub profile README for asepharyana/asepharyana. The README will auto-update via GitHub Actions, featuring AI-generated activity summaries, contribution visualizations, and comprehensive GitHub metrics.

Architecture

Repository Structure

asepharyana/
├── .github/
│   └── workflows/
│       ├── ai-activity.yml          # LLM-powered activity log (cron: every 6h)
│       └── snake.yml                # Contribution snake SVG (cron: daily)
├── scripts/
│   └── generate-ai-blog.js          # Fetch activity → call LLM → update README
├── assets/
│   └── generated/                   # Auto-generated SVGs (checked into git — referenced by README; seed with .gitkeep)
├── README.md                        # The main profile README
└── docs/
    └── superpowers/specs/
        └── 2026-07-03-profile-readme-design.md

Component Breakdown

Component	File	Responsibility
README Shell	README.md	Static layout with marker comments for dynamic content injection
AI Activity	scripts/generate-ai-blog.js	Fetch 7-day GitHub activity → format → send to LLM → write result
Snake Gen	.github/workflows/snake.yml	Uses Platane/snk action to render contribution grid as snake
Stats Cards	Inline in README	SVG cards via github-readme-stats API (queried at view time)

User Configuration

• GitHub username: asepharyana
• LinkedIn: https://www.linkedin.com/in/asep-haryana-saputra-2014a5294/
• Website: https://asepharyana.my.id/
• AI LLM API: sk-5dd268d88adb496b-818beb-6bc7498e @ https://omniroute.imrnes.team/v1 model text
• Role: Mahasiswa | AI Enthusiast

README Layout & Section Design

1. Header — Hero Section

• Custom banner (generated SVG or GitHub banner)
• Animated typing effect via markdown-compatible approach (JavaScript/CSS not available — use GIF from readme-typing-svg or similar SVG service)
• Name, tagline, role badges
• Visitor counter badge

2. Tech Stack Badges

• Grouped by category: Languages, AI/ML, Tools
• Shields.io badges with flat design
• Dark mode compatible

3. GitHub Stats Dashboard

• 3-column layout using HTML tables/grid in markdown:
  • GitHub Stats card (github-readme-stats)
  • GitHub Streak card (github-readme-streak-stats)
  • Top Languages card (github-readme-stats)
• GitHub Trophies row below stats (github-profile-trophy)

4. AI Activity Log (Dynamic via Actions)

• Section markers: <!--AI_ACTIVITY_START--> / <!--AI_ACTIVITY_END-->
• Replaced every 6 hours by generate-ai-blog.js
• Content: 2-3 sentences in casual Indonesian with emojis
• Describes: recent commits, new repos, merged PRs, opened issues
• Fallback: "Belum ada aktivitas GitHub dalam 7 hari terakhir. Pantau terus! 🚀"

5. Contribution Snake

• Animated SVG showing contribution grid as a snake eating squares
• Dark mode variant
• Generated daily via snake.yml

6. Connect & Footer

• Social links row: LinkedIn, Website, Email (if public)
• "Visitors" count badge
• Fun fact section

AI Activity Generator — Detailed Spec

Workflow: .github/workflows/ai-activity.yml

name: AI Activity Log
on:
  schedule:
    - cron: "0 */6 * * *"   # every 6 hours at :00
  push:
    branches: [main]
  workflow_dispatch:         # manual trigger

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Generate AI activity log
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          AI_LLM_API_KEY: ${{ secrets.AI_LLM_API_KEY }}
          AI_LLM_BASE_URL: ${{ secrets.AI_LLM_BASE_URL }}
          AI_LLM_MODEL: ${{ secrets.AI_LLM_MODEL }}
        run: node scripts/generate-ai-blog.js

      - name: Commit README changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add README.md
          git diff --staged --quiet || git commit -m "chore: update AI activity log [skip ci]"
          git push

Script: scripts/generate-ai-blog.js

Input:

1. GitHub Events API — /users/{username}/events?per_page=100
2. Filter: only events from last 7 days
3. Normalize to structured format:
   • PushEvent → {type: "commit", repo, branch, message_preview}
   • CreateEvent → {type: "create", repo, ref_type: "repo"|"branch"}
   • PullRequestEvent → {type: "pr", repo, action: "opened"|"merged"|"closed"}
   • IssuesEvent → {type: "issue", repo, action, title}
   • WatchEvent → {type: "star", repo}
   • ForkEvent → {type: "fork", repo}
4. Deduplicate: group same repo + same type

LLM Call:

POST {base_url}/chat/completions
Authorization: Bearer {api_key}

{
  "model": "{model}",
  "messages": [
    {
      "role": "user",
      "content": "Buat summary aktivitas GitHub dalam bahasa Indonesia kasual, maksimal 3 kalimat, pakai emoji. Jangan pake format list. Langsung kontennya aja:\n\n{formatted_activity}"
    }
  ],
  "max_tokens": 300,
  "temperature": 0.7
}

Output: Replace content between <!--AI_ACTIVITY_START--> and <!--AI_ACTIVITY_END--> in README.md.

Error Handling:

• If GitHub API fails (no token, rate limit): skip block, keep previous content
• If LLM API fails (timeout, bad response, auth error): use fallback text
• If no activity in 7 days: fallback text
• If README markers not found: log error, exit 0 (don't fail action)

GitHub Actions — All Workflows

Snake Contribution

name: Generate Snake
on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Platane/snk@v3
        with:
          github_user_name: asepharyana
          outputs: |
            assets/generated/snake.svg?palette=github-dark
            assets/generated/snake-light.svg?palette=github-light
      - uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "chore: update contribution snake [skip ci]"

Note: GitHub stats cards (github-readme-stats, github-readme-streak-stats, github-profile-trophy) load dynamically at view time via <img> URLs — no Action needed. They're not committed files.

Error Handling & Resilience

Failure Mode	Detection	Recovery
LLM API down	HTTP error / timeout	Keep previous AI log content, log warning
GitHub API rate limited	403/429 response	Wait & retry once, then skip
Snake generation fails	Action exit code	Previous snake SVG stays cached
README edit conflict	git push rejected	Retry on next cron trigger
No events in 7 days	Empty filtered data	Write fallback "No recent activity" message
Missing section markers	Script can't find delimiters	Append section, mark as degraded
API key missing from secrets	Empty env var	Graceful skip with Action annotation

Commit Strategy

• All auto-commits use [skip ci] suffix to prevent infinite Action loops
• Author: github-actions[bot]
• Human edits to README only via direct push — next Action run won't overwrite marker-delimited sections that have changed since last fetch (we always re-fetch and re-write between markers)
• The entire <!--AI_ACTIVITY_START-->...</AI_ACTIVITY_END--> block is owned by the script — any human edits inside it will be overwritten on next run

Success Criteria

• README renders with all sections visible on profile
• AI Activity section updates autonomously every 6 hours
• Snake animation appears and animates on profile
• Stats cards show accurate GitHub data
• All social links point to correct URLs
• Dark mode renders correctly (no invisible text/images)
• All error states produce graceful fallbacks visible to viewers
• No actions fail silently — failures are logged and non-fatal