[ManningWorks]

Summary

Adds skills/projex/ — an end-user agent skill that teaches any coding
agent (Hermes, Claude Code, or anything that reads SKILL.md) to drive Projex
in its own site end-to-end, with zero prior Projex knowledge.

• skills/projex/SKILL.md (442 lines) — all six spec-locked sections:
  1. init — flag-based non-interactive paths, --github auto-discovery
     (including the git config user.name username source), --yes/-i
     semantics, auto-install side effect
  2. components/themes — all 8 copyable components + 3 themes, copy
     destinations, the verified Next.js page wiring pattern
     (defineProjects returns { projects, options }, normalise() pipeline),
     compound component API, data-projex-* styling hooks
  3. content ops via flags — add project (per-type flag table),
     add learning/challenge/timeline/post, edit (incl. --no-featured,
     --unset rules), remove (incl. --force, --index), list — with the
     exact flags that keep every operation non-interactive
  4. projex.config.ts field reference — all 9 kinds
     (github, npm, youtube, gumroad, lemonsqueezy, product-hunt, devto, manual, hybrid), lifecycle statuses, featured, links, linkOrder, stats,
     defineProjects options
  5. provider env vars — GITHUB_TOKEN, DEV_TO_API_KEY,
     PRODUCT_HUNT_TOKEN, YOUTUBE_TOKEN, GUMROAD_TOKEN, LS_TOKEN
     (incl. the LS_TOKEN naming trap), build-time semantics
  6. troubleshooting — rate limits, private repos, the init --github
     null-validation failure, cancelled-prompt exit-code trap, auto-install
     failures, the component-copy bug, ESM-only import semantics
• skills/projex/references/cli-help.md — drift baseline: full raw
  --help output for every command + 14 verified behavioral notes, captured
  2026-10-12 from @manningworks/projex v1.6.0, re-captured and diffed
  byte-identical against the current branch head.

Accuracy

Every flag, default, and example was verified this session against live
--help output and by executing the built CLI (pnpm build, then a
throwaway Next.js-style sandbox): init scaffold, init --github -y (real
octocat fetch), every add/edit/remove/list recipe, component/theme copy, and
the full defineProjects → normalise → rendered project pipeline with live
GitHub data. The skill is self-contained; nothing critical points at the docs
site.

No CLI code, AGENTS.md, README.md, or release-process files are touched.

Agent-usability gaps found (documented in the skill; NOT fixed here — CLI changes out of scope)

1. [High] init --github generates a config that fails validation.
   Generated entries contain background: null / why: null, but the
   defineProjects schema is z.string().optional() (non-nullable), so any
   import of the generated config throws Validation failed ... received null. Fix candidate: emit background/why as strings or omit them in
   generateGitHubConfig() (packages/core/src/commands/init.ts). Verified
   by reproduction; deleting the two lines makes the config validate and the
   normalise() pipeline works.
2. [High] projex add <component> copies no runtime code from the
   published package. getSourceFiles() filters .tsx/.ts, but the
   published dist ships compiled .js + .d.ts — the copied
   components/projex/<Name>/ directory contains .d.ts files only, so the
   import the CLI prints (import { ProjectCard } from './components/projex/ProjectCard')
   fails at build. Workaround documented: import { ... } from '@manningworks/projex' (verified, 53 exports).
3. [Medium] add project is not fully non-interactive without --stack
   and --featured. Omitting either triggers an interactive prompt that
   cancels in a non-TTY shell. There is no --no-featured on add
   (edit-only), so non-featured projects need add-with---featured +
   edit --no-featured. --stack "" works as the empty-stack workaround
   (verified).
4. [Medium] add post prompts for --url even though it is "optional" —
   omitting it cancels non-interactively and adds nothing.
5. [Medium] Cancelled prompts exit 0 with ✖ Cancelled. — exit codes are
   unreliable for agents; the skill instructs verifying ✓ lines / file state.
6. [Medium] init --github -y derives the GitHub username from
   git config user.name — a full name yields "GitHub user not found" or
   the wrong user's repos. The skill instructs setting git config user.name <handle> first.
7. [Low] Auto-install failures are misreported. init/add run a bare
   npm install/pnpm add/yarn add (no --legacy-peer-deps); peer-dep
   conflicts fail the command, and init prints ✖ Failed to create projex.config.ts even though the file was written.
8. [Low] The package is ESM-only — exports["."] has an import
   condition only (no require/default), and internals use directory
   imports; raw Node/CJS cannot import it (fine for Next.js).
9. [Low, doc drift] Root/core README quick-start shows
   projects.map(...) but defineProjects() returns { projects, options }
   — the docs-site pattern (destructure + normalise()) is the working one
   (verified). README is owned by another card; flagging only.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
projex-docs	Ready	Preview	Oct 12, 2026 4:13am UTC

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: e1bea7c0-de39-47a5-b446-31a7f82b1b38

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[ManningWorks]

Review: spec-conformance + accuracy pass (reviewer)

Verdict: NEEDS-EDITS — 2 MEDIUM (one-line doc omissions on the accuracy promise), 2 LOW (non-blocking). No HIGH drift found. Every documented flag, default, message, exit code, and example was checked against a fresh pnpm build of the CLI at branch head (65937fa) and against packages/core source; 16 non-interactive recipes were executed live in a sandbox, and every output/exit-code/message matched the skill text.

MEDIUM (required changes)

1. onError default not documented — skills/projex/SKILL.md:290-293
   The config-shape example shows onError: 'throw' with no default annotation, while the adjacent commits field carries an explicit (default 0) — a first-time reader infers 'throw' is the default. The actual default is 'warn' (packages/core/src/lib/normalise.ts:134: options?.onError ?? 'warn'). With the real default, a failed data fetch warns and the page renders with partial data; nothing in the skill explains that outcome. Fix: annotate the true default, e.g. onError: 'throw', // 'throw' | 'warn' | 'silent' (default: 'warn') — or show the default value 'warn' in the example.

2. init --github -y silent scaffold fallback not documented — skills/projex/SKILL.md:54-61
   If git config user.name is unset or empty, init --github -y does not fail: it prints ⚠ Could not detect GitHub username from git config / Falling back to basic template and writes the basic scaffold (exit 0) — packages/core/src/commands/init.ts:193-202. The skill only documents the "user not found / someone else's repos" outcome, so an agent with no git config would hold a placeholder scaffold believing GitHub discovery ran. Fix: add one sentence to the --github -y bullet: when user.name is unset/empty, a warning is printed and the basic scaffold is written instead (no error, exit 0).

LOW (non-blocking)

3. --date enforcement overstated — skills/projex/SKILL.md:231
   "--date must be YYYY-MM-DD" — the CLI only enforces this via interactive-prompt validation (add-timeline.ts:48, add-post.ts:56); a malformed --date flag value is accepted with exit 0 and written to the config (schema is z.string(), no format check). Suggested wording: "format YYYY-MM-DD (prompt-validated; flag values are not checked)".

4. Adjacent — pre-existing CLI fragility, out of scope for this PR — packages/core/src/commands/init.ts:53-68
   The overwrite confirm() is wrapped in an empty catch {} that swallows the non-TTY ExitPromptError. The skill's documented safe behavior (no-flag non-TTY init with an existing config leaves the file untouched, exit 0) is empirically true (reproduced 4× across stdin variants), but it holds incidentally because the process exits — not because the code path returns. A future inquirer EOF-behavior change would turn this into a silent config overwrite. Suggest a CLI-side follow-up issue (explicit ExitPromptError handling); no skill change needed — the documented behavior matches observed behavior today.

Verified accurate (spot-check evidence)

• Drift baseline references/cli-help.md: all 7 --help blocks diff byte-identical against a fresh build at branch head (re-capture procedure documented in-file).
• "53 exports" (SKILL.md:408): verified exactly — bundler-resolved runtime export count is 55 keys minus 2 CJS artifacts (default, module.exports); all 17 names the skill lists are present.
• init --github null trap (SKILL.md:60-61, 378-381): reproduced verbatim — a generated-shape entry throws Validation failed | [0].background: Expected string, received null; deleting background/why validates, options default to {commits: 0} (which also confirms the "commits (default 0)" annotation).
• Non-interactive recipes (16 live runs): init -y scaffold (my-project/username/repo), add project success message ✓ Project 'my-test-app' added to projex.config.ts, duplicate → ✖ Project ID '…' already exists. exit 1, missing --stack/--featured/--url → ✖ Cancelled. exit 0 with nothing written, list table ID|Type|Status|Featured(★)|Name, edit --no-featured, --unset standalone + protected-field exit 1, type-mismatch ✖ 'repo' is not a valid field for type 'manual'…, remove --force / no---force cancel-keeps, out-of-range ✖ Invalid post index 5. Must be 0-0., unknown component → exit 1 + exact 8-component/3-theme list, missing config → ✖ projex.config.ts not found. Run 'projex init' first. exit 1.
• Config reference: all 9 kinds' required fields, 6 lifecycle statuses, links/linkOrder/stats/override keys, background/why null-rejection, posts.url URL validation — all match config-schema.ts / types/index.ts.
• Env vars: all 6 names match source (GITHUB_TOKEN, DEV_TO_API_KEY, PRODUCT_HUNT_TOKEN, YOUTUBE_TOKEN, GUMROAD_TOKEN, LS_TOKEN); 60/hr vs 5000/hr figures, no-token build warning, Dev.to views-0-without-key, YouTube ≈2 units/fetch (channels.list + playlistItems.list) — all match.
• ESM-only claim (SKILL.md:412-415): live-verified — raw Node import of dist/index.js fails with ERR_UNSUPPORTED_DIR_IMPORT; exports["."] carries an import condition only.
• Component-copy bug (SKILL.md:91-97, 404-410): mechanism verified — dist/components/<Name>/ ships compiled .js + .d.ts; the copy filter (.tsx/.ts) matches .d.ts but not .js, so copied dirs contain type declarations only.
• Spec axes: agent-agnostic (zero agent-specific tooling references in the skill), self-contained (no dangling docs-site references; all critical facts in-skill), all six spec-locked sections present, and the first-time-reader flow (init → add → edit → list) executed from the skill alone in a clean sandbox.

Well done on the drift-baseline approach — it made this review a diff, not a re-derivation. The two MEDIUMs are the kind only a second reader catches; both are one-line fixes.

[ManningWorks]

Re-review: APPROVE ✅

Re-verified the fix commit a181262 against the six findings (2 MEDIUM, 2 LOW, + changelog and peer-dep addendum). All resolved:

• onError default — config shape now annotated 'throw' | 'warn' | 'silent' (default: 'warn'), matching normalise.ts:134 (?? 'warn') and defineProjects.ts:10.
• init --github -y fallback — bullet now documents unset/empty user.name → warning + basic scaffold written, exit 0, matching init.ts:193-202.
• --date reword — "expects format YYYY-MM-DD (prompt-validated; flag values are not checked)", accurate per add-post.ts:51-57.
• CHANGELOG — one ### Added entry under [Unreleased], Keep a Changelog format, house style matches the 1.6.0 entries.
• list table — leading (index) column added; confirmed against live projex list output.
• Peer-dep wall (issue [regression of #11] Published CLI cannot start: optional peerDependencies (commander, ts-morph, chalk, @inquirer/prompts) not installed by npm/npx #42) — §1 early warning + §6 Troubleshooting entry naming the four optional peerDependencies; verified against npm view @manningworks/projex (v1.6.0), no versions pinned.

Diff vs 65937fa touches only CHANGELOG.md and skills/projex/SKILL.md; references/cli-help.md and all CLI code untouched. Earlier full-review pass (16 live recipes, drift baseline) stands.

No blocking findings. Merge tail to fire.