Add continuous cloud-agent workflow and repository safeguards

.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# Repository instructions
+
+Follow `AGENTS.md` as the repository-wide engineering contract.
+
+Keep fstack portable, dependency-light, and simple. Preserve the distinction between interactive skills and the continuous `fstack-run` cloud workflow. Inspect source truth before editing, make the smallest complete change, run `sh scripts/validate.sh`, inspect the final diff, and deliver changes on a task branch through a pull request.
+
+Never overwrite unrelated work, commit secrets, force-push, or claim unobserved test results.

.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## What changed
+
+<!-- State the user-visible or agent-visible outcome. -->
+
+## Why this is the smallest complete change
+
+<!-- Name deliberate exclusions and avoided complexity. -->
+
+## Evidence
+
+```text
+Commands run:
+
+Observed results:
+```
+
+## Skill and documentation checks
+
+- [ ] `sh -n scripts/validate.sh`
+- [ ] `sh scripts/validate.sh`
+- [ ] `git diff --check` against the base branch
+- [ ] New or changed skills are documented in `README.md`
+- [ ] Frontmatter name matches the skill directory
+- [ ] No secrets, credentials, private local paths, or generated files were added
+
+## Missing evidence or remaining risk
+
+<!-- Write "None" only when every applicable check was observed. -->

.github/workflows/validate.yml

@@ -0,0 +1,37 @@
+name: Validate skills
+
+on:
+  push:
+    branches:
+      - main
+      - 'feat/**'
+      - 'fix/**'
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: validate-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Check validator syntax
+        run: sh -n scripts/validate.sh
+
+      - name: Validate skill collection
+        run: sh scripts/validate.sh
+
+      - name: Check changed text for whitespace errors
+        shell: sh
+        run: |
+          base=${GITHUB_BASE_REF:-main}
+          git diff --check "origin/$base...HEAD"

AGENTS.md

@@ -0,0 +1,91 @@
+# fstack repository agent contract
+
+## Purpose
+
+fstack is a portable collection of Agent Skills. Keep it small, readable, agent-agnostic, and safe to install in other repositories.
+
+The interactive skills intentionally stop at human decision points. `fstack-run` is the continuous cloud-agent path. Do not remove either mode or silently make one behave like the other.
+
+## Source of truth
+
+Before changing the repository:
+
+1. Confirm the repository root, current branch, HEAD, and working-tree state.
+2. Read this file, `README.md`, and every skill or document affected by the task.
+3. Inspect recent history when the task changes established behavior.
+4. Treat repository files and command output as authoritative. Do not substitute conversation memory for current state.
+5. Preserve unrelated or pre-existing changes. Never reset, clean, overwrite, or force-push them away.
+
+## Change rules
+
+- Make the smallest complete change that satisfies the request.
+- Keep one job per skill.
+- Keep `SKILL.md` concise. The hard limit is 500 lines; prefer roughly 150 or fewer.
+- Keep skill names lowercase and hyphenated. The frontmatter `name` must match the containing directory.
+- Put activation conditions in the frontmatter `description` so agents can discover the skill correctly.
+- Prefer plain Markdown. Add scripts, references, or assets only when they improve repeatability or correctness.
+- Do not hardcode one vendor's tool names into a generally portable skill unless the skill is explicitly vendor-specific.
+- Do not add dependencies or generated files for validation that POSIX shell can handle.
+- Update `README.md` whenever a skill is added, renamed, removed, or materially changes behavior.
+
+## Continuous cloud-agent behavior
+
+When a user asks for autonomous, end-to-end, unattended, cloud-agent, or "finish it" execution, use `fstack-run`.
+
+Proceed without routine approval stops. Ask only when the missing answer changes the safe action and cannot be resolved from repository evidence. Ordinary implementation choices should use the smallest reversible option consistent with existing conventions.
+
+A cloud run is not complete after planning, editing, one passing test, or opening a pull request. It is complete only after implementation, verification, final diff review, and a durable delivery artifact exist, or after a concrete external blocker is proven.
+
+## Verification
+
+Run all applicable checks. For this repository, the minimum gate is:
+
+```sh
+sh -n scripts/validate.sh
+sh scripts/validate.sh
+git diff --check
+```
+
+Then inspect the final diff and confirm:
+
+- every changed file belongs to the task;
+- all skill frontmatter is valid and discoverable;
+- the README and routing tables match the skills on disk;
+- no secret, credential, local path, or generated artifact was added;
+- no interactive behavior was accidentally converted into autonomous behavior, or vice versa.
+
+Never claim a command passed unless its output was observed.
+
+## Git and delivery
+
+- Work on a task branch, not directly on `main`.
+- Commit only task-owned files.
+- Do not skip hooks, force-push, or amend published commits.
+- Push the task branch and open a pull request when the environment supports it.
+- Do not merge or deploy unless the user explicitly requests it and repository policy permits it.
+
+## Completion receipt
+
+End substantial work with:
+
+```text
+PROVEN
+- implemented files and behavior
+- commands run and observed results
+- branch, commit, and pull request
+
+MISSING EVIDENCE
+- checks that could not be run and the exact reason
+
+POSSIBLY WRONG OR OVERSTATED
+- remaining assumptions, or none
+
+EXACT NEXT ACTION
+- the one smallest action needed next, or none
+
+WHAT DOES NOT COUNT AS COMPLETION
+- planning, unverified edits, or a PR with failing/unknown checks
+
+CONTEXT
+- safe to continue here, or why a fresh context is required
+```

CLAUDE.md

@@ -0,0 +1,7 @@
+# Claude Code instructions
+
+Read and follow `AGENTS.md` before planning or editing.
+
+Use the repository files and observed command output as source truth. Preserve unrelated changes. For autonomous or end-to-end work, use the `fstack-run` workflow and continue through implementation, verification, final review, commit, push, and pull request unless a concrete blocker prevents it.
+
+Do not treat planning, unverified edits, or opening a pull request as completion.

README.md

@@ -4,106 +4,153 @@ Agent skills that ask: can this be less?
 
 ## The problem
 
-Skill collections keep growing. 30 skills, personas, pipelines, voice triggers. You can't hold that in your head, so you stop using it.
+Skill collections keep growing. Personas, pipelines, ceremonies, and overlapping commands become harder to remember than the work itself.
 
-And the complexity doesn't stay in the workflow. A process built to sound smart — phases, personas, ceremony — produces code that sounds smart too: layers, abstractions, and options nobody asked for.
+That complexity leaks into the code. A process built to sound smart often produces layers, abstractions, and options nobody asked for.
 
 ## The idea
 
-fstack is 13 skills. Plain names, one job each.
+fstack is 14 small skills with plain names and one job each.
 
-The agent works in small steps and checks in with you. You approve; it executes. No long autonomous runs.
+It has two deliberate modes:
 
-One skill — `/fstack-simplify` — exists only to remove things. No other stack has that.
+- **Interactive mode:** you drive each stage and approve real choices.
+- **Cloud mode:** `/fstack-run` continues from source-truth inspection through implementation, tests, review, fixes, commit, push, and pull request.
+
+One skill — `/fstack-simplify` — exists only to remove things.
 
 ## Install
 
-```bash
-npx skills@latest add flaviocopes/fstack
+With GitHub CLI 2.90 or later, preview and install the continuous runner for GitHub Copilot or another supported agent host:
+
+```sh
+gh skill preview naytewilson/fstack fstack-run
+gh skill install naytewilson/fstack fstack-run
+```
+
+With the cross-agent `skills` CLI, review the collection and install only the runner globally:
+
+```sh
+npx skills@latest add naytewilson/fstack --list
+npx skills@latest add naytewilson/fstack --skill fstack-run -g -y
+```
+
+Install the complete collection interactively:
+
+```sh
+npx skills@latest add naytewilson/fstack
 ```
 
-That's it. No dependencies, no build step, no config.
+The skills themselves have no runtime dependencies or build step.
 
-## The core loop
+See [Cloud-agent setup](docs/CLOUD_AGENTS.md) for agent-specific installation, permissions, invocation prompts, safety defaults, validation, updates, and maintenance.
+
+## Cloud mode
+
+Use `/fstack-run` when the agent should finish a repository task without routine approval stops.
+
+```mermaid
+flowchart LR
+    Inspect["Inspect source truth"] --> Isolate["Protect existing work"]
+    Isolate --> Plan["Plan briefly"]
+    Plan --> Build["Implement"]
+    Build --> Test["Test and validate"]
+    Test --> Review["Review and simplify"]
+    Review -->|Fix needed| Build
+    Review -->|Ready| Deliver["Commit, push, pull request"]
+    Deliver --> Verify["Verify checks and receipt"]
+```
+
+The runner stops only for a proven external blocker, a decision that changes the safe action, an explicit user stop, or a completed verified delivery.
+
+## Interactive mode
+
+Use the original loop when you want to control each transition:
 
 ```mermaid
 flowchart TD
-    Start{"Human: task clear?"}
+    Start{"Task clear?"}
     Start -->|No| N["fstack-nail"]
-    N --> Task["Human approves the task"]
+    N --> Task["Human approves task"]
     Task --> P["fstack-plan"]
     Start -->|Yes| P
-    P --> Plan["Human approves the plan"]
+    P --> Plan["Human approves plan"]
     Plan --> B["fstack-build"]
     B --> C["fstack-check"]
-    C -->|Ready to push| Push["fstack-push"]
-    C -->|Not ready| Earlier["Human picks the right earlier step"]
+    C -->|Ready| Push["fstack-push"]
+    C -->|Not ready| Earlier["Human chooses an earlier step"]
     Earlier -.-> N
     Earlier -.-> P
     Earlier -.-> B
 ```
 
-Invoke a skill directly, or ask `/fstack` to choose one. Nothing continues automatically.
-
-Before the loop:
-
-- `/fstack-roast` — when you have a product idea and want honest pushback before writing code
-- `/fstack-interview` — when the agent should know the business behind the project; it asks, you answer, the answers land in AGENTS.md
-
-Sprinkle in anywhere:
+Invoke a skill directly, or ask `/fstack` to choose one.
 
-- `/fstack-simplify` — when something feels bloated, from one file to the whole codebase
-- `/fstack-design` — when UI looks off or inconsistent with the rest
-- `/fstack-document` — when the project needs docs, or the docs have gone stale
-- `/fstack-learn` — when something is worth remembering
-- `/fstack-counselors` — when a decision is big enough to want three independent model opinions
-
-Don't know where to start? `/fstack` is the front door.
-
-```mermaid
-flowchart LR
-    Map["Where each skill fits"]
-    Map --> Front["Front door<br/>fstack"]
-    Map --> Before["Before building<br/>fstack-roast<br/>fstack-interview"]
-    Map --> Core["Core loop<br/>fstack-nail<br/>(when unclear)<br/>fstack-plan<br/>fstack-build<br/>fstack-check<br/>fstack-push"]
-    Map --> Needed["Use when needed<br/>fstack-simplify<br/>fstack-design<br/>fstack-document<br/>fstack-counselors"]
-    Map --> After["After useful work<br/>fstack-learn"]
-```
-
-## The 13 skills
+## The 14 skills
 
 | Skill | What it does |
 |---|---|
-| `/fstack` | The front door. Picks the right skill for your request. |
-| `/fstack-roast` | Stress-tests a product idea. Ends with a verdict and the smallest version worth building. |
-| `/fstack-interview` | Interviews you about the product — demand, customer, pricing, risks — and records the answers in AGENTS.md. |
-| `/fstack-counselors` | Asks the 3 most capable models the same question, independently, and synthesizes one verdict plus each opinion. |
-| `/fstack-nail` | Clarifies a vague task, nails down a 3-line summary, and gets your yes before planning. |
+| `/fstack` | Front door. Lists the stack or routes a task to one skill. |
+| `/fstack-run` | Completes repository work continuously from inspection through verified pull request. |
+| `/fstack-roast` | Stress-tests a product idea and finds the smallest version worth building. |
+| `/fstack-interview` | Records product, customer, demand, pricing, distribution, and risk context in the repository. |
+| `/fstack-counselors` | Gets three independent model opinions and synthesizes one verdict. |
+| `/fstack-nail` | Clarifies a vague task and gets approval on a three-line summary. |
 | `/fstack-plan` | Writes a one-page plan with a mandatory "what we're NOT doing" section. |
-| `/fstack-build` | Implements the plan one small step at a time, asking at real choices. |
-| `/fstack-simplify` | Audits for unnecessary complexity and proposes deletions — one file or the whole codebase. Only deletions. |
-| `/fstack-design` | Makes UI adhere to the project's existing styles and cleans up design slop. |
-| `/fstack-document` | Writes docs/ for the project, ELI5 to deep. Run again to update them with changes. |
-| `/fstack-check` | Three questions: does it work, does it match the plan, is it simple. |
-| `/fstack-learn` | Captures one lesson in three lines, so future sessions start smarter. |
-| `/fstack-push` | Commits the current task's changes and pushes to the remote. Nothing else — no tests, no deploy. |
+| `/fstack-build` | Implements an approved plan in small verified steps. |
+| `/fstack-simplify` | Audits unnecessary complexity and proposes deletions only. |
+| `/fstack-design` | Makes UI follow the project's existing visual system. |
+| `/fstack-document` | Writes or updates project documentation from ELI5 to deep. |
+| `/fstack-check` | Reviews whether work functions, matches the plan, and stays simple. |
+| `/fstack-learn` | Captures one non-obvious lesson in three lines. |
+| `/fstack-push` | Commits task-owned changes and pushes them. It intentionally does not test or deploy. |
+
+## Repository support for cloud agents
+
+This fork includes:
+
+- `AGENTS.md` — canonical repository-wide agent contract;
+- `CLAUDE.md` — Claude Code entrypoint;
+- `.github/copilot-instructions.md` — GitHub Copilot coding-agent entrypoint;
+- `.github/workflows/validate.yml` — automatic skill validation;
+- `.github/pull_request_template.md` — evidence-focused delivery checklist;
+- `scripts/validate.sh` — dependency-free frontmatter, naming, size, duplication, and README checks;
+- `docs/CLOUD_AGENTS.md` — complete operator guide.
+
+Validate locally with:
+
+```sh
+sh -n scripts/validate.sh
+sh scripts/validate.sh
+git diff --check
+```
+
+With GitHub CLI 2.90 or later, run the current Agent Skills publishing checks without publishing:
+
+```sh
+gh skill publish --dry-run
+```
 
 ## Philosophy
 
 1. Short sentences. One idea per sentence.
 2. Short paragraphs, then a blank line.
-3. No jargon. If a plumber wouldn't understand the word, find a simpler one.
-4. No personas. Skills describe steps, not characters.
+3. Plain language before jargon.
+4. No personas. Skills describe actions, not characters.
 5. One job per skill.
-6. Prefer deletion. When something can be shorter, make it shorter.
-7. Every skill fits in ~150 lines. If it doesn't, it's doing too much.
-8. The human drives. Skills pause at decision points and ask.
-9. Agent-agnostic. Plain markdown, no hardcoded tool names.
-10. Plain-English tone. Like explaining to a friend.
+6. Prefer deletion and the smallest complete change.
+7. Keep each skill compact; move real detail into referenced files only when needed.
+8. Interactive skills stop at decision points. The cloud runner continues through ordinary choices.
+9. Stay agent-agnostic and use the open `SKILL.md` format.
+10. Evidence beats confidence. Unrun tests are missing evidence, not a pass.
+11. Preserve unrelated work. Never make destructive Git behavior an automation default.
+12. A cloud run is done only after implementation, verification, review, and durable delivery.
 
 ## Credits
 
-fstack exists because of the stacks it distills. [gstack](https://github.com/garrytan/gstack) by Garry Tan gave it the full lifecycle idea and, through office hours, the idea-roasting step. [pstack](https://cursor.com/marketplace/cursor/pstack) by Lauren Tan gave it design-before-code and blast-radius thinking. [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) by Every gave it the plan artifact and the lesson-capture step. [Matt Pocock's skills](https://github.com/mattpocock/skills) gave it grilling, the two-axis review, and the small-skills shape. [counselors](https://github.com/aarondfrancis/fstack-counselors) by Aaron Francis gave it the council-of-advisors pattern behind `/fstack-counselors`. Go look at all of them — they're generous, thoughtful work.
+fstack exists because of the stacks it distills. [gstack](https://github.com/garrytan/gstack) by Garry Tan gave it the full lifecycle idea and idea-roasting step. [pstack](https://cursor.com/marketplace/cursor/pstack) by Lauren Tan gave it design-before-code and blast-radius thinking. [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) by Every gave it the plan artifact and lesson-capture step. [Matt Pocock's skills](https://github.com/mattpocock/skills) gave it grilling, two-axis review, and the small-skills shape. [counselors](https://github.com/aarondfrancis/fstack-counselors) by Aaron Francis gave it the independent-advisor pattern behind `/fstack-counselors`.
+
+The original fstack was created by [Flavio Copes](https://github.com/flaviocopes/fstack). This fork keeps the interactive stack and adds the continuous cloud-agent operating mode.
 
 ## License