foundryvtt-module
/foundryvtt-module
FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.
- Author
- laurigates ↗
- Repository
- claude-plugins ↗
- Licence
- MIT
- Last repository change
- 24.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.
Original author description
FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new foundry module.
How it works
- Delegated: the gitops repo-adoption procedure
- When to Use This Skill
- Preconditions
- Phase 0 — Derive and confirm the spec
- Phase 1 — Preflight
- Phase 2 — Scaffold, init, and get to green
- FoundryVTT deltas
- Phase 6 — Verify the finishing pass, then hand back
- Failure modes specific to FoundryVTT
- Notes
SKILL.md preview
---
created: 2026-06-26
modified: 2026-07-30
reviewed: 2026-07-30
name: foundryvtt-module
description: >-
FoundryVTT module idea to gitops-adopted repo: scaffold, create + seed the
repo, open the gitops adoption PR. Use when releasing or spinning up a new
foundry module.
allowed-tools: Bash, Read, Write, Edit, Grep, Glob, TodoWrite, AskUserQuestion
---
# foundryvtt-module
Drives a FoundryVTT **module idea** to a release-ready, gitops-adopted GitHub
repository in one pass, pausing at exactly one human approval.
Reach for `foundryvtt-module-scaffold` on its own when all you want is the local
file tree. Reach for **this** skill when the remote repo should also exist, be
seeded, and be under Terraform management by the time you stop.
## Delegated: the gitops repo-adoption procedure
The second half of this pipeline — creating and seeding the GitHub repo, opening
the gitops adoption PR, the human merge gate, and the import-block-removal
follow-up — is **not duplicated here**. It is identical for every laurigates repo
class and is owned by:
> **`comfyui-plugin:comfy-node`, Phases 3 → 5** (plus its branch-protection hook
> note and its generic failure-mode rows).
That skill's *Adapting Phases 3–5 to another repo class* section names every
value to substitute. Run Phases 0 → 2 here, apply the deltas in
[FoundryVTT deltas](#foundryvtt-deltas), then execute Phases 3 → 5 there.
Two consequences of that procedure worth stating up front, because they shape
what you do in Phase 2 below:
- The seed commit lands on `main` with no intervening branch or PR — read the
owner's Phase 3 for *why* that ordering is load-bearing, not just convenient.
- A Claude Code session will hit a `branch-protection` hook block on that seed.
The owner's note explains the hand-off; do not invent a workaround.
## When to Use This Skill
| Reach for this skill | Reach elsewhere |
|---|---|
| An idea needs to become a live repo — files, remote, gitops entry, release pipeline | Only local files are wanted → `foundryvtt-module-scaffold` |
| Nothing exists yet under that module name | The module already exists → work in its repo |
| Someone asks to "spin up" or "stand up" a Foundry module | A release is due → release-please and the release workflow already handle it |
## Preconditions
- Work from the FoundryVTT workspace (`repos/laurigates/foundryvtt-dev/`), so the
new checkout sits beside `foundryvtt-mcp` / `foundryvtt-mediasoup-webrtc`. The
gitops clone is therefore at `../gitops`.
- The remaining preconditions (a **personal** `gh auth` that may create repos, and
an uncommitted-change-free gitops clone) are stated once in the owner skill —
satisfy them before Phase 3.
## Phase 0 — Derive and confirm the spec
From the idea, derive and **show the user** before creating anything external:
| Field | How to derive | Example |
|-------|---------------|---------|
| `--name` | `foundryvtt-<kebab>` (the GitHub repo). | `foundryvtt-initiative-tweaks` |
| `--id` | Foundry module id; default = `--name` minus `foundryvtt-`. | `initiative-tweaks` |
| `--display` | Title-case. | `Initiative Tweaks` |
| `--desc` | One line, manifest-facing. | `Small quality-of-life tweaks to the combat initiative tracker.` |
| `--variant` | `app` for a UI window; `libwrapper` to patch a core method; else `basic`. | `basic` |
| `--fvtt-verified` | The major Foundry version the harness pins. | `13` |
| topics | `["foundryvtt", "module", …]` + facet tags. | `…,"combat","initiative"` |
Get explicit user sign-off on **name, id, and variant** — renaming any of the
three after the repo exists is expensive.
## Phase 1 — Preflight
Three lookups; every one must come back free before you continue. Any collision
is a full stop — report it and wait.
```sh
test ! -e foundryvtt-initiative-tweaks && echo "local: free" || echo "local: EXISTS"
```
```sh
grep -q '"foundryvtt-initiative-tweaks"' ../gitops/repositories.tf && echo "gitops: EXISTS" || echo "gitops: free"
```
```sh
gh repo view laurigates/foundryvtt-initiative-tweaks >/dev/null 2>&1 && echo "github: EXISTS" || echo "github: free"
```
(`../gitops` assumes the foundryvtt-dev layout; point it at wherever the gitops
clone actually lives.)
## Phase 2 — Scaffold, init, and get to green
```sh
python3 ${CLAUDE_SKILL_DIR}/../foundryvtt-module-scaffold/scaffold.py --name foundryvtt-initiative-tweaks --display "Initiative Tweaks" --desc "Small quality-of-life tweaks to the combat initiative tracker." --variant basic
```
```sh
cd foundryvtt-initiative-tweaks
```
```sh
git init -b main
```
```sh
bun install
```
```sh
just check
```
Notes specific to this stack:
- **`git init -b main` precedes `bun install`** — the install step wires git
tooling and expects a repository to already be present.
- **`bun.lock` belongs in the seed commit.** `bun install` writes it and CI runs
`--frozen-lockfile`; a seed without it fails on the first workflow run.
- `just check` is typecheck + build + lint + test. A red module never reaches
GitHub — repair it here and re-run.
## FoundryVTT deltas
Substitutions to apply while executing `comfyui-plugin:comfy-node` Phases 3 → 5.
Everything the owner skill states that is not listed here applies verbatim.
| Owner's step | FoundryVTT value |
|---|---|
| Repo name | `foundryvtt-initiative-tweaks` |
| gitops clone path | `../gitops` — so `git -C ../gitops …` throughout, and `grep … ../gitops/repositories.tf` |
| Seed commit subject | `feat: scaffold foundryvtt-initiative-tweaks (basic module)` |
| `repositories.tf` entry | `release_please = true` and **no registry flag** — see below |
| PR title | `feat: adopt foundryvtt-initiative-tweaks` |
| What merging the PR pushes | The release-please App credentials only (no registry token) |
| Phase 5 verification | `gh api repos/laurigates/foundryvtt-initiative-tweaks/actions/variables/RELEASE_PLEASE_APP_ID --jq .name` — it should echo the variable name. Skip the owner's `gh secret list` probe; there is no registry secret to find. |
The entry to add under the active repositories `locals` block, beside the other
`foundryvtt-*` entries (mirror `foundryvtt-mcp`):
```hcl
"foundryvtt-initiative-tweaks" = {
description = "Small quality-of-life tweaks to the combat initiative tracker"
visibility = "public"
release_please = true
topics = ["foundryvtt", "module", "combat", "initiative"]
}
```
**Why no registry flag:** Foundry modules are distributed as GitHub release
assets, not through a package registry, so there is no analogue of a ComfyUI
pack's `comfy_registry`. `release_please = true` is the whole adoption surface.
## Phase 6 — Verify the finishing pass, then hand back
**Run the gate before declaring done** — do not close on a self-authored summary:
```sh
python3 ${CLAUDE_SKILL_DIR}/../foundryvtt-module-scaffold/scaffold.py --verify foundryvtt-initiative-tweaks
```
Read `STATUS=`; the exit code is 1 on ERROR.
| `STATUS=` | Action |
|-----------|--------|
| `ERROR` | **Not done.** The ERROR rows are install-blocking — the module id disagrees across `module.json`/`vite.config.ts`/`src/constants.ts`, `esmodules` names a file the build never emits, or an install URL resolves to a release asset that does not exist. Fix and re-run. |
| `WARN` | Deferrable. Log each WARN to `project:foundryvtt` in taskwarrior and say so in the hand-back. |
| `OK` | Hand back. |
An ERROR is never a follow-up item: every one of them ships a module Foundry
either refuses to install or loads to nothing, with no error anywhere in CI. The
same invariants run in the module's own `test` job (`tests/manifest.test.ts`), so
a later drift fails a PR rather than a user's install.
Once the apply lands, the delivery chain is live: conventional-commit PRs →
release-please PR → tag → the release workflow builds, zips `dist/`, and attaches
`<id>.zip` plus `module.json` (the manifest URL) to the GitHub release.
Remaining work to hand over:
- Write the module logic — `basic`: `src/module.ts` + `src/settings.ts`; `app`:
`src/app.ts` + `templates/app.hbs`; `libwrapper`: swap the `Token._draw`
example in `src/patches.ts` for the real patch.
- Exercise it against the local `foundryvtt-harness` (`bun run dev`, or build and
symlink `dist/` into `Data/modules/<id>`). Keep `module.json` `compatibility`
aligned with the Foundry version the harness pins.
- The first `feat:`/`fix:` merge triggers the first release-please PR.
Record durable follow-ups in the user's FoundryVTT taskwarrior project per
`taskwarrior-cross-session`.
## Failure modes specific to FoundryVTT
The gitops-side failures (empty release-please `app-id`, `403 Resource not
accessible by integration`, a plan that *creates* instead of *imports*, a red
`just check` in gitops) are diagnosed in the owner skill's table. Foundry adds
one of its own:
| Symptom | Cause | Fix |
|---------|-------|-----|
| Module fails to load in Foundry | `esmodules` path ≠ Vite output, or `id` ≠ install folder | The scaffold pins both; confirm `dist/<id>.mjs` exists and the installed folder is named `<id>` |
| CI fails on the very first run with a lockfile error | `bun.lock` missing from the seed commit | Commit it — `--frozen-lockfile` has nothing to check against |
## Notes
- Playwright integration tests against the harness, and a Quench in-Foundry
suite, are deliberately not scaffolded. Add them when the module earns them.
- Local gitops work stays read-only (`plan` / `validate`); the owner skill
explains why applies only ever run through `tofu-apply.yml`.
Versions
The database has no other skills named foundryvtt-module.
Database snapshot: 13.11.2026 · package version 1402013f6f90 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100foundryvtt-module-scaffold
Scaffold a new FoundryVTT v13 module repo (Vite + TS + bun + biome, CI, release-please) with basic/app/libwrapper variants. Use when bootstrapping or init-ing a foundry module. - 100comfy-node
Orchestrate a ComfyUI node pack from idea to registry: scaffold, create + seed the repo, open the gitops adoption PR. Use when releasing or spinning up a new comfyui node pack. - 95module-scaffold
Use when creating a brand new module file in modules/ for a new tool category. Generates the boilerplate with correct array prefix, install_module_<name>() function, and ensures it integrates with install.sh, profiles, and MCP server. Triggers on "new module", "add a module for… - 91foundry-vtt-system-dev
Covers building, extending, and maintaining Foundry VTT game systems for v14+. This skill applies when scaffolding a new system, declaring Actor/Item types with documentTypes + TypeDataModel, customizing dice mechanics, implementing combat & initiative, building character… - 100get-started
Get this person set up for the hackathon, from a fresh clone to their app live through GitOps, and lay out the day, the way a coach at the Radar table would. Use when they ask to get set up, check their setup, or what to do first, when they ask what they're looking at in Radar,… - 100gitops-status
Monitor GitOps application health, sync status, and manage ArgoCD deployments via Harness MCP. Use when user says "gitops status", "argocd status", "application sync", "gitops health", "is my app in sync", or asks about GitOps applications.