diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/new-worktree/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/new-worktree/SKILL.md index 633143f..9a68be1 100644 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/new-worktree/SKILL.md +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/new-worktree/SKILL.md @@ -1,9 +1,9 @@ --- name: new-worktree -description: Create or reuse a worktree for a branch of a code repo (worktrees//). Worktrees are the default way to make or check out any new branch; use this before starting a ticket, reviewing or fixing a PR branch, or any other branch work, unless the user says not to use worktrees. +description: Create or reuse a worktree for a branch of a code repo (worktrees//), for a ticket, a PR branch, or a throwaway experiment. --- -`repos/` is a bare store (no files); every checkout of a code repo is a worktree under `worktrees//`. `.delphi/setup.sh` makes the default branch's (`worktrees///`); keep it a clean reference: fetch and fast-forward only. Make every other branch with this script, never by switching branches in an existing worktree, unless the user explicitly says not to use worktrees. +Each code checkout is a worktree under `worktrees///`, made from the bare store `repos/`. `.delphi/setup.sh` makes the default branch's; run anything there, but make code changes on a branch of your own. Run from the workspace root: @@ -11,8 +11,8 @@ Run from the workspace root: bash .delphi/new-worktree.sh [] ``` -An existing branch (local or on origin, e.g. a PR's head) is checked out; anything else is created from `` (default: the repo's default branch). It's safe to re-run. It prints the worktree path: `cd` there and do all work in it. +An existing branch (local or on origin, e.g. a PR's head) is checked out; anything else is created from `` (default: the repo's default branch). It's safe to re-run and prints the worktree path to work in. -After the branch merges, remove it with `git -C repos/ worktree remove ../../worktrees//`. +When you're done with a branch, remove it with `git -C repos/ worktree remove ../../worktrees//`. -Argos: always pass `origin/develop` as ``. New ticket branches follow `{issue-number}-{kebab-case-title}`. Run `npm ci` in the worktree's `angular-client/` before building, testing, or running the client. +Argos: pass `origin/develop` as ``. Name the branch `{issue-number}-{kebab-case-title}` for a ticket, or `throwaway-{kebab-case-title}` to try something without one. Run `npm ci` in the worktree's `angular-client/` before building, testing, or running the client. diff --git a/software/application-software/argos/workspaces/argos-dev/.claude/skills/run-local/SKILL.md b/software/application-software/argos/workspaces/argos-dev/.claude/skills/run-local/SKILL.md index 9d91dc5..feb43e8 100644 --- a/software/application-software/argos/workspaces/argos-dev/.claude/skills/run-local/SKILL.md +++ b/software/application-software/argos/workspaces/argos-dev/.claude/skills/run-local/SKILL.md @@ -3,7 +3,7 @@ name: run-local description: Bring up the local Argos environment for running or testing — Docker backend (right profile for what changed) + Angular client on the next free port. Use whenever you need to actually run the app locally, not just start the frontend. --- -From the ticket's worktree, run `bash /.claude/skills/run-local/scripts/find-app.sh`. It prints `client`, `backend`, `scylla` (docker/local), and `free_client_port`. +From the worktree you want to run (a ticket's or throwaway's, or `worktrees/argos/develop/` to try current `develop`; fetch and fast-forward that one first so it isn't stale), run `bash /.claude/skills/run-local/scripts/find-app.sh`. It prints `client`, `backend`, `scylla` (docker/local), and `free_client_port`. - `backend=none`: ask the user to start it on the right profile (Local Development in CLAUDE.md). - `scylla=docker` while `scylla-server/` has changes: flag that the backend is stale. diff --git a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md index 4d06eb7..144188e 100644 --- a/software/application-software/argos/workspaces/argos-dev/CLAUDE.md +++ b/software/application-software/argos/workspaces/argos-dev/CLAUDE.md @@ -6,8 +6,8 @@ You're in Delphi workspace `argos-dev` (branch `ws/argos-dev`); code repos are c ## Branch & Commit Conventions -- Branch from `develop` (not `main`) unless told otherwise. Branch name format: `{issue-number}-{kebab-case-title}` (e.g. `533-csv-upload-download-rules`). -- Commit message format: `#{ticket-number} - {concise description}` (e.g. `#533 - add CSV upload endpoint`). +- Branch from `develop` (not `main`) unless told otherwise. Branch name format: `{issue-number}-{kebab-case-title}` (e.g. `533-csv-upload-download-rules`), or `throwaway-{kebab-case-title}` to try something without a ticket. +- Commit message format: `#{ticket-number} - {concise description}` (e.g. `#533 - add CSV upload endpoint`). Throwaway branches have no ticket, so any short message works. ## Safety Rules @@ -23,8 +23,8 @@ The Argos repo's `develop` is checked out at `worktrees/argos/develop/`. Paths b ## Worktrees -- `worktrees/argos/develop/` is a clean reference to `develop`. Never edit, branch, commit, or run dev servers there; only fetch and fast-forward it. -- Every ticket gets its own worktree at `worktrees/argos//`, and every workflow (implement, test, run, commit, PR) runs there. Create or reuse one with the `new-worktree` skill, based on `origin/develop`: `bash .delphi/new-worktree.sh argos origin/develop`. +- `worktrees/argos/develop/` mirrors `develop`: run anything there (`npm ci`, tests, the backend, `/run-local`), but never edit code, branch, or commit there. The only git operations there are fetch and fast-forward. +- To change code, make a worktree on its own branch with the `new-worktree` skill, based on `origin/develop`: `bash .delphi/new-worktree.sh argos origin/develop`. Use the ticket's branch, or a `throwaway-{kebab-case-title}` branch to experiment without one. If a throwaway turns into real work, file a ticket (`create-ticket`), make the ticket's worktree from `origin/develop`, and in it run `git merge --squash throwaway-{kebab-case-title}` then `/commit`, so the work lands as one commit in the ticket format. - A new worktree has no `node_modules`: run `npm ci` in its `angular-client/` before testing or running the client. ## Local Development