remote-sprite-development

name	remote-sprite-development
description	Use when a Software Factory worker task must mutate or verify an existing remote Fly.io Sprite while preserving locality, checkpoint, evidence, rollback, and review discipline.
version	1.0.1

Remote Sprite Development

Use this skill when a Kanban task targets an existing remote Sprite for application inspection, mutation, deployment, runtime validation, rollback verification, or independent review.

Core locality rule

$HERMES_KANBAN_WORKSPACE is orchestration scratch. It is not the authoritative application source unless the task explicitly says it is analysis-only. All app inspection, edits, installs, builds, tests, runtime checks, checkpointing, and rollback validation must happen on the target Sprite by explicit remote commands.

Accepted remote execution pattern:

sprite -s <target-sprite> exec -- <read-only-command>
sprite -s <target-sprite> exec -- bash -c '<shell command with pipes, redirects, cd, or chaining>'

Use pi-sprite or another approved mechanism only when the task requires it or sprite exec cannot provide reliable mutation, transcripts, checkpoint/rollback hooks, or runtime verification.

Required task context

Every remote Sprite task must state:

• tenant/project name,
• target Sprite name,
• remote app path if known,
• service name, port, or URL if known,
• whether mutation is allowed or the task is read-only/review-only,
• acceptance criteria and quality gates,
• protected data/routes and explicit out-of-scope areas,
• required skills, including software-factory-kanban-workflow, kanban-worker, remote-sprite-development, sprite-exec, and any app-specific skill.

If target Sprite, mutation authority, checkpoint availability, or credential scope is ambiguous, block before mutation.

Checkpoint and rollback discipline

Before mutating a Sprite:

1. Identify current state with read-only commands.
2. Create or verify a pre-change checkpoint/snapshot using the project-approved mechanism.
3. Record the checkpoint handle/id/name, timestamp if available, and exact command.
4. Define the rollback procedure before edits begin.

After mutation:

1. Capture changed files or remote diff summary.
2. Run the task's validation commands on the remote Sprite.
3. Create or record a post-change checkpoint when the task requires it.
4. Preserve enough evidence for another worker to verify or roll back.

Do not continue after checkpoint creation fails unless the task thread contains explicit human approval to accept that risk.

Evidence package

Complete remote Sprite tasks with structured metadata:

{
  "target_sprite": "<sprite>",
  "remote_app_path": "<path>",
  "mutation_allowed": true,
  "pre_change_checkpoint": "<id or unavailable with reason>",
  "post_change_checkpoint": "<id or not required>",
  "commands_run": ["<command summaries>"],
  "changed_files": ["<remote paths>"],
  "verification": ["<command/result summaries>"],
  "rollback": "<exact rollback procedure>",
  "follow_up_tasks": ["<task ids>"],
  "risks_or_limitations": ["<known risks>"]
}

For read-only review tasks, set mutation_allowed to false, independently inspect the remote state, compare it with the implementation evidence, and explicitly state pass/fail plus any gaps.

Common failure modes

• Mutating local scratch files and claiming remote success.
• Forgetting bash -c for pipes, redirects, cd, heredocs, variable expansion, or chained commands.
• Continuing after checkpoint failure without approval.
• Omitting rollback instructions.
• Reporting "done" without remote validation output.
• Ignoring project-specific Remember sections or required board skills.