feat: expose typescript-best-practices skill in marketplace#5
Open
roeex5 wants to merge 57 commits into
Open
Conversation
- git-worktree-tidy: routine hygiene for bare-repo + worktree layouts (fetch, prune stale branches/worktrees, ff-only update important branches) - test-ping: minimal skill stub for test CLI ping command - canton-nodes codex override: stripped-down version without broken symlink
- Add zmx skill with session management patterns using zmx run, zmx history, zmx wait, and zmx list - Update tilt and tiltup skills to use zmx instead of tmux - Update CLAUDE.md skill combo reference (tilt + zmx) - Remove tmux skill (zmx has no windows/panes concept; uses separate sessions with project prefix instead)
Read ZMX_SESSION env var and display as gray `zmx:<name>` segment between the git status and model gauge sections. Hidden when not inside a zmx session.
- Descriptions lead with "Use when..." for discovery - Remove MUST/NEVER over-prompting (Claude 4.6 overtriggers on aggressive language); use normal phrasing with context/motivation - Deduplicate PROJECT= boilerplate (define once, reference after) - Cut redundant "Common Patterns" section that restated earlier examples - tilt skill: inline zmx reference instead of restating rules
Add 💤HH:MM indicator to statusline showing when the agent last went idle. Uses Stop/UserPromptSubmit hooks to write and clear per-session marker files, with 7-day auto-cleanup of orphaned files.
Ralph and Codex reviewer plugins defaulted to too few cycles, causing loops to hit caps before completing complex tasks. - ralph command: 15→30 max-iterations, 10→20 max-reviews - ralph-loop plugin: 50→30 max-iterations (aligned with ralph command) - codex-reviewer plugin: 10→20 max-cycles (command + hook fallback)
Bump the default --max-cycles value by 50% to allow more review iterations before auto-approve, matching real-world usage patterns.
Add check-plugin-versions.sh that validates plugin.json and marketplace.json versions match, and warns when plugin source files change without a version bump. Update CLAUDE.local.md with a clear version bump checklist for publishing plugin updates.
Prefer integration tests over mocked unit tests for data flow and permissions. Mocks only acceptable for external services, not your own data layer. "Would this survive a manual walkthrough?" check.
…letion Major rewrite of the ralph-reviewed plugin: State migration: - State moved from .claude/ralph-loop.local.md (YAML) to .rl/state.json (JSON) - Prompt stored separately in .rl/prompt.md - Structured event log at .rl/log.jsonl - .rl/ auto-added to .git/info/exclude on init rl CLI (new): - rl init: one-command setup (state, prompt, log, symlink) - rl done / rl done --blocked: state-flag completion (replaces <promise> tags) - rl log phase|commit|decision|summary: structured JSONL logging - rl prompt / rl status / rl clean: state inspection and cleanup - Creates .rl/rl symlink for short-path access after init - Git root walks superprojects (matches stop hook behavior) Stop hook: - Completion detection via state.json flags (not transcript regex) - Removed legacy <promise> tag parsing and transcript reading - Review prompt simplified: correctness-focused, tells Codex to use rl - Codex review outputs kept in .rl/ (not /tmp/) - Codex cwd uses gitRoot for reliable .rl/ access - Slimmed LoopState: removed completion_promise, original_prompt, pending_feedback, review_history (all derived from .rl/ files) - Review feedback is plain text (no structured issue IDs/severity) - Iteration headers hide denominators from agent Behavioral improvements: - Pacing, churn breaker, depth-before-breadth, skill loading, live verification sections in skill prompt - Ralphoff "Done when" guidance: verify behavior not file existence BREAKING CHANGE: State format changed from YAML frontmatter to JSON. Completion mechanism changed from <promise> tags to rl done command.
Update statusline to read ralph loop state from the new .rl/state.json path using std.json instead of YAML frontmatter parsing. Tests updated to use JSON fixtures. Statusline still shows N/M denominators for human visibility (only hidden from the agent in the loop).
QA.md covers full e2e verification: rl init, agent work, rl done, Codex review gate, feedback cycle, edge cases. qa.sh resets the test repo and launches claude interactively with the QA prompt.
Sources direnv environment in non-interactive bash commands so tools spawned by Claude Code inherit the correct PATH and env vars. Referenced by settings.json BASH_ENV config.
Replace embedded scripts/rl with the standalone @0xbigboss/rl package. Stop hook now delegates state, prompt, and log operations to the rl CLI via spawnSync instead of reimplementing them. - Delete scripts/rl (323 lines) - Refactor stop hook: remove parseStateFile, serializeState, readPrompt, appendLog, LogEntry, LoopState (872 → 654 lines) - Update ralph-loop.md: discover rl on PATH or via bunx - Update cancel-ralph.md: use rl status --json - Update QA.md: reference installed rl, add hook integration checks - Bump to v3.0.0
- Stop hook: find rl via PATH, then .rl/rl wrapper fallback - Stop hook: reject prompt says ".rl/rl done" not "<promise>" - ralph-loop.md: add bunx/npx/command to allowed-tools - Bump plugin.json to v3.0.0
ralph-loop.md now builds rl from github.com/0xbigboss/rl via bun build --compile if not already on PATH. Zero manual setup needed — just run /ralph-reviewed:ralph-loop.
Override default "comment only when non-obvious" behavior with an explicit preference for more comments that explain why, not what.
Claude Code has internal protection on ~/.claude that blocks writes even with explicit permissions and additionalDirectories configured. Moving handoffs outside the protected zone eliminates approval prompts.
Commit 00f93cf introduced a claude-code submodule pointer inside the claude-code repo itself. Remove the bogus gitlink and .gitmodules entry.
Skill wrappers for rl-clean, rl-done, rl-init, rl-log, rl-prompt, rl-state, and rl-status commands.
Standalone skill that replaces the manual "knowing what you know now, what are some improvements?" prompt with structured, grounded output. Analyzes across six dimensions (correctness, simplicity, security, tests, performance, DX) and produces [IMP-N] format suggestions that integrate with ralph loops and handoffs.
Replaced by /rl:ralph plugin command.
Simplify ADF flow to reflect actual agent ownership: agent owns SPEC → PLAN → TDD → DEV → E2E; review, CI, and merge are human decisions. Remove CI/REVIEW/MERGE gates, multi-skill combinations matrix, and verbose explanations while preserving all behavioral rules. Restore file-pattern triggers in skills table for Codex compatibility.
Delete 4 skills no longer needed: - data-driven-testing: deprecated, replaced by testing-best-practices - extract-transcripts: replaced by /recall - codex: no longer used - specalign: Opus handles spec alignment naturally via ADF
…best practices Apply skill authoring guidelines across all 36 remaining skills: - Fix all descriptions to "Use when..." format (triggering conditions only, no workflow summaries that Claude shortcuts past) - Remove CLAUDE.md overlap from language skills (type-first workflow, functional patterns, error handling, config sections) - Split heavy skills into short SKILL.md + reference files: react-best-practices (1737→404 words), playwright (1655→386), git (1293→938 with git-examples.md) - Condense zig (1811→436), tamagui (1324→529), orbstack (1114→566), canton-network-repos (1281→503), spec (921→508), testing (1023→721), e2e (687→562) - Add CLAUDE.md cross-references in language skills Total context savings: ~8,500 words eliminated from skill loading.
Add Shell environment section clarifying that direnv hooks in ~/.zshenv auto-export .envrc on every cd/pushd/popd, so agents should not manually run `direnv allow`, `source .envrc`, or `eval "$(direnv export ...)"`. Saves tokens and prevents the agent from re-inventing workarounds when a var looks missing.
Design for a Claude Code skill that lets Opus delegate bounded implementation tasks to Codex via `codex exec` while keeping the existing `rl review` gate as the audit. Approach 1 (skill-first proving ground), forward-compatible with promotion to a first-class `implement` worker role in rl-broker.
The rl 1.0 rewrite moved verdict state into .rl/state.json (v3 schema) with
strategy-typed loops, async review workers, and verdict/in-flight fields.
The statusline's old segment still reads the pre-1.0 files and no longer
reflects what the loop is actually doing.
Changes:
- Strategy-aware leading glyph: ralph (🔁), review (🧪), research (🔬).
- Verdict/in-flight tail glyph: ⏳ > ✅ > ❌ > none, with in-flight-wins
precedence (running worker supersedes any prior verdict by construction).
- research strategy hides the review counter and renders ★{best_metric_value}
when present (3 decimal places).
- Drop dead CodexReviewState code + tests; rl 1.0 does not write
.claude/codex-review.local.md.
- Thread allocator through parseRalphStateFromContent (was using
std.heap.page_allocator directly).
- glyphs namespace alongside colors for grepability.
- --debug mode logs schema version drift (version != 3) to
/tmp/statusline-debug.log without affecting rendering.
Adds SPEC.md as a retroactive specification covering both preserved behavior
(path/git/model/gauge) and the rl 1.0 alignment requirements.
Tests: 50/50 passing (+11 new, -8 removed CodexReviewState tests).
Manual smoke-tested against 7 synthetic fixtures covering each
strategy/verdict/in-flight/metric/legacy permutation.
…dict gate
The first-cut rl 1.0 alignment (commit 3ecca04) projected state.json fields
directly onto the status line. Testing against live rl 1.1 loops exposed the
gaps: verdicts rendered even when stale against HEAD, in-flight markers rendered
even when the worker was orphaned, iteration counters rendered even for review
strategies (which never advance iteration), and terminal-state flags were
ignored entirely so blocked loops looked active.
This commit rewrites the rl segment to mirror the decision logic of rl's own
Stop hook (~/0xbigboss/rl/src/strategies/{ralph,review,research}.ts). Every
rendering rule is now traceable to a specific branch of rl's state machine,
locked in by per-strategy fixture tests.
REQ-SL-060..069 in SPEC.md are the durable record; the highlights:
- Strategy-dispatched layout (REQ-SL-061):
* ralph → 🔁 iter/max 🔍 rev/cap verdict? age? (iter is meaningful here)
* review → 🧪 🔍 rev/cap verdict? age? (iter is dead — hidden)
* research → 🔬 iter/max ★arrow value? age? (no reviews)
- Terminal-state prefix (REQ-SL-062): 🚧 blocked_claimed / 🏁 completion_claimed,
precedence blocked > completion. Surfaces the "active: true + blocked_claimed:
true" anomaly we hit in ~/0xbigboss/rl yesterday at a glance.
- Orphan-aware verdict resolution (REQ-SL-063): readJobStatus opens
.rl/jobs/{id}.json and checks the status field; only queued|running counts as
in-flight. Orphan markers (missing/terminal job file) fall through to the
staleness check, which itself suppresses the verdict glyph when
review_verdict_sha != git HEAD. Collapses "no verdict", "stale verdict", and
"orphaned in-flight" into the same "no signal you can trust" visual — which
is the semantically useful bucket.
- Research metric with direction arrow (REQ-SL-064): ★↑0.823 (maximize) /
★↓0.045 (minimize) / ★1.500 (direction unknown).
- Loop age from iteration_start_ms (REQ-SL-065): +Ns / +Nm / +NhMm / +Nd with
color grade (green <1h, yellow <4h, red ≥4h). Note: emitIterationEnd is dead
code in rl 1.1, so this reads "loop age since init" not "current iteration
age" — still useful as a "has this loop been open too long" signal.
Per-strategy fixture tests (REQ-SL-068) assert the exact render for each
stateUpdates branch in the rl strategy files. When rl adds a new branch or
changes a branch's field shape, the tests will fail against the old assertions
and force a statusline update — the coupling becomes an explicit contract
rather than a silent assumption.
Implementation notes:
- RalphState is now fully by-value. String fields (verdict_sha, in_flight_job_id)
live in fixed-size stack buffers on the struct, so the state is safe to use
after its parse-time allocator is torn down. copyIntoFixedBuf handles
overflow by treating the field as absent.
- New helpers: readJobStatus, parseJobStatusFromContent, getGitHead,
formatLoopAge, copyIntoFixedBuf.
- Removed: first-cut REQ-SL-037 (staleness-ignored), REQ-SL-033 unconditional
iteration counter, REQ-SL-035 parse-time verdict precedence.
- Verified: 78 tests green, release build clean, manual smoke against 21
synthetic fixtures covering every new code path.
Observed: `rl implement start` spawns a detached worker against a packet with no active rl loop — the famo-gas-floor-ratchet workspace on 2026-04-13 had a running `.rl/jobs/impl-famo-gas-phase-1-schema-repo-tzzyst.json` and no state.json. The prior statusline cut surfaced nothing: the rl segment is gated on state.json's `active` flag, so impl workers were invisible. REQ-SL-070 adds a standalone `hasRunningImplJob` check that scans `.rl/jobs/` directly. Runs independent of state.json; renders `🔨` at the tail of the rl segment area whenever at least one `impl-*.json` reports status `queued` or `running`. Sibling of RalphState.format — called from main() unconditionally after it, so the glyph appears with or without an active loop. Implementation notes: - `hasRunningImplJob`: opens `.rl/jobs/` as iterable dir, bounded to 100 entries, short-circuits on the first running impl job. Filters by filename (must start with `impl-`, end with `.json`) to avoid conflating with review-kind jobs — the rl segment already tracks those via review_in_flight_job_id. - `formatImplWorker`: thin writer wrapper returning bool for consistency with the other segment functions. Fail-closed on every filesystem or parse error — treats anything unexpected as "no worker running". - `parseJobStatusFromContent` reused unchanged (already used for orphan detection on review jobs). Test coverage (+9 new, 87/87 total): - missing .rl/jobs/ → no glyph - running impl job → glyph - queued impl job → glyph - completed/failed/cancelled → no glyph - review-kind running job → no glyph (filtered out) - mixed: one of many running → glyph (short-circuit) - wrong filename prefix / extension → no glyph - formatImplWorker: emits glyph when running, writes nothing otherwise Rendering examples: 🧪 🔍 2/30 ⏳ 🔨 +1h # loop + impl worker parallel ~/foo/bar [main] 🔨 # no loop, just impl 🔁 5/30 🔍 0/10 🔨 +30m # ralph + impl
The specalign skill no longer exists. Remove the row from the CLAUDE.md skills table and reword two spec-best-practices passages that pointed at it to describe the drift-detection behavior directly.
Replace the ~1300-line rl-state schema mirror in src/main.zig with a shell-out to `rl statusline --format text --cwd <git_root> [--git-head <sha>]`. rl 1.10 (0xsend/rl#6) now owns the renderer, strategy dispatch, verdict staleness, and impl-worker glyph — one source of truth instead of a drifting mirror. - src/main.zig: 2906 → 1584 lines. Delete RalphState, Strategy, MetricDirection, VerdictState, JobStatus, VerdictRaw and their parse/format/test helpers. Introduce renderRlStatusline with a PATH probe and graceful fail-open on missing/failing rl. - SPEC.md: mark REQ-SL-020..024 / 030..039 / 060..071 SUPERSEDED in place (retain for traceability) and add REQ-SL-080..083 for the delegated contract. - CLAUDE.md: update data-source note to point at `rl statusline`. All 24 remaining tests pass; `zig build` clean.
Recorded the dogfood lesson from the 2026-04-18 rl reject cycles: match absolutist SPEC language to what the check actually enforces, or the reviewer will build a sub-60s counterexample. Guidance lives alongside Evidence-based under Authoring rules.
…kipDangerousModePermissionPrompt Plugin set now mirrors what's actually installed (drops codex-reviewer and ralph-reviewed; adds the official-marketplace + workflow plugins added via UI, plus swift-lsp and gh-pulse promoted from settings.local.json). Without this, claude-settings-merge --fix silently overwrote UI-installed plugins on every sync. Also moves effortLevel=xhigh and skipDangerousModePermissionPrompt=true into the baseline since they're durable per-user prefs used everywhere.
…e of truth settings.json now declares both marketplaces (extraKnownMarketplaces) and which plugins are on (enabledPlugins). Claude Code auto-registers the marketplaces on startup; install.sh derives the install list from this file. bin/bin/claude-settings-merge --check is expected to report DRIFT on hosts until bin/bin/claude-settings-merge --fix propagates the new field.
Adds guidance to treat tree-switching boolean props as a composition smell, prefer compound components with provider-scoped state, and lift provider boundaries when external controls need shared access.
These symlinks pointed at ~/.agents/skills/ which is empty, so they resolved to nothing. The rl:* plugin skills (rl:delegate, rl:rl, etc.) have superseded the local rl-* helpers. Removes 25 dead entries from the skill listing to free description budget.
- delegate-implementer: dead spec; v1 was built on feat/delegate-implementer but only SPEC.md ever landed on master. Functionally superseded by the rl: plugin (rl:delegate, rl:implement, rl:rl). - ios-device-screenshot: 1 actual load across all sessions; obsolete. - openai-image-gen: 4 loads, ad-hoc gothic-cathedral image experiments; not part of any recurring workflow. Frees description budget in the skill listing.
Trim enabledPlugins to the active set (canton-skills, recall, send-infra, rl, canton-keycloak-skills, typescript-lsp), add the canton-keycloak-providers marketplace, and surface defaultMode=auto plus skipAutoPermissionPrompt that had drifted in ~/.claude.
.claude/skills/engagement-algos is a symlink to a working directory outside this repo; keep it loose on this host.
Upstream 0xbigboss/recall was transferred to alleneubank/recall and the marketplace renamed accordingly. The plugin name stays `recall`, but the @-suffix tracking the marketplace must update or `claude plugin install` fails with "Plugin recall not found in marketplace 0xbigboss-recall".
Pin Claude Code's TUI to fullscreen (alternate-screen) so the preference survives across machines instead of living only in the live ~/.claude/settings.json.
…story reason Errors were getting buried in 20+ pending lines; separate the queries so failures surface first and include buildHistory[0].error for the why. Adds a re-poll note since in_progress can flip to error.
Rewrite README.md to make this repo presentable for open-source consumers who don't have the surrounding private dotfiles tree. Inventory every directory (commands, agents, all 25 skills, plugins, statusline, scripts, settings, hooks, analytics) with accurate descriptions, document the plugin marketplace install path, and add an explicit footnote about the optional dotfiles-tree relationship. install.sh now also symlinks commands/, agents/, and .claude/skills/ into ~/.claude/, and prefers the parent dotfiles' codex/codex.json when present but falls back to a new in-repo codex.json sample so standalone clones no longer fail under set -e. Remove the stale TODO.md (DuckDB indexing work, all items completed) and untrack CLAUDE.local.md / AGENTS.local.md so personal notes stay private on disk via .gitignore. Drop a personal ~/dotfiles path from scripts/README.md.
When the codex-reviewer and ralph-reviewed Stop hooks invoke `codex exec`, they pass `-o <outputFile>` so the verdict can be parsed back from a known path, then append the user's `extra_args`. Two latent bugs surfaced after the docs commit started promoting the shared ~/.claude/codex.json knobs to standalone users: 1. The previous filter dropped `-o` / `--output*` tokens individually but not the value that followed a bare flag. With extra_args: ["-o", "/tmp/other"], the filter left "/tmp/other" as a stray positional that Codex treated as an extra prompt argument. The new index-walk filter consumes both halves of paired flags (-o, --output, --output-last-message) and drops the inline --flag=value variants. Applied to both hooks. 2. ralph-reviewed honored `timeout_seconds` raw. A configured value at or above the 1800s Stop hook timeout let Claude kill the hook before it could parse Codex's output and surface a verdict. Now clamped to [60, 1680] (matching the existing codex-reviewer clamp), leaving a 120s buffer below the hook ceiling. Bumps ralph-reviewed to 3.0.2 and codex-reviewer to 1.6.10 in lockstep across each plugin.json and the root marketplace.json. The ralph-reviewed troubleshooting README is updated to describe the new clamp range rather than telling users to "increase to 1800".
Reintroduces and broadens the dropped ios-device-screenshot skill (413d349) into a full pymobiledevice3 toolkit. Covers capture (screenshot, syslog, crash, pcap), apps + sandbox file I/O, diagnostics + sysmon, port forwarding, WebInspector/CDP, and device info. Grounded against pymobiledevice3 7.0.7 CLI surface. SKILL.md + 3 reference docs (capture, apps-files, diagnostics-perf).
…henv) The hardcoded /Users/allen/... path only worked on Mac. shell/.zshenv already exports BASH_ENV via $HOME on every zsh process and Claude Code inherits it through its bash subprocesses, so the settings.json field was Mac-only redundancy.
Adds a slash command that signals the user is stepping away. Tells Claude to keep working but proactively skip any command that needs 1Password/SSH/Touch ID/sudo/browser-dialog approval, then invoke /handoff at the natural stopping point so the user can resume on return. Marked disable-model-invocation so only the user can trigger it.
Captures the auto-update flag the Claude Code upgrade wrote into the runtime marketplace entry so it survives reinstalls instead of reading as drift.
…ches A deleted upstream does not prove the work shipped: squash- and rebase-merges land changes under a new SHA, so git rev-list/ancestry report a fully-merged branch as having unmerged commits. Relying on that risks force-deleting branches that actually shipped (false positive) or, worse, trusting it the other way. - Add step 3a: verify each gone-upstream branch against the forge's PR merge state (gh pr list --head; confirm tip == merged PR head), and classify Merged (verified) vs At risk. - Add a hard rule against inferring merged status from rev-list/ancestry. - Surface ship status in the confirmation table so deletions are confirmed with the evidence visible.
Plain `git rebase origin/{base}` rewrites the range and orphans any local
branch pointing into it, silently breaking stacked feature branches (and
their open PRs). Make `--update-refs` the documented default so stacked
branches follow the rewrite.
- git-rebase-sync: add stacked-branch detection step (5), default the
rebase command to --update-refs and note rebase.updateRefs config,
verify moved refs post-rebase, and force-push each moved stack member
individually (--update-refs moves local refs only; worktree-checked-out
refs are skipped).
- git-best-practices: add a "Rebasing a Stack" note near Force Push.
Closes alleneubank#4
Adds the existing .claude/skills/typescript-best-practices skill to .claude-plugin/marketplace.json so it can be installed from any Claude Code marketplace as an external reference: /plugin install typescript-best-practices
Author
|
@alleneubank this is an embarrassingly minor edit — would love a quick review 🙏 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.claude/skills/typescript-best-practicesskill to.claude-plugin/marketplace.jsonWhat this enables
Once merged, the skill can be installed from any Claude Code marketplace as an external reference:
{ "name": "typescript-best-practices", "source": { "source": "url", "url": "https://github.com/alleneubank/claude-code.git" } }Users can then install it directly:
Test plan
marketplace.jsonparses as valid JSON🤖 Generated with Claude Code