github-empire · diff
git:20260526.a2a18ed to git:20260921.a2e8de7
114 added, 660 removed. Audit A to A.
---
name: github-empire
- description: Portfolio-level GitHub empire builder — scans presence, builds profile README, syncs topics, cross-links repos, generates avatars.
+ description: Review and improve a scoped GitHub portfolio, profile, related-project navigation, and metadata. Prepare concrete local drafts and apply only authorized account or repository changes.
---
- # GitHub Empire -- Build Your GitHub Presence
-
- ## Role
-
- You are an **empire architect**. You don't hand someone a list of things to fix and
- walk away. You survey the land, draw the blueprints, get approval, and then build
- it -- right now, in this session.
-
- Your mindset:
- - "Your bio is empty. I'll write one with your niche keywords and set it via API.
- Approve this text and I'll push it live in 3 seconds."
- - "Five repos, zero shared topics. I'll unify them under a core topic set and push
- all 5 updates in a single batch. Here's what each repo will look like after."
- - "No profile README? I'll create the repo, write the README, and push it. You'll
- see it on your profile page before this conversation ends."
- - "Your cross-linking is nonexistent. I'll write the exact markdown and inject it
- into each README. Review the diffs, say yes, and it's done."
-
- **The philosophy:** Everything the GitHub API can do, you do. Everything it can't,
- you hand-hold with direct links and numbered steps. The user should finish this
- session with a transformed GitHub presence, not a homework assignment.
-
- **Be opinionated.** Don't hedge. If a repo should be archived, say so. If a bio
- line is weak, rewrite it. If topics are scattered, unify them. You're the expert --
- act like it.
-
- ## What You Can Automate (GitHub API)
-
- These actions require NO manual steps. You execute them directly after user approval:
-
- | Action | API Command |
- |--------|-------------|
- | Set bio | `gh api user -X PATCH -f bio="..."` |
- | Set location | `gh api user -X PATCH -f location="..."` |
- | Set company | `gh api user -X PATCH -f company="..."` |
- | Set website URL | `gh api user -X PATCH -f blog="..."` |
- | Set Twitter/X handle | `gh api user -X PATCH -f twitter_username="..."` |
- | Update repo description | `gh api repos/{owner}/{repo} -X PATCH -f description="..."` |
- | Update repo homepage URL | `gh api repos/{owner}/{repo} -X PATCH -f homepage="..."` |
- | Set repo topics | `gh api repos/{owner}/{repo}/topics -X PUT --input -` (JSON body: `{"names":["topic1","topic2"]}`) |
- | Enable Discussions | `gh api repos/{owner}/{repo} -X PATCH -f has_discussions=true` |
- | Enable Wiki | `gh api repos/{owner}/{repo} -X PATCH -f has_wiki=true` |
- | Create profile README repo | `gh repo create {username}/{username} --public --description "Profile README"` |
- | Archive a repo | `gh api repos/{owner}/{repo} -X PATCH -f archived=true` |
-
- ## What Requires Manual Steps (No API)
-
- For these, provide **direct links + numbered instructions** so the user can do it
- in under 60 seconds:
-
- | Action | Why Manual | How to Hand-Hold |
- |--------|-----------|-----------------|
- | Profile photo | No upload API | Generate avatar, provide `file:///` link + https://github.com/settings/profile |
- | Pin repos | No API for pins | List exact repos in order + https://github.com/{username}?tab=repositories |
- | Social preview image | Requires web upload | Generate image, provide `file:///` link + https://github.com/{owner}/{repo}/settings |
- | Enable GitHub Sponsors | Requires enrollment | https://github.com/sponsors/accounts |
-
- **UX rule:** Never say "go update your bio." Say "Here's your new bio. Approve it
- and I'll set it right now." Never say "you should pin these repos." Say "Pin these
- 6 repos in this order: [list]. Go to https://github.com/{username}?tab=repositories
- and click 'Customize your pins.'"
-
- ## Headless Contract
-
- For deterministic CLI/API use, the shipped runner now exposes:
-
- ```bash
- python3 scripts/run_headless.py empire --path /path/to/repo
- python3 scripts/run_headless.py empire --path /path/to/repo --username your-login
- python3 scripts/run_headless.py empire --path /path/to/repo --generate-avatar
- ```
-
- This writes `.github-audit/empire-data.json` plus `EMPIRE-REPORT.md`,
- `EMPIRE-BLUEPRINT.md`, `PROFILE-README-DRAFT.md`, and `EMPIRE-SUMMARY.json`.
- The runner builds a deterministic portfolio blueprint, profile README draft,
- cross-link plan, and explicit `gh` commands without auto-applying account-wide
- mutations. `--generate-avatar` creates `assets/avatar.jpg` when KIE and Pillow
- are available. Pin ordering and final profile-photo upload remain GitHub web UI
- steps and must stay explicit.
-
- ## Process (GARE Pattern)
-
- ### 1. Gather
-
- **Step 0 -- Check shared data cache:**
- Check `.github-audit/` for cached data from other skills.
- Reference: `github/references/shared-data-cache.md` for schemas.
-
- - `audit-data.json` (recommended) -- per-repo scores from `github-audit`. If available,
- use scores directly. If missing, gather lightweight metrics yourself and note:
- "Run `github-audit {username}` for detailed per-repo scoring."
- - `seo-data.json` (optional) -- keyword landscape for profile README SEO.
- - `empire-data.json` (optional) -- **previous Empire run**. If found, load it for
- growth delta reporting. Compare stars, views, topic counts, and portfolio health
- score against the previous snapshot.
- - `repo-context.json` (optional) -- per-repo metadata.
-
- **Portfolio data (REQUIRED -- always gather these):**
- ```bash
- # All public repos with key metrics
- gh repo list {username} --visibility public --limit 500 --json name,description,repositoryTopics,stargazerCount,forkCount,primaryLanguage,updatedAt,licenseInfo,homepageUrl
-
- # Check for profile README repo
- gh repo view {username}/{username} --json name,description 2>/dev/null
-
- # User profile details
- gh api users/{username} --jq '{name, bio, blog, twitter_username, company, location, public_repos, followers, following, type, avatar_url}'
-
- # Traffic for each repo (requires push access -- may fail for non-owned repos)
- # Run for each repo: gh api repos/{owner}/{repo}/traffic/views --jq '{views: .count, uniques: .uniques}'
- ```
-
- **Competitor landscape (lightweight):**
- ```bash
- # Find similar repos in the user's niche for competitive context
- gh search repos "{primary_niche_keyword}" --limit 10 --json fullName,stargazersCount,description --sort stars
- ```
-
- **SEO data for portfolio strategy:**
- - If DataForSEO MCP is available AND `seo-data.json` is missing: **just run it.**
- No cost confirmation needed -- the cost is ~10-15 cents total, negligible.
- Generate 2 seed keywords from the user's dominant niche (most common topics
- across repos). Call `dataforseo_labs_google_keyword_suggestions` for each seed.
- Use the results for topic authority analysis and profile README keyword optimization.
- - If DataForSEO is NOT configured: note it in the output and encourage setup:
- "DataForSEO is not configured. SEO recommendations are based on GitHub search
- analysis only. For live keyword data, set it up in 5 minutes:
- https://dataforseo.com -- then run the install script in extensions/dataforseo/."
- Proceed with `gh search repos` competitor analysis as fallback.
-
- ### 2. Analyze
-
- #### Portfolio Health Score (0-100)
-
- Compute this FIRST. It's the headline number for the entire report.
-
- | Dimension | Weight | How to score |
- |-----------|--------|-------------|
- | Profile completeness | 20 pts | Custom profile photo (3), bio with keywords (4), profile README (8), location/company (2), blog/twitter (3) |
- | Branding consistency | 20 pts | Description pattern (5), homepage URLs correct (5), license consistency (5), badge usage (5) |
- | Topic authority | 20 pts | Owned topics with 2+ repos (10), no missing high-value topics (5), no over-tagged repos (5) |
- | Repo health signals | 20 pts | All repos have recognized license (5), all have 5+ topics (5), all updated within 3 months (5), flagship repo has 1+ stars (5) |
- | Discovery readiness | 20 pts | SEO keywords in descriptions (5), cross-linking exists (5), social preview set (5), README has badges (5) |
-
- If a previous empire-data.json exists, show the delta:
- **Portfolio Health: 38/100 (+12 since March 8)**
-
- #### Portfolio Identity
-
- Derive 1-2 sentences that define what this developer stands for. This is NOT assumed --
- it comes from analyzing the actual repos, their topics, and their descriptions.
-
- This identity drives every decision downstream: bio text, profile README narrative,
- which repos to pin, which topics to unify, what to build next.
-
- #### Per-Repo Assessment
-
- | Repo | Stars | Language | Topics | License | Last Updated | Health |
- |------|-------|----------|--------|---------|-------------|--------|
- | ... | ... | ... | ... | ... | ... | Strong/Needs Work/Weak |
-
- For repos marked "Weak": is this dead weight or recoverable? Dead weight gets an
- archive recommendation. Recoverable gets targeted actions.
-
- #### Branding Consistency
-
- Check across all repos:
- - **Descriptions:** Consistent voice? Keywords present? Action-oriented?
- - **Topics:** Shared core set across related repos? Or fragmented?
- - **Licenses:** Same license family? Mixed without reason?
- - **Homepage URLs:** Pointing somewhere useful? Or empty/broken?
- - **Badges:** Consistent style? Or some repos with badges, some without?
- - **README structure:** Similar format? Or wildly different?
-
- #### Topic Authority Map
-
- - **Owned topics:** Topics appearing on 2+ repos (authority signal to GitHub)
- - **Orphan topics:** Topics on only 1 repo (no reinforcement)
- - **Missing high-value topics:** Common topics in the niche that the user doesn't use
- - **Topic clusters:** Group related topics, map which repos belong to each
- - **Over-tagged repos:** 15+ topics dilute signal -- recommend trimming
-
- #### Competitive Position
-
- Based on the competitor landscape gathered in Step 1:
- - Where does the user's portfolio rank in their niche? (stars, repo count, topic coverage)
- - What do top competitors have that this portfolio lacks?
- - What unique angles does this portfolio have that competitors don't?
-
- #### Ecosystem Gap Analysis
-
- Based on the portfolio identity and competitive landscape:
- - **What's missing?** If the user has SEO tools for 2 AI platforms but not a third,
- that's a gap. If they have CLI tools but no documentation site, that's a gap.
- - **What to build next?** Concrete project suggestions with reasoning.
- - **What to stop?** Repos that dilute the brand more than they contribute.
-
- Only include this section if the analysis reveals genuine strategic gaps. Don't
- manufacture suggestions for the sake of filling a section.
-
- ### 3. Recommend -- The Empire Blueprint
-
- **The Blueprint is not the deliverable. The built empire is.**
-
- The Blueprint is what the user reviews before you execute. Keep it focused on
- decisions that need approval, not analysis they need to read.
-
- #### TL;DR (always first)
-
- 3-4 sentences max:
- 1. Portfolio identity (who they are)
- 2. Biggest problem (what's broken)
- 3. What you're about to build (not "what they should do")
- 4. Portfolio Health Score (with delta if available)
-
- Example:
- > **TL;DR:** Your portfolio says "SEO tools for every AI CLI" but your GitHub
- > doesn't show it -- no bio, no profile README, fragmented topics. I'm going to
- > set your bio, create your profile README, unify topics across all 5 repos, and
- > inject cross-links. **Portfolio Health: 38/100.**
-
- #### The Build Plan
-
- This is the core of the Blueprint. Present it as a numbered action list with
- clear tags showing what happens:
-
- ```
- ## Build Plan
-
- ### Automated (I'll execute these via API after your approval)
- 1. [PROFILE] Set bio: "Developer building SEO optimization tools for AI-powered CLIs -- Codex and other AI CLIs"
- 2. [PROFILE] Set website: https://avalonreset.com
- 3. [REPO] Create avalonreset/avalonreset repo with profile README (draft below)
- 4. [TOPICS] Sync topics across all repos:
- - codex-seo: +seo-tools, +ai-cli, +developer-tools
- - codex-seo: +seo-tools, +ai-cli, +developer-tools
- - legends-github: +ai-cli, +developer-tools
- 5. [DESCRIPTION] Rewrite BenjaminTerm description: "Modern terminal emulator for Windows..."
- 6. [CROSS-LINK] Add "See Also" sections to codex-seo and codex-seo READMEs
-
- ### Manual (I'll guide you step-by-step with direct links)
- 7. [PIN] Pin these 6 repos in order: [list]
- -> https://github.com/{username}?tab=repositories -> "Customize your pins"
- 8. [PHOTO] Upload profile avatar (generating now...)
- -> file:///path/to/avatar.jpg
- -> https://github.com/settings/profile -> Click avatar -> Upload
-
- ### Future (run these sub-skills next)
- 9. [SKILL] Run `github-readme` on BenjaminTerm (weakest README)
- 10. [SKILL] Run `github-audit` for detailed per-repo scoring
-
- Approve all, or tell me which ones to execute.
- ```
-
- **Tag meanings:**
- - `[PROFILE]` -- modifies your public GitHub profile (immediate, visible to everyone)
- - `[REPO]` -- creates a new public repository
- - `[TOPICS]` -- modifies repository topic tags
- - `[DESCRIPTION]` -- modifies repository description
- - `[CROSS-LINK]` -- modifies README files (local, requires push)
- - `[PIN]` -- manual action with step-by-step guidance
- - `[PHOTO]` -- manual action with generated asset + guidance
- - `[SKILL]` -- recommended follow-up skill to run
- - `[ARCHIVE]` -- archives a repository (reversible but visible)
-
- #### Profile README Draft
-
- If no profile README exists, draft one inline so the user can review it as part
- of the Build Plan approval. This is the single most impactful deliverable.
-
- **Content strategy:**
- - Lead with identity and niche keywords (SEO -- GitHub profiles ARE indexed by Google)
- - "What I Build" section references topic clusters, not just repo names
- - Featured projects table shows ONLY the best 3-4 repos with stars
- - Tech stack badges match languages actually used
- - If seo-data.json exists, weave the primary keyword into the first paragraph
- - Links use descriptive anchor text, not "click here"
-
- **Structure:**
- ```markdown
- # Hi, I'm [Name]
-
- [1-2 sentence bio with niche keywords]
-
- ## What I Build
- [Narrative paragraph derived from topic clusters]
-
- ## Featured Projects
- | Project | Description | |
- |---------|-------------|---|
- | [repo](link) | [description] | stars badge |
-
- ## Tech Stack
- [shields.io language/framework badges]
-
- ## Connect
- [Only links that exist -- website, social, email]
- ```
-
- #### Pinned Repos Recommendation
-
- Recommend exactly which repos to pin and in what order. Reasoning for each slot:
- - Slot 1-2: Flagship projects (highest impact/stars)
- - Slot 3-4: Supporting projects that reinforce the identity
- - Slot 5-6: Range demonstrators or emerging projects
-
- Provide the direct link: `https://github.com/{username}?tab=repositories`
- and instruct: "Click 'Customize your pins' in the top-right."
-
- #### Cross-Linking Strategy
-
- Don't just recommend cross-links. **Write the exact markdown** that will be
- injected into each README. Specify:
- - Which README file
- - Where in the file (after which section)
- - The exact markdown block
-
- Example:
- ```markdown
- ## Related Projects
-
- - **[codex-seo](https://github.com/avalonreset/codex-seo)** -- SEO optimization for OpenAI Codex CLI
- - **[codex-seo](https://github.com/avalonreset/codex-seo)** -- SEO optimization for OpenAI Codex CLI
- ```
-
- **Directionality matters:** Flagship repos should receive more inbound links than
- they send. New/small repos link UP to flagships. Flagships link ACROSS to peers.
-
- ### 4. Execute (after explicit user approval)
-
- **Nothing executes without a "yes."** But once you get it, move fast.
-
- #### Execution Order
-
- 1. **Profile fields** (bio, location, company, website, twitter)
- 2. **Profile README** (create repo if needed, write README, push)
- 3. **Topic synchronization** (batch-update all repos)
- 4. **Description rewrites** (batch-update all repos)
- 5. **Feature toggles** (enable Discussions, etc.)
- 6. **Cross-linking** (write markdown into READMEs -- local, needs push)
- 7. **Avatar generation** (if requested -- takes ~30 seconds)
- 8. **Manual guidance** (pins, social previews, photo upload)
-
- #### Profile Field Updates
-
- Execute all approved profile changes in a single API call:
- ```bash
- gh api user -X PATCH \
- -f bio="Your approved bio text" \
- -f blog="https://yoursite.com" \
- -f location="City, State" \
- -f company="@org-name" \
- -f twitter_username="handle"
- ```
-
- Only include fields that are changing. Verify after:
- ```bash
- gh api users/{username} --jq '{bio, blog, location, company, twitter_username}'
- ```
-
- Show the user: "Profile updated. Verify at: https://github.com/{username}"
-
- #### Profile README Repo Creation
-
- ```bash
- # Create the repo
- gh repo create {username}/{username} --public --description "Profile README"
-
- # Clone, write README, push
- git clone https://github.com/{username}/{username}.git /tmp/{username}-profile
- # Write the approved README content to /tmp/{username}-profile/README.md
- cd /tmp/{username}-profile && git add README.md && git commit -m "Add profile README" && git push
- ```
-
- Show the user: "Profile README is live. View at: https://github.com/{username}"
-
- If the profile README repo already exists, clone it, update README.md, and push.
-
- #### Topic Synchronization
-
- For each repo with topic changes:
- ```bash
- gh api repos/{owner}/{repo}/topics -X PUT --input - <<< '{"names":["topic1","topic2","topic3"]}'
- ```
-
- **Critical:** This REPLACES all topics, not appends. Always include existing topics
- that should be kept, plus the new ones.
-
- Show a before/after for each repo so the user can verify.
-
- #### Description Rewrites
-
- ```bash
- gh api repos/{owner}/{repo} -X PATCH -f description="New keyword-optimized description"
- ```
-
- #### Cross-Link Injection
-
- For each README that needs cross-links:
- 1. Clone the repo (or work in the local directory if it's the current repo)
- 2. Read the current README
- 3. Insert the approved cross-link section at the specified location
- 4. Commit with message: "Add cross-links to related projects"
- 5. Push (or note: "Cross-links written locally. Push when ready.")
-
- #### Archive Recommendations
-
- If the user approved archiving dead repos:
- ```bash
- gh api repos/{owner}/{repo} -X PATCH -f archived=true
- ```
-
- Note: Archiving is reversible. The repo becomes read-only but remains visible.
-
- ### 5. Verify
-
- After all executions complete, run a quick verification pass:
-
- ```bash
- # Re-fetch profile to confirm changes
- gh api users/{username} --jq '{bio, blog, location, company, twitter_username}'
-
- # Check profile README is live
- gh api repos/{username}/{username}/contents/README.md --jq '.name' 2>/dev/null
-
- # Spot-check topics on 2-3 repos
- gh repo view {owner}/{repo1} --json repositoryTopics
- gh repo view {owner}/{repo2} --json repositoryTopics
- ```
-
- Present a summary:
- ```
- ## Empire Build Complete
-
- ### What Changed
- - Profile bio: set (was: empty)
- - Profile website: set (was: empty)
- - Profile README: created (was: missing)
- - Topics synchronized: 5 repos updated
- - Descriptions rewritten: 2 repos
- - Cross-links added: 3 READMEs (local -- push when ready)
-
- ### Portfolio Health: 62/100 (+24 from 38)
-
- ### Manual Steps Remaining
- 1. Pin repos: [link]
- 2. Upload avatar: [link]
-
- ### Recommended Next Steps
- - Run `github-audit {username}` for detailed per-repo scoring
- - Run `github-readme` on [weakest repo] to improve its README
- ```
-
- ## Portfolio Pruning
-
- Don't just recommend what to add -- recommend what to **stop doing.** Frame it
- as "focusing your signal" not "your work is bad."
-
- - **Dead repos:** No commits in 6+ months, 0 stars, 0 traffic -- recommend archive
- - **Off-brand repos:** Don't fit the portfolio identity -- recommend unpin or archive
- - **Duplicate effort:** Two repos doing the same thing -- recommend merging or differentiating
- - **Abandoned experiments:** No README, no license, 1-2 commits -- recommend making private
-
- If the user approves archiving, execute it via API immediately.
-
- ## Portfolio Size Handling
-
- Scale the depth of analysis to the portfolio size:
-
- - **1-5 repos (small):** Compact report. Combine Branding + Topics into one section.
- Skip Pruning if nothing to prune. Total: ~6 sections.
- - **6-15 repos (medium):** Full report with all sections. This is the default.
- - **16+ repos (large):** Full report with top-5/bottom-5 highlights. Summarize and
- call out outliers rather than listing every repo in every table.
-
- **Hard cap:** Deep-dive analysis on max 15 repos. For larger portfolios, focus
- on the top 15 by stars + recency and note: "Analyzed top 15 repos. Run
- `github-audit` on specific repos for detailed scoring."
-
- ## Organization Profiles
-
- If the user has a GitHub org:
- - Create/optimize `.github` repo with `profile/README.md` (org profile README)
- - Set up default community health files that inherit to all org repos
- - Recommend org-level settings (verified domain, member visibility)
- - Use the same API automation approach -- create repo, push files, verify
-
- ## Avatar Generation (Profile Photo via KIE.ai)
-
- When the user confirms they have a default identicon (or wants a new profile photo),
- generate one using KIE.ai GPT Image 2. Reference:
- `github/references/banner-generation.md` for API mechanics.
-
- ### Avatar vs Banner -- Different Goals
-
- | | Banner (README header) | Avatar (profile photo) |
- |--|----------------------|----------------------|
- | Aspect ratio | 21:9 (ultrawide cinematic) | **1:1** (square) |
- | Purpose | Showcase the project | Represent the person/brand |
- | Text | Project name + tagline | **Minimal or none** -- GitHub shows username next to it |
- | Style | Cinematic, detailed, dramatic | **Bold, simple, iconic** -- must read at 40px |
- | Complexity | Rich scenes with multiple elements | **One strong focal element** |
-
- ### Avatar Design Strategy
-
- **The #1 rule: it must read at 40x40 pixels.** GitHub displays avatars at tiny sizes
- in comments, commit lists, and PR reviews. Think app icon, not movie poster.
-
- **What works:**
- - A single bold letter or monogram (first initial, stylized)
- - An abstract geometric mark (hexagon, shield, circuit pattern)
- - A clean icon representing the user's niche (terminal cursor, code brackets, etc.)
- - Strong contrast between foreground and background
- - Flat or minimal gradients -- not photorealistic
-
- **What does NOT work:**
- - Faces or portraits (AI faces look uncanny and age poorly)
- - Detailed scenes with multiple objects
- - Thin lines or small details (invisible at 40px)
- - Text-heavy designs (username already shown by GitHub)
- - Photorealistic renders (look out of place among GitHub avatars)
-
- ### Prompt Strategy
-
- **Keep it under 80 words.**
-
- **The formula:**
- ```
- Square 1:1 profile avatar. [SUBJECT]: [single bold element, described simply].
- [STYLE]: [flat/geometric/minimal, color palette]. [BACKGROUND]: [solid or simple
- gradient]. Clean, high contrast, reads well at small sizes.
- ```
-
- ### Example Prompts
-
- **Developer/coder identity:**
- ```
- Square 1:1 profile avatar. A bold geometric letter "B" made of glowing
- cyan circuit traces on a dark navy background. Clean flat design, no
- gradients, high contrast. Minimal and iconic, reads well at small sizes.
- ```
+ # GitHub portfolio and profile workflows
- **SEO/tools niche:**
- ```
- Square 1:1 profile avatar. A stylized magnifying glass with a code
- bracket inside the lens, glowing teal on a deep charcoal background.
- Flat geometric style, bold shapes, high contrast. Simple and iconic.
- ```
+ Help visitors understand related projects and choose a useful starting point.
+ Keep individual repository differences and maintenance commitments visible.
- **Abstract/branded:**
- ```
- Square 1:1 profile avatar. An abstract hexagonal shield shape with
- intersecting geometric lines forming a subtle "A" pattern. Electric
- purple and deep blue gradient on black background. Flat, bold, minimal.
- ```
+ ## Runtime and scope
- ### API Parameters
+ Resolve **GITHUB_HOME** from this skill directory: `../../github` in source,
+ `../github` when installed. Verify `scripts/run_headless.py` exists and read
+ `GITHUB_HOME/references/portable-workflows.md`. Resolve **TARGET** separately.
- ```bash
- curl -X POST https://api.kie.ai/api/v1/jobs/createTask \
- -H "Authorization: Bearer $KIE_API_KEY" \
- -H "Content-Type: application/json" \
- -d '{
- "model": "gpt-image-2-text-to-image",
- "input": {
- "prompt": "YOUR_AVATAR_PROMPT_HERE",
- "aspect_ratio": "1:1"
- }
- }'
+ ```text
+ python "<GITHUB_HOME>/scripts/run_headless.py" empire --help
+ python "<GITHUB_HOME>/scripts/run_headless.py" empire --path "<TARGET>" --username OWNER
```
- **Key differences from banners:**
- - `aspect_ratio`: **"1:1"** (not "21:9")
- - Source file: keep the KIE result as the lossless original, then convert after download
- - Resolution: default KIE GPT Image 2 output is fine (GitHub resizes to 460x460 anyway)
+ The runtime writes `empire-data.json`, `EMPIRE-REPORT.md`, `EMPIRE-BLUEPRINT.md`,
+ `PROFILE-README-DRAFT.md`, and `EMPIRE-SUMMARY.json`. The blueprint and emitted
+ commands do not automatically apply account changes. Inspect portfolio coverage,
+ source freshness, and intended owner before treating its conclusions as complete.
- ### Post-Download Conversion (required -- strip metadata + convert to WebP)
+ A user profile, organization profile, and repository collection are different
+ targets. Resolve the user's intended owner and included repositories. Do not
+ expand a public portfolio task to private repositories or unrelated accounts.
- ```python
- from PIL import Image
- import os
+ ## Gather a bounded portfolio view
- src = Image.open("assets/avatar-source.png")
- # Strip all metadata: create fresh image from pixel data only
- clean = Image.new(src.mode, src.size)
- clean.putdata(list(src.getdata()))
- # WebP, quality 80, method 6 (slowest encode = smallest file)
- clean.convert("RGB").save("assets/avatar.jpg", "JPEG", quality=85, optimize=True)
- os.remove("assets/avatar-source.png")
- ```
+ - Read the owner/profile and requested repository inventory from current GitHub
+ data when available. Use explicit owner/repo arguments and appropriate limits.
+ Identify truncation, pagination, filters, forks, archived repos, and omitted items.
+ - Inspect descriptions, primary audience, capabilities, docs, installation,
+ maintenance policy, release/distribution routes, and relevant local changes.
+ - Read existing profile README content before proposing a replacement. Account
+ biography fields and verified public links are useful; private contact details
+ or inferred personal attributes are not portfolio copy.
+ - Use prior audits/research as optional context after identity and freshness
+ checks. A full audit of every repository is not a prerequisite for a profile
+ edit. A lightweight inventory is not a full source-quality audit.
+ - For large collections, select deeper reviews by the user's priorities and
+ representative project types, state the sample, and preserve coverage gaps.
+ Stars and recency can be context but should not be the only selection rule.
- WebP is the preferred delivery format (~30% smaller than JPEG at equivalent quality).
- Metadata is stripped to remove AI generation data, tool signatures, and color profiles.
- GitHub renders WebP natively. Use JPEG only if the user specifically requests it.
+ Record **observed**, **unavailable**, and **not_applicable** per finding. Missing
+ access to traffic or profile settings is unavailable, never a zero or a failed
+ quality check. A private repository need not participate in a public portfolio.
- ### Post-Generation UX
+ ## Shape a useful portfolio
- 1. Save as JPEG via the avatar pipeline (see banner-generation.md "Applying This to Avatars")
- 2. **Show it inline** using the Read tool on `assets/avatar.jpg`
- 3. **Provide a clickable file link:**
- ```
- Avatar saved: file:///[absolute-path]/assets/avatar.jpg
- ```
- 4. Ask: "Here's your profile avatar. Use it, regenerate, or skip?"
- 5. If approved, provide **upload instructions with direct links**:
- ```
- To set as your GitHub profile photo:
- 1. Go to: https://github.com/settings/profile
- 2. Click your current avatar (or "Upload a photo")
- 3. Select: file:///[absolute-path]/assets/avatar.jpg
- 4. Crop/adjust and save
- ```
- There is NO API for profile photos. This is the one manual step we can't avoid.
- **Format note:** Always deliver as JPEG. GitHub rejects WebP and PNGs often exceed the 1MB upload limit.
+ | Area | Look for | Action when supported |
+ |---|---|---|
+ | Identity | Actual work, audience, verified expertise | Concise bio/profile copy linking relevant projects |
+ | Featured projects | Working, distinctive projects serving the objective | Recommend a useful order with a reason per selection |
+ | Project grouping | Shared audience or complementary workflows | Group by user problem and explain differences |
+ | Topics/descriptions | Accurate common concepts and project-specific features | Correct mismatches while retaining meaningful differences |
+ | Cross-links | A reader's logical next step | Link docs, companion tools, examples, or integrations |
+ | Support/maintenance | Stated ownership, support channels, superseded tools | Clarify current status and maintained alternatives |
+ | Distribution | Actual install and release paths | Fix missing navigation to verified artifacts/docs |
- ### Profile Photo Detection
+ Do not clone the same topics or positioning onto all repositories. Do not infer
+ that a collection needs more projects to fill a marketing matrix. Recommend
+ archiving, merging, unpinning, or visibility changes only when supported by the
+ owner's intent and actual project state, never from low stars or age alone.
+ Those actions require exact target authorization.
- There is no API flag for "custom vs default." Download the avatar image with curl,
- then use the Read tool to show it inline:
- ```bash
- curl -sL "AVATAR_URL" -o /tmp/github-avatar.jpg
- ```
- Then `Read /tmp/github-avatar.jpg` to display it. Do NOT use WebFetch on image URLs.
- Ask: "Is this your custom profile photo, or the default GitHub identicon?"
+ Cross-links should serve readers. Describe the concrete relationship and where
+ to continue; avoid reciprocal link schemes, repeated promotional blocks, and
+ claims that inbound link direction establishes ranking authority.
- ### When NOT to Generate
+ ## Prepare a concrete change set
- - User already has a custom photo they're happy with
- - User explicitly declines
- - KIE_API_KEY is not configured (guide them to set it up, don't block the rest of the build)
+ Produce a concise table with target, current state, proposed text/diff, evidence,
+ and local versus external effect. Prepare profile copy, README edits, and payloads
+ before any required approval. If edits are already authorized, proceed through
+ verification without a redundant blueprint approval ritual.
- ### Handling Failures
+ A profile README can include a short accurate introduction, useful project groups,
+ a small featured-project table, and verified public links. Badges, metrics,
+ avatars, keyword quotas, and claims of authority are optional. Retain original
+ credits and avoid publishing private plans or invented experience.
- 1. Regenerate with same prompt (87% text accuracy, but avatars have minimal text)
- 2. Simplify the prompt further
- 3. Avatars rarely need the Pillow fallback since they typically have little or no text
+ For personal profiles, verify the supported owner/owner repository convention.
+ For organization profiles, verify the current `.github/profile/README.md` layout
+ and applicable default-policy inheritance before creating content. Creating a
+ public repository or changing account settings is distinct from writing a local
+ draft and must be within the request.
- ## Growth Tracking
+ ## Apply safely to the intended identity
- Every Empire run captures a snapshot. On subsequent runs, show deltas.
+ Before authenticated profile edits, check that the current authenticated identity
+ matches the intended account. `gh api user` targets that authenticated user;
+ changing its fields will not update an arbitrary username or organization.
+ Use the correct documented organization endpoint for organization changes.
- ```bash
- # Stars
- gh api repos/{owner}/{repo} --jq '.stargazers_count'
+ Use exact UTF-8 JSON payload files or structured arguments for complex text.
+ Examples below are external operations and require the scoped user request:
- # Traffic (requires push access)
- gh api repos/{owner}/{repo}/traffic/views --jq '{views: .count, uniques: .uniques}'
- gh api repos/{owner}/{repo}/traffic/clones --jq '{count: .count, uniques: .uniques}'
+ ```text
+ gh api user --method PATCH --input "<APPROVED_PROFILE_PAYLOAD.json>"
+ gh repo edit OWNER/REPO --description "Accurate project-specific description"
+ gh api repos/OWNER/REPO/topics --method PUT --input "<APPROVED_TOPICS_PAYLOAD.json>"
```
- **Delta reporting:** If empire-data.json exists from a previous run, compare:
- - Portfolio Health Score: 38 -> 62 (+24)
- - Total stars: 12 -> 18 (+6)
- - Per-repo changes: "codex-seo: 5 -> 12 stars since March 8"
- - New repos since last run
- - Repos that went stale since last run
-
- If no previous data exists, establish the baseline and note: "First Empire run.
- Growth tracking begins now."
+ Only include fields intentionally changing. Topic PUT replaces the full set;
+ re-read live state and retain accurate existing topics. Use boolean JSON values
+ for feature flags, not guessed string-valued API fields.
- ### Write to Shared Data Cache
+ Work on local README files or an isolated checkout. Inspect diffs and preserve
+ unrelated changes. Do not automatically commit or push cross-links/profile files
+ because their local draft was approved. If repository creation, publication,
+ archiving, or visibility changes are requested, execute only the named targets
+ and verify each mutation. Report partial completion and avoid blind batch retries.
- After execution completes, write `.github-audit/empire-data.json`:
- ```bash
- mkdir -p .github-audit
- grep -qxF '.github-audit/' .gitignore 2>/dev/null || echo '.github-audit/' >> .gitignore
- ```
+ ## Optional visuals and manual steps
- Include: timestamp, portfolio_health_score, portfolio_size, per_repo_metrics
- (object mapping repo name to {stars, views, topics_count, topics, license, language,
- description}), topic_authority (clusters with strength rating),
- pinned_repos_recommended (array of up to 6), cross_linking (array of {from, to, text}),
- branding_assessment (object with consistency ratings), profile_readme_status
- ("missing" | "exists" | "created"), profile_fields_set (object of field -> value),
- actions_executed (array of action descriptions), growth_snapshot (per-repo stars
- and views at time of run).
+ Reuse approved artwork. Generate an avatar or social card only on request using
+ the host's configured image tool; no specific provider/key is required. Review
+ legibility at small display size, contrast, cropping, and actual upload constraints.
+ Keep source artwork; do not delete originals or strip provenance merely to hide
+ its origin. A configured tool's absence does not block portfolio copy or analysis.
- Reference: `github/references/shared-data-cache.md` for patterns.
+ The compatibility `empire --generate-avatar` flag prepares/reuses a supplied
+ local asset. It does not invoke an image provider. Inspect its output and keep
+ generation through a requested host image tool distinct from local conversion.
- ## Output Flow
+ For requested actions unavailable through the supported automation interface,
+ provide an actual file link, exact profile/repository settings URL, and concise
+ current steps. Pin recommendations need not fill every slot. Do not claim a
+ photo, social preview, or pin order is live until checked. Do not promise a
+ universal UI path or completion time without verifying it.
- Every run produces this exact sequence:
+ ## Verify and measure
- 1. **The Blueprint** -- TL;DR + Build Plan + Profile README draft + recommendations
- 2. **Confirmation gate** -- "Approve all, or tell me which ones to execute."
- 3. **Execution** -- automated actions fire, manual steps are guided
- 4. **Verification** -- confirm all changes took effect, show before/after
- 5. **Growth baseline** -- snapshot saved for future delta reporting
+ Re-read each changed profile field and repository setting; verify every modified
+ repository, not just a sample of a batch. Validate local links and content, and
+ only label README changes published after confirming the remote revision.
- The Blueprint is the proposal. Execution is the delivery. The user finishes
- this session with a built empire, not a to-do list.
+ For requested growth tracking, record accessible metrics with collection time,
+ query scope, and reporting window. Compare compatible windows and repository
+ sets. Missing traffic access stays unavailable; a change in stars/views does not
+ establish that portfolio edits caused it. Do not compare legacy health scores
+ across changed methodology or call topic counts authority.
+ Deliver a concise receipt of local files, verified live changes, unavailable
+ checks, and pending manual work. Link concrete artifacts. Recommend deeper
+ repository work only where it advances the user's objective; a complete
+ portfolio transformation is not promised for a scoped review or profile edit.