a-green-hand-jack/remote-project-control

Remote Project Control

Before Acting — Mandatory

1. Detect scope: run git rev-parse --git-common-dir vs --show-toplevel. In a project-control-root layout, <ProjectName>/ and <ProjectName>/code/ are independent repos — inspect them separately.
2. Read project memory if memory/BRIEFING.md exists in the project root:
   • memory/BRIEFING.md — compact project state snapshot
   • memory/project-conventions.md — active conventions including SSH wrappers, server paths, and scope constraints for this project
3. If inside a worktree: read .agent/worktree-status.md first; write in-progress server state there, not into root memory/.
4. Treat volatile state (queue, server load, job status) as requiring fresh verification — do not act on cached session memory for these values.

Skipping this step risks using stale server state, wrong environment paths, or violating project-specific SSH wrapper conventions.

---

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

Terminology used by this skill:

• local: the user's local development machine, usually the Mac where the agent is running
• remote or git remote: the Git hosting remote such as GitHub or GitLab, e.g. origin
• server: an execution machine or cluster reached by SSH, such as quest, ibex-vscode, or epfl-haas

The skill name is historical. In project memory and user-facing summaries, prefer server for SSH/HPC/RunAI execution environments and reserve remote for Git remotes unless quoting an existing field name.

Pair this skill with research-project-memory when server execution state should be linked to project-level experiments, evidence, actions, or worktree status. Pair with run-status-monitor after job submission when lightweight progress checks or artifact-bounded monitoring are needed without pulling raw logs into context.

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── memory-model.md
│   ├── operations.md
│   └── ssh-command-wrappers.md
├── scripts/
│   ├── remote-cmd
│   └── remote-bash
├── 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
• Read references/ssh-command-wrappers.md before composing SSH commands that include loops, shell variables, command substitution, pipes, globs, find, awk, or multi-line logic
• Use templates/ as the source of truth when bootstrapping memory files into the target project
• If the repo has memory/, summarize verified server execution facts into research-project-memory boards without duplicating the server 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/GitLab or the configured Git remote for local-to-server code sync; do not improvise ad hoc source copying unless the project explicitly uses it
• Never use destructive server-side git commands without explicit user approval
• Treat network access as a separate failure mode for gh, git, ssh, curl, and scheduler/API commands; DNS, timeout, or connection errors in a sandboxed agent runtime must be retried with network permission before diagnosing credentials or configuration
• Treat GitHub/GitLab API access as separate from normal git SSH access: git push may work while gh repo create, gh repo view, or gh repo fork fails because gh is not authenticated
• Treat GitHub/GitLab API network access as separate from authentication: in sandboxed agent runtimes, gh may fail to reach api.github.com unless the command is rerun with network permission
• Treat GitHub Projects as GitHub API operations, not Git remotes. gh project ... needs a token with the project scope; refresh it with gh auth refresh -s project before project-board commands when the scope is missing.
• In project-control-root layouts, inspect root and component repos separately; <ProjectName>/ and <ProjectName>/code/ may be independent Git repos with different remotes and permissions
• Use remote-cmd for simple argv-style server commands and remote-bash for scripts, loops, or anything with shell syntax. See Forbidden SSH Patterns below.

Forbidden SSH Patterns

Never compose these directly in the transcript or agent command output:

| Anti-pattern | Use instead | |---|---| | ssh <alias> "cd <path> && <cmd>" | remote-cmd <alias> <repo> -- <cmd> | | ssh <alias> "<cmd> $VAR" (shell variable) | remote-cmd <alias> <repo> -- <args> | | ssh <alias> "<cmd> \| <cmd>" (pipe / loop / find / awk) | remote-bash <alias> <repo> <script> | | ssh <alias> "<cmd1> ; <cmd2>" (chained) | remote-bash <alias> <repo> <script> | | ssh A "ssh B '<nested cmd>'" (nested one-liner) | project-local scripts/ops/ wrapper called via remote-bash |

Exception: single-word no-argument commands with no shell syntax are fine (ssh <alias> "pwd", ssh <alias> "hostname").

Why: local shell expands $VAR, ~, globs, and quotes before the SSH command is sent, silently corrupting the intended server-side command. Wrappers quote correctly and keep the transcript clean.

Memory Files

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

• infra/remote-projects.yaml: stable shared facts such as local repo path, Git remote/branch, server 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

1. Detect the project root:

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

2. 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

3. 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
• server repo root
• scheduler type
• default launch mode
• environment activation command

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

5. If the project appears to be a control root with component repos, inspect each relevant repo independently instead of assuming one Git remote:

git -C <project-root> remote -v
git -C <project-root>/code remote -v
git -C <project-root>/paper remote -v

Missing remotes in one repo do not imply missing remotes in another.

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 server and server repo root
• Git remote name and branch used for sync
• 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:

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

For the chosen server, verify the server-side repo and git state using the configured ssh_alias and remote_repo_root or server_repo_root:

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

For repeated checks, prefer the safer wrapper equivalent:

remote-cmd <ssh-alias> <remote-repo-root> -- git status --short
remote-bash <ssh-alias> <remote-repo-root> scripts/ops/status.sh

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

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 server git state, verify paths, env activation, scheduler availability, and summarize the current situation
• git-remote-setup: inspect or create GitHub/GitLab repositories, set remotes, fork upstream repos, link optional GitHub Projects, or prepare local-to-server sync through a Git remote
• sync-code: prepare local commits, push through the configured Git remote, and update the server repo with non-destructive fast-forward pulls only
• run-job: use the server 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 server 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.

Before any gh operation that uses GitHub's API, including gh repo ... and gh project ..., run:

gh auth status

Interpret failures carefully:

• If the output says it cannot connect to api.github.com, github.com, or asks to check the internet connection, treat it as network/sandbox access first. Rerun the same gh check with network permission before asking the user to log in again.
• If gh auth status has network access and still reports an invalid token, missing account, or failed login, stop the GitHub API flow and tell the user to re-authenticate with gh auth login -h github.com.
• Do not interpret either failure as a repository creation failure, Git remote failure, SSH key failure, or server problem.

For GitHub Projects:

• Verify gh auth status shows the project scope before gh project create, gh project view, gh project link, gh project item-*, or gh project field-*.
• If the scope is missing, run or ask the user to run gh auth refresh -s project.
• If normal sandboxed gh auth status fails but a network/keyring-enabled check succeeds, treat the normal failure as sandbox or Keychain access, not a real logout.
• Record the GitHub Project URL/number in root memory/project.yaml when the code repo belongs to a project-control-root layout.

Apply the same network-first classification to other commands:

• git fetch, git push, git pull, git ls-remote: DNS or connection failure is network/sandbox access until rerun with network permission.
• ssh <server>: hostname resolution, timeout, or network unreachable is network/VPN/sandbox reachability until rerun with the expected network permission and VPN state.
• curl, package managers, and scheduler/API CLIs: connection failure is not enough to prove credentials or server configuration are wrong.

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 server 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 server execution summary and next verification step
• worktree .agent/worktree-status.md: server 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 pushed to the Git remote and pulled into the server 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 a new project-specific SSH/remote convention was established (e.g., a new wrapper alias, a server path, a RunAI pool, a scheduler flag), write it to memory/project-conventions.md under the ssh or compute category. When server infrastructure changes make a convention obsolete, move it to Expired with the reason.

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.