@sbswang2002/flash 0.1.49

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sbswang2002/flash",
+  "version": "0.1.49",
+  "packageManager": "pnpm@11.1.1",
+  "description": "Run a coding agent in a loop inside a git repo, one commit per successful iteration",
+  "type": "module",
+  "bin": {
+    "flash": "dist/cli.mjs"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "start": "node dist/cli.mjs",
+    "lint": "eslint src",
+    "format": "prettier --write src",
+    "format:check": "prettier --check src",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "pnpm run build && vitest run",
+    "test:e2e": "pnpm run build && vitest run e2e/",
+    "test:coverage": "vitest run --coverage --exclude \"e2e/**\""
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.2",
+    "acp-mock": "^1.1.0",
+    "acpx": "^0.6.1",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "prettier": "^3.0.0",
+    "tsdown": "^0.21.7",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gwang-indoc/gnhf_update.git"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/flash/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: flash
+description: Use when the user asks to run FLASH, says they are going to sleep or leaving and wants an agent-managed coding run, asks to supervise, steer, or review an active FLASH run, or gives feedback on FLASH results.
+---
+
+# FLASH
+
+## Overview
+
+FLASH is an agent orchestrator: it repeatedly calls another coding agent until a natural-language stop condition is met. This skill teaches the host agent to prepare one durable run and, in Companion mode, steer or review it.
+
+Core rule: the host agent orchestrates; FLASH executes. Do not manually implement inside the same scope while a FLASH worker is responsible for it unless the user explicitly changes the delegation.
+
+In Companion mode, FLASH completion is not user acceptance. "Stop condition met" only means the worker stopped; the host still compares the result to the user's latest requirements and fresh verification.
+
+## Modes
+
+Choose exactly one mode for the run.
+
+### Hands-Off
+
+Use when the task is bounded, verification is clear, and the user wants one configured run to proceed without steering.
+
+- Prepare a precise prompt with constraints, non-goals, verification, and stop condition.
+- Launch FLASH and wait for completion.
+- Intervene early only for hard failure, runaway scope, destructive behavior, or impossible prerequisites.
+- Report the final FLASH status after exit.
+
+Examples:
+
+- English: "I'm going to bed. Use FLASH with Copilot to keep working on this branch and stop when the test suite passes."
+- Chinese: "我要睡了。用 FLASH 接着跑这个分支，测试都过了就停。"
+
+### Companion
+
+Use when the task is uncertain, exploratory, design-heavy, research-heavy, or likely to need course correction.
+
+Default to Companion when the user asks to iterate until satisfied, requests multi-round work, provides review findings, asks for design/skill/documentation improvement, or asks for supervision.
+
+- Keep a note of original intent, branch, session id, and last known result.
+- Poll the active FLASH process until exit or until an intervention point appears.
+- Intervene when the worker optimizes the wrong thing, repeats failed fixes, skips requested research, drifts scope, or claims success without evidence.
+- Treat review findings as the next acceptance criteria.
+- Prefer a new bounded FLASH prompt over manually taking over implementation.
+
+Examples:
+
+- English: "Run FLASH for a few rounds on this onboarding flow. Check the diff between rounds and tighten the next prompt if it starts polishing the wrong thing."
+- Chinese: "用 FLASH 多跑几轮这个 onboarding 流程。每轮看一下 diff，如果它开始改偏了，就收窄下一轮 prompt。"
+
+## Launch
+
+Check the installed CLI before relying on flags:
+
+```bash
+flash --help
+```
+
+Known shape:
+
+```bash
+flash \
+  --agent <claude|codex|rovodev|opencode|copilot|pi|acp:<target>> \
+  --max-iterations <n> \
+  --stop-when "<observable completion condition>" \
+  --prevent-sleep on \
+  "<worker prompt>"
+```
+
+If FLASH has no `--model` flag, put model requirements in the worker prompt or backend config. Do not invent unsupported flags.
+
+Before launch:
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline --max-count=5
+```
+
+Prompt skeleton:
+
+```text
+Objective: <one concrete outcome>.
+
+Use <agent/model requirement>. Work in this repo. Treat this as a long-running FLASH task.
+
+Before coding, inspect the current repo, relevant docs, and recent commits. Preserve user changes. Do not make unrelated refactors.
+
+After each meaningful slice, run relevant verification. If blocked, commit no fake success; leave notes with the blocker and evidence.
+
+Stop only when: <observable completion condition>.
+```
+
+## Steer
+
+In Companion mode, evaluate after each iteration or meaningful output chunk:
+
+| Signal                                                        | Action                                                               |
+| ------------------------------------------------------------- | -------------------------------------------------------------------- |
+| Worker found a real blocker                                   | Stop or relaunch with blocker-specific instructions                  |
+| Good partial slice                                            | Let it continue or tighten the next stop condition                   |
+| Skipped requested research                                    | Relaunch with research as explicit first deliverable                 |
+| Worker changes unrelated files                                | Stop and review before continuing                                    |
+| Worker claims success without verification                    | Review immediately; relaunch only with evidence-based stop condition |
+| Reviewer finds a blocking issue or user says not satisfactory | Relaunch with that finding as the sole bounded correction            |
+
+Steering prompt:
+
+```text
+Continue from the current repo state. The previous run partially succeeded: <evidence>.
+
+Do not redo completed work. Focus only on <bounded correction>.
+
+The issue to fix now is <specific observed issue>. Verify with <commands/checks>.
+
+Stop only when <observable condition>.
+```
+
+## Companion Review
+
+Use only in Companion mode, when the host is supervising quality or deciding whether to continue with another bounded run.
+
+1. Inspect branch, status, commits, changed files, and diff.
+2. Read FLASH notes/logs as claims, not evidence.
+3. Run independent verification: tests, lint, build, typecheck, manual QA, or domain-specific checks.
+4. Compare the result to the stop condition and the user's latest feedback.
+5. Decide: **Mergeable**, **Needs follow-up FLASH run**, or **Do not merge**.
+
+If the result needs follow-up, continue in Companion mode instead of presenting the run as complete. Do not merge unless explicitly authorized.
+
+## Findings
+
+Use when the user provides findings such as "not preserved", "scope drift", "missing requirement", or "why did you stop".
+
+1. Treat the run as Companion mode.
+2. Convert each finding into an observable correction. Preserve severity, file/line scope, and the user's wording.
+3. Relaunch on the same candidate branch when salvageable.
+4. Prompt the worker to fix only the bounded finding, preserve completed valid work, verify, and stop only when the finding is no longer true.
+5. Review again after the follow-up.
+6. Repeat until no blocking findings remain, verification passes, or a real blocker is found.
+
+## Morning Review
+
+Use when the user returns with "good morning", "how did last night's run go?", or similar after a FLASH run.
+
+Do not ask what to review first. Reconstruct state:
+
+```bash
+git status --short
+git branch --show-current
+git log --oneline --decorate --max-count=20
+pgrep -fl 'flash|claude|codex|copilot|opencode|rovodev' || true
+```
+
+Inspect likely FLASH branches, notes, logs, terminal sessions, and changed files. If a FLASH process is still running, report that first.
+
+Report mode, agent, branch, status, changes, verification, stop-condition result, quality assessment, and recommended next action. Never summarize an overnight run from memory.
+
+## Agent
+
+- `copilot`: explicit GitHub Copilot CLI request or local Copilot config.
+- `codex`: repo-aware code work or review-heavy tasks.
+- `claude`: reasoning-heavy implementation or prose-heavy planning when configured.
+- `pi`: explicit Pi request or local Pi configuration.
+- `opencode` / `rovodev`: explicit request or repo-specific setup.
+- `acp:<target>`: explicit ACP target request, or when the user wants to drive a custom ACP-compatible agent through FLASH.
+
+## Safety
+
+- Preserve user changes. Never run destructive git commands to clean up a FLASH branch.
+- In Companion mode, do not trust a worker's success summary without fresh verification.
+- Keep prompts outcome-based and evidence-based.
+- Use concrete stop conditions. Bad: "looks good". Good: "the target workflow succeeds, relevant checks pass, and no unrelated files changed."
+- If the user is away, produce branches and a status report, not irreversible changes, unless explicitly authorized.