Remote Project Control

Help the user operate a project whose code is edited locally but actually runs on one or more remote servers over SSH. Establish project memory first, then coordinate safe local and remote actions.

Pair this skill with

research-project-memory

when remote execution state should be linked to project-level experiments, evidence, actions, or worktree status.

Skill Directory Layout

text

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── memory-model.md
│   └── operations.md
├── template_manifest.json
└── templates/
    ├── infra/remote-projects.yaml
    ├── docs/ops/current-status.md
    ├── docs/ops/decision-log.md
    └── agent/local-overrides.yaml

Progressive Loading

Always read
```
references/memory-model.md
```
Read
```
references/operations.md
```
when the user wants to inspect, sync, run, monitor, or fetch artifacts
Use
```
templates/
```
as the source of truth when bootstrapping memory files into the target project
If the repo has
```
memory/
```
, summarize verified remote execution facts into
```
research-project-memory
```
boards without duplicating the remote manifest.

Core Principles

Memory is bootstrap context, not execution truth
Stable shared facts belong in the repo; private machine-specific facts belong in a local override file
Verify volatile state before acting on it
Prefer GitHub or the configured git remote for code sync; do not improvise ad hoc source copying unless the project explicitly uses it
Never use destructive remote git commands without explicit user approval

Memory Files

This skill manages four project-memory files with distinct roles:

```
infra/remote-projects.yaml
```
: stable shared facts such as local/remote repo mapping, scheduler type, launch modes, key paths, and safety policies
```
docs/ops/current-status.md
```
: working memory for the current phase of the project, including active branch, focus, latest known job, open issues, and next step
```
docs/ops/decision-log.md
```
: durable explanations for why stable workflow decisions were made
```
.agent/local-overrides.yaml
```
: optional private overrides for one user's machine, ssh aliases, usernames, and private paths; this file should usually be gitignored

If one or more files are missing, bootstrap them from the bundled templates before trying to infer project context from scratch.

Step 1 — Orient and Load Memory

Detect the project root:

bash

git rev-parse --show-toplevel 2>/dev/null || pwd

Read the existing memory files if present:

<project-root>/infra/remote-projects.yaml

<project-root>/docs/ops/current-status.md

<project-root>/.agent/local-overrides.yaml

```
<project-root>/docs/ops/decision-log.md
```

If
```
infra/remote-projects.yaml
```
is missing, bootstrap the project memory using the templates in this skill. Ask only for the minimum critical fields:

project name
local repo root
default server name
ssh alias
remote repo root
scheduler type
default launch mode
environment activation command

If
```
.agent/local-overrides.yaml
```
is missing but private overrides are clearly needed, offer to create it and recommend adding
```
.agent/
```
to
```
.gitignore
```
.

Step 2 — Build the Session Bootstrap Summary

Merge the loaded files into a concise project context summary. Always show the user a compact bootstrap summary before doing substantial remote work.

Include, when known:

project name
local repo root, current branch, short commit, and whether the tree is dirty
default remote server and remote repo root
scheduler type and default launch mode
environment activation command
key data, checkpoint, scratch, and logs roots
current focus
latest known job
open issues
next planned step
any missing required fields

Step 3 — Re-validate Volatile State Before Action

Before any remote action, verify the pieces of state that could have changed since the last session.

At minimum:

bash

git rev-parse --short HEAD
git branch --show-current
git status --short

For the chosen remote server, verify the remote repo and git state using the configured

ssh_alias

and

remote_repo_root

bash

ssh <ssh-alias> "cd <remote-repo-root> && pwd && git branch --show-current && git rev-parse --short HEAD && git status --short"

If the request involves job submission or monitoring, also verify the scheduler tool and relevant log or output paths on the remote host.

Step 4 — Classify the Request and Execute

Choose one of the following flows and follow the detailed guidance in

references/operations.md

```
bootstrap
```
: create or repair the memory files from templates and fill the minimum required fields
```
inspect
```
: compare local and remote git state, verify paths, env activation, scheduler availability, and summarize the current situation
```
sync-code
```
: prepare local commits, push through the configured git remote, and update the remote repo with non-destructive fast-forward pulls only
```
run-job
```
: use the remote context to submit a job safely; if a new reproducible job script is needed, use
```
run-experiment
```
after this skill has established the environment
```
interactive-session
```
: prepare the correct
```
salloc
```
,
```
srun
```
, or equivalent command and run subsequent commands from the remote repo with the configured environment activation
```
monitor
```
: inspect queue state and tail logs from the configured log roots
```
artifacts
```
: locate remote checkpoints, outputs, and logs; do not bulk-transfer large data unless the user explicitly asks
```
closeout
```
: update project memory at the end of a session

If the runtime cannot execute SSH commands directly, still use this skill: generate the exact commands in the correct order, explain the assumptions, and keep the memory files up to date.

Step 5 — Write Back to the Right Memory Layer

When new information becomes trustworthy, persist it to the appropriate file:

stable mapping and policy changes ->
```
infra/remote-projects.yaml
```
current branch, latest known job, current focus, blockers, and next step ->
```
docs/ops/current-status.md
```
durable workflow rationale ->
```
docs/ops/decision-log.md
```
user-specific ssh aliases, usernames, and private paths ->
```
.agent/local-overrides.yaml
```

If the repo also uses

research-project-memory

, write only cross-project pointers:

```
memory/evidence-board.md
```
: verified job/run pointer for linked
```
EXP-###
```
```
memory/action-board.md
```
: monitor, fetch-artifact, rerun, or report actions
```
memory/current-status.md
```
: latest verified remote execution summary and next verification step
worktree
```
.agent/worktree-status.md
```
: remote run status when tied to a branch/worktree purpose

Do not write volatile scheduler output or one-off shell command results into the stable manifest.

Step 6 — End Every Substantial Session with Closeout

Before finishing, update

docs/ops/current-status.md

whenever the session materially changed project state. Capture:

branch or commit the user should resume from
what was changed locally
what was synced to the remote repo
latest known submitted or running job
log or output paths worth checking next
the next concrete action for the next session

If a new stable practice was established, add a short entry to

docs/ops/decision-log.md

If the project has

memory/current-status.md

, update it with a concise cross-component pointer rather than copying the full remote status.

Bootstrap Targets

When bootstrapping a project, materialize these files from

templates/

templates/infra/remote-projects.yaml

<project-root>/infra/remote-projects.yaml

templates/docs/ops/current-status.md

<project-root>/docs/ops/current-status.md

templates/docs/ops/decision-log.md

<project-root>/docs/ops/decision-log.md

templates/agent/local-overrides.yaml

<project-root>/.agent/local-overrides.yaml

when private overrides are needed

Preserve existing files unless the user explicitly asks to overwrite them.

remote-project-control

NPX Install

Tags

SKILL.md Content

Remote Project Control

Skill Directory Layout

Progressive Loading

Core Principles

Memory Files

Step 1 — Orient and Load Memory

Step 2 — Build the Session Bootstrap Summary

Step 3 — Re-validate Volatile State Before Action

Step 4 — Classify the Request and Execute

Step 5 — Write Back to the Right Memory Layer

Step 6 — End Every Substantial Session with Closeout

Bootstrap Targets