Portfolio Forge

The problem: employers ask for a GitHub portfolio; the best work is private because it may become a product. Publishing it hands competitors the moat. Refusing to show anything loses the interview.

The answer is a three-layer public portfolio, none of which exposes product code:

1. Case studies — one page per project: architecture, engineering decisions, measured results. Describes the moat by shape, never contents.
2. Extracted libraries — genuinely generic modules pulled out, genericized, tested, CI-badged. Real code employers can read, none of it product-specific.
3. Visuals — screenshots/GIFs proven synthetic, wired into the case studies.

Run the phases in order. Every phase has a hard safety gate — the gates are the skill.

Phase 1 — Explore (parallel subagents)

One read-only exploration subagent per private project. Each must return:

1. What the product does; target user; honest status (shipped / MVP / personal)
2. Tech stack (from manifests, not guesses)
3. Architecture — structure and notable patterns
4. 3–5 standout engineering features worth bragging about
5. Scale — LOC, file counts, test counts (run the counts; never estimate)
6. Existing assets — screenshots, videos, design prototypes, logos, with paths
7. Open-source extraction candidates, ranked by how cleanly they detach
8. Sensitivity notes — secrets on disk, real user data, the business moat, stale docs that would cause false public claims

Insist on #8. The moat is usually NOT the crypto or the framework wiring — it is tuned prompts, scoring weights, rule tables, curated datasets, pricing, clinical/domain content. Explorers must name these precisely so later phases can avoid them.

Phase 2 — Case studies

One markdown page per project. Structure that works:

• Status banner: **Status:** Private MVP · **Code:** private, available on request · **Role:** solo design, development & ops — honest framing is non-negotiable (no "live SaaS" claims for an unshipped MVP, no clinical or efficacy claims for health apps; add disclaimers where the domain needs them)
• What it does — bullets, product language
• Tech stack table
• Engineering highlights — 3–5 subsections, each a real decision with its why. Measured numbers beat adjectives: "triage accuracy 55% → 77% on a frozen golden set" outperforms "high accuracy". War stories with fixes land well ("found the plugin silently dropped the auth requirement; replaced it with…")
• Scale & quality — LOC, test counts, notable ratios

Moat gate before writing: describe that a venue cost engine exists and what makes it hard; never publish its formula, thresholds, weights, rule contents, few-shot anchors, or unvalidated pricing. Numbers that are safe: outcome metrics, test counts, LOC.

Index README: hero visual strip, project table with one-liners, recurring themes across projects, open-source section, "read access can be arranged for interview processes", contact.

Phase 3 — Extract libraries (parallel subagents, worktree-free)

Pick candidates that detach cleanly (explorers ranked them). Per library, a subagent:

1. Copies source + tests into a fresh repo layout with package manifest, README, MIT LICENSE, .gitignore
2. Genericizes: product names out of identifiers, domain vocabulary out of comments and fixtures, hardcoded aliases/URLs → parameters. Keep behavior identical — when the API must change because domain names are baked into the signature, flag it explicitly.
3. Ports and RUNS the tests. A library extracted without a green test run does not ship.
4. Where feasible, proves equivalence: differential run of extracted vs. original across generated inputs (thousands of cases costs one loop).
5. Leak-greps the result: product names, domains, secrets, dataset rows, internal paths. Synthetic example data must be verified disjoint from any proprietary dataset.

README per library: what it does, the story of why it exists (production origin stories are the selling point), usage, honest caveats section. Add CI (the real test suite on push), a badge, and repo topics. Verify the badge goes green after the first push.

Phase 4 — Visuals (safety-gated)

Sources, in order of cheapness:

1. Committed visual-regression baselines — synthetic by construction and guaranteed current. Best source when they exist.
2. Tracked test screenshots — verify seed data visually before use.
3. Design prototypes / handoff HTML — serve locally, screenshot with a browser tool; synthetic by design.
4. Existing demo videos → GIF excerpts (640px, 10fps, two-pass palette) plus full-res stills.

The gate, absolute: never publish a frame nobody viewed. For videos: sample frames across the full clip, view every sampled frame, cut GIFs only from ranges whose samples were all viewed. Seeded personas (Jan Kowalski, demo@example.com) are fine; real emails, tokens in URLs, terminals, real uploads are not. Real-user data in a personal app (health data especially) disqualifies the screenshot — reseed synthetically or skip.

Caption every visual with its provenance: "synthetic seed data", "from the design prototype", "visual-regression baseline".

Phase 5 — Publish

• Portfolio repo + per-library repos, descriptions, topics
• Profile README (<user>/<user>) — the landing page: portfolio link, library table, "how I work" with the measured numbers, contact
• Point the user at the two settings only they can click: Include private contributions on my profile, and pinned repos
• Suggest per-repo read access (outside collaborator) as the answer for late-stage interviews

Failure modes this skill exists to prevent

• Publishing the moat because it was the most impressive code
• Screenshots with real user data (the owner's own data counts)
• Case studies sourced from stale READMEs — always source from code and domain docs, and say so when a README contradicts reality
• Claiming shipped/production status for MVPs — one caught lie voids the whole portfolio
• Extracted libraries with no tests, or tests that were never run
• GIFs cut from unviewed footage
• Secrets adjacent to the work: .env files, service-account keys, auth-session JSON in eval fixtures — grep before every publish, and never screenshot a terminal in a project directory