Walsworth-Group/physkit / skills/new-project
new-project
VerifiedThe project home above campaigns; new-campaign invokes it.
new-project — the home for a whole investigation
A Project is one physical system investigated over many Campaigns (versioned attempts) and Sessions
(ad-hoc work). It exists so shared data and docs live once, referenced by relative path and never copied, and
so "what each version changed and found" lives in one index. The interview stance is CORE's
Stage 0, as applied in new-campaign's "Stance for the interview".
Every campaign lives in a project — there is no bare-campaign mode
Two entry paths: directly, when the user starts a new line of research, or from new-campaign, whose
Step 0.1 found no project home. When called from new-campaign, the interview below is largely answered
already: carry those answers in, fill the tree, and return. Do not call back into new-campaign; it is
mid-run and resumes on its own.
A one-off project costs three near-empty documents; the physics, conventions, and instrument knowledge
lives once in PROJECT.md rather than multiplying. A sibling campaign, a fork, or an ad-hoc session can
be added later with no reorganization and no path rewrites.
Interview (gather, don't assume)
- Physical system & end goal — what system, what decision the investigation serves, what "done" looks like.
- Canonical data — where the experimental/reference data lives. If it is large or already on disk, keep it
out of the tree and record a
data_pathpointer; else place a read-only copy atdata/. Data is never copied per-campaign; one copy referenced by relative path prevents duplication and broken paths. - Shared physics / conventions / system params — the facts every campaign inherits
(→
PROJECT.md's knowledge sections), and which of them are standing constraints: the hard rules a run must obey (inventory tags, a-priori bound, sign/unit/frame conventions, run-constraining rig parameters), which the campaign driver delivers into every spawned prompt. - First campaign — the initial attempt (its goal + frozen metric); scaffolded via
new-campaign(below).
Generate the project tree
PhysKit resource links in this skill are relative to the directory containing this SKILL.md, not to
the process working directory. Resolve them to absolute paths before reads, copies, or commands. If the
linked doctrine or template directory is absent, stop and ask the user to install the full PhysKit
plugin; never substitute an unrelated source checkout. Copy
from ../../templates/project/, strip .tmpl, and fill placeholders:
<project>/
├── README.md # the front door: a very short "where to find things" map — nothing deeper
├── PROJECT.md # THE overview: §Mission · §Standing constraints (driver-delivered) · system
│ # knowledge · §Updates from discoveries · §Durable decisions · §Lineage (the
│ # index of every campaign & session; schema inside)
├── CLAUDE.md # one rendered source for the harness-native instruction twins
├── AGENTS.md # exact byte-copy of CLAUDE.md for Codex
├── data/ # canonical data (read-only) + README; OR a DATA_PATH.txt pointer — NEVER written by the loop
├── campaigns/ # each campaign lives here (new-campaign generates into it)
├── sessions/ # ad-hoc / non-campaign sessions — each a <date>_<slug>/ with a NOTES.md
└── reports/ # one project-level outputs location (+ README)
Promoted shared artifacts get flat, purpose-named project-level dirs (scripts/, models/,
datasets/, …) created on demand at the first promotion, never pre-created empty. A promoted
artifact is versioned and carries a PROJECT.md §Lineage promotion line — that line, not a
directory name, is what marks it promoted-frozen (project CLAUDE.md rule 6).
- Author
PROJECT.md— the one overview, ordered for a first read. Fill §Mission (goal, decision served, done-criteria, project-wide invariants, the data location/pointer) and the knowledge sections (target of study, predictive framework, instrument, equations and methods) from the interview. Fill its §Standing constraints with care and keep it lean: the campaign driver delivers that section into every spawned prompt, every cycle; depth belongs in the sections below it. Leave §Updates from discoveries and §Lineage as their seeded empty forms. Preserve the edit-tier comment banners — the OPEN/GUARDED split (mirrored as projectCLAUDE.mdrule 7) is what lets future agents update the overview without eroding the signed-off core. - Resolve every
[[KEEP — … ]]tag: keep what it marks (the headings the runner and validator read, the instruction-file marker on line 1) and delete the tag line; the rest is shaped to the project. - Keep
README.mdshort. It is the map for someone unfamiliar — what campaigns and sessions are, where the data and promoted artifacts live — pointing atPROJECT.mdfor everything deeper. The map lives there ONLY; do not restate it inPROJECT.md. - Materialize both harness instruction files from one render. Render
CLAUDE.md.tmplonce, write exact-case regularCLAUDE.md, then byte-copy it to exact-case regularAGENTS.md. Never author or update the twins independently. - Data home (copy the README; decide copy vs pointer). Copy
data/README.md(the read-only, referenced-never-copied rule). Then, from interview topic 2: if the canonical data is on-tree, place the read-only files indata/. If it lives off-tree (large, or already on a lab store), do not copy it: writedata/DATA_PATH.txtwith one line, the absolute path, and record the samedata_pathinPROJECT.md§Mission. That pointer is the project's only absolute path. - Sessions & reports scaffolding.
sessions/starts empty. Each later ad-hoc session gets its ownsessions/<YYYY-MM-DD>_<slug>/NOTES.mdauthored from../../templates/project/sessions/NOTES.md.tmpl; do not pre-create empty session folders. Copyreports/README.md(the single outputs location). - Relative paths only. Campaigns reference
../../dataand the promoted dirs (../../scripts, …), so the whole tree relocates as one unit. The only absolute path allowed is the resolveddata_pathpointer, documented inPROJECT.md§Mission. - Strip
.tmplon write. Fill every{{PLACEHOLDER}}; run the validator when done.
Then the first campaign
If new-campaign called you, return to it; it scaffolds the campaign under campaigns/ itself. If the user
came here directly, invoke new-campaign to scaffold the first campaign, wired to ../../data, and append
its opening row to PROJECT.md §Lineage. Either way, do not duplicate the interview: carry over what was
gathered here.
Verify
Run the bundled validator on the project root (it auto-detects project vs campaign trees, and old- vs new-layout projects) and fix anything it flags:
python "<resolved path to the new-campaign skill>/scripts/validate_campaign.py" <project_root>
Resolve that command from the linked
../new-campaign/scripts/validate_campaign.py, not from
the shell's current directory.
It checks the required project files/dirs, that PROJECT.md carries its ## Standing constraints
section (what the campaign driver delivers into every spawned prompt) and its ## Lineage tables, no
leftover {{…}} in the project docs, that every campaign under campaigns/ (incl. _archive/) is
indexed in §Lineage, that no campaign carries a local copy of the overview (referenced-never-copied),
and that no config hard-codes an absolute path (portability).
Then also confirm:
data/is a read-only canonical copy or aDATA_PATH.txtpointer — not a per-campaign copy — and carries its README.campaigns/,sessions/,reports/exist (reports/README.mdpresent); no empty pre-created purpose dirs.- No stray reference to a doc the tree does not hold (a
SYSTEM.md, a project-rootENGINEERING_NOTES.md): all of it lives inPROJECT.md, one section each — except verified findings, which live in the campaigns that produced them, pointed at from §Lineage and §Updates from discoveries. - Report the project root, the data decision (copy vs pointer), and the first campaign created.
Composition
Composes new-campaign (first and subsequent campaigns) and fork-campaign (invalidation forks).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |