jeds-curated-skills

A collection of Claude Code and Codex skills for agent-driven software development workflows.

Installation

Forgejo is the canonical repository and supported Git remote. GitHub is a read-only mirror maintained by Forgejo. Clone from Forgejo, and push changes to its origin; the server-side push mirror publishes those commits to GitHub. Do not configure a second client-side push remote.

Use the included installer to select which skills to install:

# Clone the repository
git clone https://git.ardenone.com/jedarden/jeds-curated-skills.git ~/jeds-curated-skills

# List available skills
cd ~/jeds-curated-skills
./install.sh --list

# Install specific skills (doesn't touch other skills already in ~/.claude/skills/)
./install.sh plan-review repo-hygiene

# Install everything
./install.sh --all

# Remove one or more installed skills
./install.sh --remove usage-statusline

--remove deletes only the named skill. For usage-statusline, it also deletes ~/.claude/usage-statusline.sh and removes the installer-owned statusLine entry from ~/.claude/settings.json while preserving unrelated settings and any different statusline command. Re-running removal is safe. The same command works from the direct-clone layout and removes the named skill directory from that clone.

Or clone directly to your Claude Code skills directory (overwrites existing skills):

git clone https://git.ardenone.com/jedarden/jeds-curated-skills.git ~/.claude/skills

This direct-clone shortcut installs the skill files, but it does not by itself deploy ~/.claude/usage-statusline.sh or update ~/.claude/settings.json. If you use usage-statusline, finish its setup from the clone:

~/.claude/skills/install.sh usage-statusline

The installer recognizes this in-place layout and only performs the out-of-tree setup; it does not remove the cloned skill. It merges the statusLine setting alongside other keys and leaves an existing statusLine that runs another command untouched.

Codex plan skills

The six plan skills (plan-author, plan-review, plan-gap-review, plan-idea-gen, plan-to-bead, and plan-vs-built) also work in Codex. Install them from this checkout into ${CODEX_HOME:-$HOME/.codex}/skills:

./install-codex.sh --list
./install-codex.sh                  # all six
./install-codex.sh plan-review     # one skill

The Codex installer copies the skill resources and inlines the shared Bash helpers into scripts that need them. It does not touch Claude's installation. When an installed Codex copy differs, inspect it before running ./install-codex.sh --replace <skill>; replacement backs up the previous installer-owned copy under ${CODEX_HOME:-$HOME/.codex}/skill-backups/. Codex detects new skills automatically; restart Codex if a newly installed skill does not appear.

Checking for drift

Skills are installed by copying into ~/.claude/skills/ (normally via ./install.sh) with no automatic update or drift-detection mechanism. If you edit skills locally or update the repo, installed copies can silently diverge from the canonical source.

To check for drift between installed skills and the repo:

cd ~/jeds-curated-skills
./scripts/check-installed.sh

This checks all skills present in both the repo and ~/.claude/skills/, reporting any files that differ or are missing on either side.

To check specific skills only:

./scripts/check-installed.sh plan-review repo-hygiene usage-statusline

Exit codes:

• 0 — No drift found
• 1 — Drift detected
• 2 — Usage error or ~/.claude/skills/ directory not found

To fix drift, re-install the affected skill with the installer:

./install.sh plan-review

Do not fix drift with a bare cp -r <skill>/ ~/.claude/skills/. In this repo, five scripts across four skills source the shared ../../lib/common.sh — a path that resolves to a lib/ directory beside the skill's parent, present only in a full clone of the repo and never in a per-skill install. A plain copy byte-identical to the repo therefore installs scripts that fail at source time. ./install.sh inlines lib/common.sh into those scripts at install time so each installed skill is self-contained, and for usage-statusline it also redeploys the out-of-tree ~/.claude/usage-statusline.sh and re-wires settings.json. check-installed.sh flags the broken-lib state too, since the diff alone sees a byte-identical copy as clean.

Stale inlines are drift. An installed script differing from its repo source is expected only while it is byte-identical to what ./install.sh would inline today: the checker re-derives the expected inline from the current repo copy of the script plus the current lib/common.sh (the same derivation the installer writes, shared via lib/inline.sh) and compares. The inlining marker alone proves nothing. So when lib/common.sh changes in the repo, every already-installed copy of the four skills the installer inlines for — plan-author, plan-review, readme-review, and spec-review — still runs the helpers it was installed with, and the next check reports them as Stale inline drift — the fix is the usual re-install, which re-inlines from the current lib:

./install.sh plan-author plan-review readme-review spec-review

usage-statusline's deployed copy is checked directly: check-installed.sh diffs ~/.claude/usage-statusline.sh against the repo whenever the skill is named, and on any sweep where a deployed copy exists — including a machine with no ~/.claude/skills/usage-statusline/ for the sweep to intersect. A drift there is fixed the same way: ./install.sh usage-statusline redeploys the script and re-wires settings.json (without displacing an existing statusLine).

The drift checker detects the same issue that motivated this repo's own ADR-1: the installed ~/.claude/usage-statusline.sh once hardcoded /home/coding while the repo's version generalized to $HOME — silent drift that went unnoticed until manual inspection.

Testing

When installed with scripts/install-hooks.sh, the local pre-commit hook runs three suites:

Suite	Covers
scripts/validate-skills.sh	Skill structure: frontmatter, references, shell syntax, executable bits, and inventory/fixture coverage. ShellCheck is optional and is skipped when unavailable.
scripts/test-root-scripts.sh	Root-script contracts, including installer preservation and idempotence, shared-helper execution, settings preservation, and timer lifecycle fixtures.
scripts/test-script-fixtures.sh	Deterministic replays of the script fixtures documented in SELF-TEST.md, checked against their pinned outputs.

Push CI

For non-CI-authored pushes to main, the Forgejo webhook sensor submits the skills-validate Argo WorkflowTemplate. It runs scripts/validate-skills.sh and scripts/test-script-fixtures.sh. The validate-skills workflow image does not include ShellCheck, so that optional lint check reports a skip there. The local hook adds scripts/test-root-scripts.sh.

Scheduled delivery check

The push-ci-heartbeat Argo CronWorkflow runs scripts/check-push-ci.sh in iad-ci on schedule 11,41 * * * * (every 30 minutes). It checks whether the newest eligible origin/main commit has the iad-ci/skills-validate Forgejo commit status, with a sensor-submitted skills-validate workflow as a fallback. This heartbeat checks push-to-workflow delivery. The path was verified by successful sensor workflow skills-validate-qk79k on commit 1956088 and scheduled heartbeat push-ci-heartbeat-1791652260 (2026-10-10).

Functional SELF-TEST sections

The LLM-in-the-loop functional sections of each skill's SELF-TEST.md remain manual runbooks by design. The automated fixture step replays deterministic script cases; functional runs requiring an LLM stay manual.

Run locally

Run the suites by hand with:

./scripts/validate-skills.sh
./scripts/test-root-scripts.sh
./scripts/test-script-fixtures.sh
./scripts/test-review-timers.sh     # focused installer/lifecycle fixtures

The fixture suite is the regression net for the shared lib/common.sh extraction: each fixture pins behavior so changes in the shared helpers or a scorer surface as a named failure instead of a silent count drift.

Skills

Each skill is a self-contained, checklist-driven artifact derived from the structural patterns of high-quality work. They cover the agent-driven development lifecycle from spec through release.

The canonical inventory is docs/skill-inventory.md: this repository currently contains 19 skills, comprising 18 lifecycle skills and the auxiliary usage-statusline observer. Every skill has a SELF-TEST.md; the fixture suite replays 12 script fixtures across 11 skills. The inventory and lifecycle-coverage check runs as part of scripts/validate-skills.sh—the same suite invoked by push CI—so these counts, the lifecycle map, and the headings below cannot drift.

Plan & design

plan-author

The inverse of plan-review: turns a short brief or idea into a complete plan.md.

Generates the same eleven structural categories plan-review checks for — scope lock, acceptance scenarios, architecture, pre-flight safety, phasing, testing, security, performance, operations, API design, and risk — so the draft is built to pass review on the first pass. Makes concrete decisions and parks genuine unknowns as numbered Open Questions rather than vague TBDs.

Usage: /plan-author [brief text | path/to/brief.md] [--out path/to/plan.md]

Supports greenfield, port, improvement, and integration plan types. For port and improvement plans it first scans the existing codebase so the plan is grounded in reality. Self-scores the draft against a completeness bar and backfills any thin sections before writing the file.

plan-review

Pre-flight review of a software plan that hunts for the decisions an implementer will be forced to make that the plan has not made — and proposes each one — so the plan itself is the decision record and no ADRs are needed mid-build.

Five lenses, run inline in one context: a decision ledger (every fork classified LOCKED / ASSERTED / RECOMMENDED / SPIKED / DEFERRED / UNNOTICED / SHADOW, each open one resolved with Decision / Because / Rejected / Enforced by / Revisit if), an implementer dry run that narrates the first files a worker would create and the first question they cannot answer, a reality check of the plan's claims against the actual repo and cluster, seven safety caps (any one ⇒ NOT READY — there are no percentages), and a compact, applicability-aware structural sweep as the safety net. The output is a memo written next to the plan: verdict first, then "Decide these now".

Usage: /plan-review [path/to/plan.md] · --fast for a five-minute caps-and-forks check · --lock DN-1,DN-3 (or --lock all) to write accepted decisions into the plan where an implementer will read them.

Handles greenfield, port, improvement, integration, migration/cutover, and spike plans. scripts/find-forks.sh is a line-anchored locator for deferred, hedged, shadowed, amended, and unquantified decisions.

plan-to-bead

Decomposes an approved plan.md into a dependency-wired bead graph, one owner per independently deliverable outcome.

Detects the repo's bead backend before writing anything, drafts single-task beads — never a bundle, never an unresolved decision masquerading as work — then runs a bounded independent review child that checks coverage, scoping, and real dependency edges before anything is reported done. Also runs standalone against a repo that already has a full bead graph, auditing it for the same three properties without creating duplicates.

Usage: /plan-to-bead [path/to/plan.md]

plan-idea-gen

Wide-then-narrow ideation anchored to a specific plan.md.

Generates a large pool of ideas (default 100) across eight forced-diversity lenses, then filters to the top K (default 10) through clustering, harsh triage, crossover hybrids, pairwise ranking, and an adversarial kill pass — comparisons, never 1–10 scores. Finalists arrive as decision-ready dossiers: pitch, complexity grade, concrete first step, and the strongest objection that survived. Every idea — winners and losers alike — lands in a per-repo ledger that future runs dedupe against, so the skill compounds per project.

Usage: /plan-idea-gen [plan.md path or repo] [--pool N] [--keep K] [--constraint "..."] [--lens "..."]

If the target plan is ambiguous it stops and asks rather than guessing. Adopted ideas can flow into bead tracking and back into the plan's roadmap.

plan-gap-review

Reviews a document for consequential gaps, contradictions, and missing pieces.

Delegates a bounded analysis to a fresh subagent for substantial documents, then applies authorized corrections directly — ordinary wording and implementation details without re-asking, while a finding that expands scope or needs a new product decision is batched for one explicit admit/reject/defer review rather than applied unilaterally. Repeats analysis only for changed inputs or a specific unresolved concern, not merely to accumulate consecutive clean rounds.

Usage: /plan-gap-review [path/to/document.md]

spec-review

A pre-plan gate: reviews a PRD or requirements doc for ambiguity, untestable requirements, and missing non-functional considerations before a plan is written.

Quotes each ambiguous phrase verbatim and proposes a precise rewrite, then checks clarity, testability, completeness (NFRs, error/edge states), and constraints. Feeds clean requirements into plan-author.

Usage: /spec-review [path/to/spec.md]

adr

Author or review Architecture Decision Records.

In author mode it computes the next sequence number and drafts a complete ADR with steel-manned alternatives and honest negative consequences. In review mode it rates an existing ADR and hunts "the two lies" — strawman alternatives and all-positive consequences.

Usage: /adr [author <decision brief> | review <path>]

threat-model

Produce or review a STRIDE-based threat model.

Author mode enumerates assets, trust boundaries, data flows, and entry points, then walks STRIDE per element and emits a threat table with mitigations. Review mode rates an existing model's coverage and flags gaps.

Usage: /threat-model [author | review] [path/to/architecture-or-model]

Implement & verify

diff-review

A generic, language-agnostic structural review of a code diff for correctness bugs and design/cleanup issues.

Collects the diff itself, produces candidate findings tagged with file:line, then runs an adversarial verification pass that tries to refute each finding and drops the ones it cannot substantiate — biasing hard against false positives. Has a large-diff runbook for chunked, parallel review.

Usage: /diff-review [base-ref]

test-plan-review

Suite-level review of a test directory or test plan for coverage gaps and tests that will lie to you.

Names specific untested behaviors and the bug each missing test would catch, across coverage, failure injection, non-functional concerns (concurrency, idempotency, cleanup), and test quality (determinism, isolation, meaningful assertions).

Usage: /test-plan-review [path/to/tests | path/to/test-plan.md]

api-design-review

Review a REST, gRPC, GraphQL, or CLI API surface for design quality and evolvability before it's locked.

Locates the API definition (OpenAPI, .proto, GraphQL schema, or routes), detects the style, and reviews resource modeling, semantics, evolution/versioning, payloads, and security — naming the specific anti-pattern behind each finding.

Usage: /api-design-review [path/to/api-definition]

plan-vs-built

Checks whether a repo's plan.md deliverables actually exist as working artifacts, not just as closed beads.

Sweeps every repo with a plan by default. Classifies each deliverable BUILT / UNPROVEN / PARTIAL / STUB / ABSENT / DIVERGENT / PLAN-STALE from observed evidence — a binary that runs, a test that fails when broken, a pod that answers — never from prose, commit messages, or bead status. Separately audits closed beads against those verdicts and flags false closures: work marked done that produced no artifact.

Usage: /plan-vs-built [repo-path-or-plan.md] [--create-beads] [--filter <regex>]

find-stubs

Sweeps a repo for leftover stub, mock, and placeholder code — the class of AI-generated incompleteness that passes lint and type-check but does nothing real.

Text-pattern detection (TODO/FIXME markers, unimplemented!()/todo!(), placeholder/fake-data comments, silently swallowed errors) across the tree. Report-only by default; converts surviving findings into tracked beads on request, deduped against open work.

Usage: /find-stubs [repo-path] [--create-beads]

readme-review

Review a project's README against a quality rubric tuned to its project type.

Infers whether the project is a library, CLI, service, or app, then runs an explicit "zero-to-running" walkthrough and flags any install or usage step it cannot verify is complete.

Usage: /readme-review [path/to/README.md]

Ship & operate

release-readiness

A go/no-go gate run before cutting a release, tag, or deploy.

Inspects the repo and changes since the last release, gathers evidence for each gate (quality, versioning, operations, comms/docs), and emits a GO / CONDITIONAL / NO-GO verdict. A gate with no evidence is marked MISSING, not passed. Includes a reduced-gate hotfix runbook.

Usage: /release-readiness

migration-runbook

Author a reversible cutover or migration runbook a human or agent can execute step by step.

Selects a migration pattern (expand-contract, dual-write + backfill, blue-green, canary, strangler-fig), then writes a runbook where every step has an action, a verification gate, and a rollback — with points-of-no-return flagged loudly.

Usage: /migration-runbook [brief | --out path/to/runbook.md]

postmortem

Author a blameless incident postmortem from an incident description and available artifacts.

Builds a timestamped timeline, drives root-cause analysis past a single cause into contributing factors, and produces an action-items table where every item has an owner, a due date, and a prevent/detect/mitigate classification — no "be more careful" items allowed.

Usage: /postmortem [incident summary | path/to/notes]

repo-hygiene

Audit a repository for hygiene debt, with an optional guarded fix mode.

Detects committed build artifacts (target/, node_modules/, __pycache__/, ...), tracked files over 5 MB, dead GitHub Actions workflows, README version-badge drift, dirty trees and stash pileups, missing .gitignore coverage, and suspicious tracked files (.env, keys — flagged for review, never read). The detection core is a plain report-only bash script (scripts/repo_hygiene.sh --json) that any agent harness can invoke directly — the skill is a thin wrapper that adds a fix mode applying one commit per category, strictly limited to .gitignore entries, git rm --cached, dead workflow removal, and badge fixes.

Usage: /repo-hygiene [repo-path] [--fix]

Observe

usage-statusline

A live Claude Code statusline showing session and weekly usage against elapsed-time pace, plus a rolling Claude-co-authored commit counter.

Renders each quota window as a percent, a ten-cell bar comparing usage-consumed against time-elapsed, and an extrapolated time-to-exhaustion — so you see you're overspending before you hit the wall instead of after. Unlike the other skills here, it isn't invoked on demand; it installs a statusLine command that runs on every prompt. See usage-statusline/README.md for the full legend.

Usage: ask Claude Code to "set up the usage statusline" (see usage-statusline/SKILL.md). ./install.sh usage-statusline performs the whole install — the skill directory, the ~/.claude/usage-statusline.sh deploy, and the statusLine wiring in ~/.claude/settings.json — idempotently, merging alongside existing keys and never displacing a statusLine that runs something else.

Factory Review Timers

For automated, scheduled review of multiple workspaces, install the systemd --user timers. The commands below assume a Bash-capable host with a systemd user manager. The install itself also works without an active user manager and leaves the generated units in place with an actionable warning; systemctl --user commands require a login session with a user bus:

cd ~/jeds-curated-skills
./scripts/install-review-timers.sh

The core contract is exactly four required timer/service pairs: three weekly workspace-review pairs and one weekly host memory-check pair, staggered across Monday through Thursday. The installer also creates one explicitly auxiliary, machine-local drift pair on Friday; it is documented separately so it is not mistaken for a fifth required workspace review:

• factory-review-plan-vs-built.timer / factory-review-plan-vs-built.service
• factory-review-find-stubs.timer / factory-review-find-stubs.service
• factory-review-repo-hygiene.timer / factory-review-repo-hygiene.service
• factory-review-memory-tool.timer / factory-review-memory-tool.service

The workspace timers are factory-review-plan-vs-built, factory-review-find-stubs, and factory-review-repo-hygiene; they read workspaces.txt as described below. factory-review-memory-tool runs independently of that list. The auxiliary factory-review-installed-drift checks this checkout's installed-skill drift. Each row installs the named .timer, its paired .service, and a runner script under ~/.config/factory-review/:

Role	Timer	Service	Schedule	Action
Required	factory-review-plan-vs-built.timer	factory-review-plan-vs-built.service	Mon 02:00	plan-vs-built
Required	factory-review-find-stubs.timer	factory-review-find-stubs.service	Tue 02:00	find-stubs
Required	factory-review-repo-hygiene.timer	factory-review-repo-hygiene.service	Wed 02:00	repo-hygiene
Required	factory-review-memory-tool.timer	factory-review-memory-tool.service	Thu 02:00	memory-tool check
Auxiliary	factory-review-installed-drift.timer	factory-review-installed-drift.service	Fri 02:00	installed-skill drift (scripts/check-installed.sh)

What gets installed

The command must be run from the checkout whose skills and drift state should be reviewed. The installer itself needs bash; activating and inspecting the schedule needs a systemd user manager with systemctl --user and journalctl --user. The generated runners additionally need claude for the three workspace reviews, memory-tool for its host check, and the bead CLI declared by each workspace (bead for bead-rs or bf for legacy bead-forge). The installed-drift runner also needs bead in this checkout's workspace. If no user manager is available, installation still writes the generated files and prints a warning; use the activation commands below later from a login session with a user bus. The installer resolves bash with command -v and embeds that path in the service units, which avoids assuming that /bin/bash exists. Each runner prepends $HOME/.local/bin:$HOME/.cargo/bin to PATH so user-installed commands are found under systemd.

For each unit name N, a real install generates these paths:

~/.config/factory-review/workspaces.txt
~/.config/factory-review/N.sh
~/.config/systemd/user/N.service
~/.config/systemd/user/N.timer

Here N is each of the four required unit names plus the auxiliary factory-review-installed-drift name. The workspace list is the only generated path that is not removed by --uninstall.

The generated service contract is the same for all five installer-owned units: Type=oneshot, TimeoutSec=30min, Nice=10, Environment=PATH=/run/current-system/sw/bin:/usr/local/bin:/usr/bin:/bin, and journal-bound standard output and error. Generated runners extend that base PATH with the user command directories needed by their child (/run/current-system/sw/bin:$HOME/.local/bin:$HOME/.cargo/bin:$PATH for workspace reviews; $HOME/.local/bin:$HOME/.cargo/bin:$PATH for the memory check). Timers use Persistent=true, so a missed scheduled run is considered when the user manager returns. Installation runs systemctl --user daemon-reload and systemctl --user enable --now for all five timers when the user manager is available. If it is not available, the generated files remain installed and the script prints the command to activate them later.

The three workspace-review service files are thin wrappers around the checked-in scripts/factory-review-workspace.sh child. That child owns workspace iteration, the claude --print invocation, clean/no-op reporting, and findings filing; the installer owns only systemd lifecycle generation and the separate host-check runners. The memory-check child owns its check and failure-bead behavior, while the installed-drift runner owns the machine-local drift check. This boundary keeps the installer contract independent of review report details.

The installer creates ~/.config/factory-review/workspaces.txt with comments if it does not exist. Before relying on the three workspace timers, edit that file and put one workspace path on each line; for example:

# Absolute paths are accepted.
/home/coding/project-a

# ~ and paths without a leading slash are relative to $HOME.
~/project-b
projects/project-c

Blank lines and lines whose first non-whitespace character is # are ignored. ~ expands to $HOME, and other relative paths are also resolved relative to $HOME. Missing directories are skipped. Each workspace timer invokes claude --print with its skill in report-only mode, captures the combined output, and prints it to the service journal. Claude is asked to finish with FACTORY_REVIEW_RESULT: clean or FACTORY_REVIEW_RESULT: findings; a clean result prints an explicit nothing to file outcome and creates no bead, while findings are filed as one report bead in the target workspace. Filing uses the workspace's declared backend (bead for bead-rs, bf for legacy bf/bead-forge), stable report hashing for bead-rs deduplication, and open-title lookup for legacy bf. The review runners never write .beads/ directly. A Claude or filing failure is reported and makes that service fail, but the remaining configured workspaces are still processed.

The memory-tool timer is different: it is a host check, runs exactly once, and ignores workspaces.txt. It chooses its filing workspace from FACTORY_REVIEW_HOME_WORKSPACE when set, otherwise $HOME/jeds-curated-skills; when that default is not a workspace checkout, it falls back to the checkout from which the installer was run if that checkout has .needle.yaml and .beads.

The memory check has two important outcomes. On success (exit 0), it prints memory-tool check passed; nothing to file. and No bead needed., exits successfully, and creates no bead. On failure (a nonzero exit), it prints only the status and, when the selected workspace has a supported backend and CLI, files or reuses exactly one safe failure bead for the check; the service still returns the original nonzero check status. It never forwards memory-tool diagnostics to the journal or bead description. It reads bead_cli.backend from the selected workspace's .needle.yaml:

• bead-rs (or bead) invokes bead create --issue-type task with the stable factory-review:memory-tool-check unique reference, so repeated failures are idempotent.
• bf (or bead-forge) invokes the legacy bf create --type task form and checks open items first to avoid filing a duplicate.

Both paths use the factory-review and memory-tool labels. On a successful filing the runner prints only the returned bead identifier; a bead-rs replay reports that the existing bead was reused, and a legacy bf replay reports that an open duplicate already exists. If the check fails but the selected workspace has no bead store/backend, has an unsupported backend, or lacks the selected CLI on PATH, it prints an explicit nothing to file or unable to file bead outcome and creates no bead. A filing failure also preserves the original check code; it never turns a failed check into a false success.

The installed-drift timer is machine-local rather than per-workspace: it runs scripts/check-installed.sh once a week from this checkout, including the full skill sweep and the usage-statusline deployed copy. It ignores workspaces.txt. Exit 1 means drift was found, so it files one deduplicated bead in this checkout and leaves the service failed for inspection. Exit 2 means a usage/environment problem such as a missing ~/.claude/skills/ directory; it files no bead because that is not drift.

An empty or missing workspace list has an intentional, explicit outcome: workspace runners print No configured workspaces; nothing to file. and do not invent a finding. This does not disable the independent memory-tool or installed-drift checks.

Operate and inspect

Re-running the installer from the same checkout is idempotent: it regenerates the same installer-owned service, timer, and runner files, reloads the user manager, and re-enables the timers without creating duplicate units. It also removes marker-owned artifacts from an older factory-review unit set, while refusing to overwrite or remove same-named files that do not carry the installer ownership marker.

# Re-install or repair the generated units
./scripts/install-review-timers.sh

# Reload systemd
systemctl --user daemon-reload

# Enable the timers managed by this installer (the first four are the required review timers)
systemctl --user enable --now \
  factory-review-plan-vs-built.timer \
  factory-review-find-stubs.timer \
  factory-review-repo-hygiene.timer \
  factory-review-memory-tool.timer \
  factory-review-installed-drift.timer

# List next/last runs for every factory-review timer
systemctl --user list-timers --all | grep factory-review

# Inspect a timer and its last service result
systemctl --user status factory-review-memory-tool.timer
systemctl --user status factory-review-memory-tool.service

# Run a service immediately, without waiting for its calendar time
systemctl --user start factory-review-memory-tool.service
journalctl --user -u factory-review-memory-tool.service --no-pager

# The same manual form works for a workspace review
systemctl --user start factory-review-plan-vs-built.service

systemctl --user list-timers --all shows the staggered next-run time and the last result; systemctl --user status and journalctl show the unit's detailed outcome. In particular, the drift timer intentionally remains failed after exit 1 so its finding is visible in those inspections.

./scripts/install-review-timers.sh is the real, idempotent installation. To preview the generated units and commands without creating the config directory, unit files, runner scripts, or changing systemd state, use --dry-run:

./scripts/install-review-timers.sh --dry-run

The installer accepts --dry-run to preview, --uninstall to remove its generated units, and --help (or -h) to print usage. An unknown option exits with an error and the usage text.

Remove only the timers, services, and runner scripts owned by this installer with:

./scripts/install-review-timers.sh --uninstall

The workspace list is not removed. Uninstall stops and disables active/enabled timers before removing their files, then reloads the user manager; unrelated user units and scripts are left byte-for-byte unchanged.

Fixture verification

Run the focused lifecycle checks directly after changing a runner or the installer:

bash scripts/test-review-runner.sh
bash scripts/test-review-timers.sh

Both commands must exit 0. The workspace-runner fixture prints factory-review-workspace fixture: PASS. The timer fixture prints a summary ending in Failed: 0; its manual-service cases also require the observable outcomes that matter in a real journal: clean reviews print an explicit nothing to file result and create no bead, finding reviews print Filed review finding ... and create one bead per finding, and the successful memory check prints memory-tool check passed; nothing to file. followed by No bead needed.. Its failing memory-check cases preserve the check's nonzero exit status and print the filed bead identifier without forwarding diagnostic output.

The focused installer fixture is scripts/test-review-timers.sh; it creates a temporary HOME, fake systemctl, fake claude, fake memory-tool, and fake bead/bf CLIs and runs the complete scripts/install-review-timers.sh lifecycle without touching the real user manager, workspace list, or bead store. It checks idempotent install and uninstall, dry-run side-effect safety, generated service/timer/runner validation, manual service execution, and memory-tool success/failure output including safe bead filing and deduplication. The broader scripts/test-root-scripts.sh suite runs the same fixture alongside the other root-script contracts.

The focused workspace child fixture is scripts/test-review-runner.sh; it creates two temporary fixture workspaces and uses fake claude/bead commands to prove workspace iteration, target-directory execution, selected-skill invocation, successful clean/no-file behavior, findings filing, and empty/missing-list no-op behavior. The complete timer lifecycle is covered by scripts/test-root-scripts.sh (run it with bash scripts/test-root-scripts.sh, expecting exit 0). It uses a temporary HOME, fake systemctl, fake claude, fake memory-tool, and fake bead/bf CLIs, so the fixture never touches the real user manager, workspace list, or bead store. It checks the three workspace timers and the independent memory timer through a fake systemctl --user list-timers response and also performs a read-only live probe when the host's user manager is available. A host without systemd or a user bus records SKIP and remains green. The fixture checks every generated service, timer, and runner (the four required review timers plus the auxiliary installed-drift timer), including oneshot/timeout/Nice/PATH/journal properties, staggered calendars, persistent activation, and manual service execution. When systemd-analyze is available, it also verifies every generated service and timer file with the equivalent of:

systemd-analyze verify \
  ~/.config/systemd/user/factory-review-*.service \
  ~/.config/systemd/user/factory-review-*.timer

When systemd-analyze is unavailable, it records an explicit SKIP. The isolated fake manager compares the four required timer names exactly and checks the auxiliary installed-drift timer separately, without depending on unrelated user units. It also checks that repeated install is byte-identical, --dry-run prints the generated commands without filesystem side effects, all three reviews visit two configured workspaces, clean reports produce no bead and an explicit nothing to file result, findings carry captured output into beads through both backends, failed Claude commands preserve their nonzero status, an empty workspace list reports No configured workspaces; nothing to file., a passing memory check files no bead, and failing bead-rs/legacy checks preserve their exit code while filing one deduplicated bead without exposing diagnostics. Finally, --uninstall removes every installer-owned artifact while preserving the workspace list and foreign files byte-for-byte. scripts/lint-shell.sh also exits successfully with an explicit skip message when ShellCheck is unavailable; structural bash -n validation still runs. Keep these expectations in sync with this operator documentation when the timer contract changes.

Philosophy

These skills are designed for use in headless agent workflows — they should work without human steering mid-execution. Each skill is self-contained: it locates its own inputs, spawns its own subagents, and produces a complete output.

Lifecycle Flow

The skills cover the complete agent-driven development lifecycle from spec through release. See docs/notes/lifecycle.md for the full SDLC map showing when to invoke each skill, including branch points for spec vs. brief entry and different plan types.

Versioning

Versioned skills record version: X.Y.Z in their SKILL.md frontmatter, or metadata.version for skills shared with Codex, with a corresponding entry in the root CHANGELOG.md. When a skill's SKILL.md, checklists, or scripts change materially (typo fixes excluded), bump its version and add a CHANGELOG entry.

This convention supports drift detection: users with local skill copies can compare their version against the upstream CHANGELOG to see whether they're missing changes. The drift-checker bead (jcs-3) will eventually report version mismatches automatically.

---

Part of jedarden.com

GitHub is a read-only mirror of the canonical Forgejo repository — clone and push through Forgejo.