feat: update SKILL.md with changes to block directives and execution behavior guidelines

Akagi201 · Akagi201 · commit 05d8d549152a · 2026-03-15T11:46:05.000+08:00
diff --git a/SKILL.md b/SKILL.md
@@ -114,7 +114,60 @@ pwd
 
 Why it is bad: the `cd /srv/app` line becomes part of every block, including remote blocks.
 
-## 4. Assume every block runs in a fresh shell
+## 4. Use block directives for timeout, retry, and exports
+
+Block directives must appear immediately after the `# @LOCAL` or `# @REMOTE <host>` marker, before any command lines. They configure execution behavior for that specific block.
+
+### Timeout Directive
+
+`# @TIMEOUT <seconds>` - Abort the block if it exceeds the specified duration.
+
+```bash
+# @LOCAL
+# @TIMEOUT 30
+sleep 60
+```
+
+### Retry Directive
+
+`# @RETRY <count>` - Retry the block up to N times on failure (0 means no retry).
+
+```bash
+# @LOCAL
+# @RETRY 3
+curl -f https://api.example.com/health
+```
+
+### Export Directive
+
+`# @EXPORT NAME=source` - Capture a value from the block result and pass it to subsequent blocks as an environment variable.
+
+Valid sources:
+
+- `stdout` - The block's standard output
+- `stderr` - The block's standard error
+- `output` - Combined stdout and stderr
+- `exit_code` - The block's exit code (as string)
+
+```bash
+# @LOCAL
+# @EXPORT BUILD_ID=stdout
+echo "build-$(date +%s)"
+
+# @LOCAL
+echo "Building: $BUILD_ID"
+```
+
+You can use multiple exports in a single block:
+
+```bash
+# @LOCAL
+# @EXPORT STATUS_CODE=exit_code
+# @EXPORT RESPONSE=stdout
+curl -s -w "%{http_code}" -o response.txt https://api.example.com
+```
+
+## 5. Assume every block runs in a fresh shell
 
 Each block is isolated.
 
@@ -158,7 +211,7 @@ pwd
 
 Why it is bad: `artifact` and the working directory do not persist.
 
-## 5. Use SHELLFLOW_LAST_OUTPUT for explicit handoff
+## 6. Use SHELLFLOW_LAST_OUTPUT for explicit handoff
 
 Shellflow passes the previous block's combined output into the next block as `SHELLFLOW_LAST_OUTPUT`.
 
@@ -197,7 +250,7 @@ print(payload["release"])
 PY
 ```
 
-## 6. Use SSH config host aliases, not ad-hoc targets
+## 7. Use SSH config host aliases, not ad-hoc targets
 
 `# @REMOTE <ssh-host>` should point to a host that resolves through SSH config.
 
@@ -210,7 +263,7 @@ Avoid assuming Shellflow accepts any arbitrary free-form destination unless it i
 
 If a remote host is unknown, Shellflow fails before execution.
 
-## 7. Keep blocks self-contained and fail-fast
+## 8. Keep blocks self-contained and fail-fast
 
 Shellflow runs blocks in order and stops on the first failure.
 
@@ -243,17 +296,69 @@ docker compose up -d
 
 Why: the second block cannot rely on the first block's `cd`.
 
+## 9. CLI Options and Output Modes
+
+Shellflow provides several CLI options for different use cases:
+
+### Basic Options
+
+```bash
+shellflow run script.sh              # Run a script
+shellflow run script.sh -v          # Run with verbose output
+shellflow run script.sh --dry-run   # Preview execution plan without running
+```
+
+### Structured Output
+
+```bash
+shellflow run script.sh --json       # Single JSON report
+shellflow run script.sh --jsonl       # Streaming JSON Lines events
+```
+
+- `--json`: Outputs a single JSON object with the complete run report
+- `--jsonl`: Outputs one JSON object per event (run_started, block_started, block_finished, run_finished)
+
+### Execution Control
+
+```bash
+shellflow run script.sh --no-input   # Non-interactive mode (stdin closed)
+shellflow run script.sh --ssh-config /path/to/config  # Custom SSH config
+```
+
+- `--no-input`: Closes stdin before running blocks; useful for automation
+- `--ssh-config`: Override the default SSH config path (`~/.ssh/config`)
+
+### Audit Logging
+
+```bash
+shellflow run script.sh --audit-log audit.jsonl --jsonl
+```
+
+The `--audit-log` option writes redacted JSON Lines events to a file. Secret-like exports (containing TOKEN, SECRET, or PASSWORD in the name) are automatically redacted to `[REDACTED]`.
+
+## 10. Exit Codes
+
+Shellflow returns distinct exit codes for different failure types:
+
+- `0`: Success
+- `1`: General execution failure
+- `2`: Parse failure (invalid script syntax)
+- `3`: SSH config failure (host not found)
+- `4`: Timeout failure (block exceeded timeout)
+
 ## Authoring Checklist
 
 Before returning a Shellflow playbook, verify that:
 
 - The script is valid bash without custom DSL syntax.
-- Only `# @LOCAL` and `# @REMOTE <host>` are used.
+- Only `# @LOCAL`, `# @REMOTE <host>`, and block directives (`# @TIMEOUT`, `# @RETRY`, `# @EXPORT`) are used.
+- Block directives appear immediately after the block marker, before any commands.
 - Anything before the first marker is safe to repeat for every block.
 - Every block can run independently in a fresh shell.
-- Cross-block data uses `SHELLFLOW_LAST_OUTPUT` explicitly.
+- Cross-block data uses `SHELLFLOW_LAST_OUTPUT` or `@EXPORT` explicitly.
 - Remote targets match the intended SSH host aliases.
 - Commands that should happen once are not accidentally placed in the shared prelude.
+- Export sources are valid (stdout, stderr, output, exit_code).
 
 ## Reference Example
 
@@ -266,27 +371,36 @@ log() {
 }
 
 # @LOCAL
+# @EXPORT BUILD_ID=stdout
 log "building artifact"
-artifact="$(mktemp /tmp/shellflow-release.XXXXXX)"
-printf 'release-%s\n' "$(date +%Y%m%d%H%M%S)" > "$artifact"
-echo "$artifact"
+build_id="build-$(date +%Y%m%d%H%M%S)"
+echo "$build_id"
+
+# @LOCAL
+# @TIMEOUT 60
+# @RETRY 2
+log "deploying to staging"
+echo "Deploying $BUILD_ID to staging"
 
 # @REMOTE staging
-cd /srv/app
-artifact_path="$SHELLFLOW_LAST_OUTPUT"
-log "receiving artifact path $artifact_path"
-test -n "$artifact_path"
-uname -a
+# @EXPORT DEPLOYED_HOST=stdout
+log "receiving deployment"
+hostname
 
 # @LOCAL
-log "remote said: $SHELLFLOW_LAST_OUTPUT"
+log "deployed to: $DEPLOYED_HOST"
+log "build $BUILD_ID complete"
 ```
 
 ## Common Mistakes
 
 - Putting one-time commands before the first marker, then being surprised when they run for every block.
 - Expecting `cd`, `export`, or local shell variables from one block to exist in the next block.
 - Using an undefined remote host alias.
-- Printing extra debug output from a block whose output is consumed by the next block.
+- Placing block directives after commands instead of immediately after the marker.
+- Using invalid export sources (not stdout, stderr, output, or exit_code).
+- Forgetting that `@RETRY 0` means no retry attempts.
+- Using `@TIMEOUT` with values too small for normal operation.
+- Printing extra debug output from a block whose output is consumed by the next block via `@EXPORT`.
 - Forgetting to quote `"$SHELLFLOW_LAST_OUTPUT"`.
 - Treating Shellflow as a persistent session instead of sequential isolated shells.
diff --git a/playbooks/hello.sh b/playbooks/hello.sh
@@ -1,8 +1,89 @@
 #!/bin/bash
 set -euo pipefail
 
+log() {
+  printf '[hello] %s\n' "$*"
+}
+
+log "Shellflow Feature Demo"
+
+# Block 1: Local execution with timeout, retry, and export
+# Demonstrates: @TIMEOUT, @RETRY, @EXPORT, SHELLFLOW_LAST_OUTPUT
+# @LOCAL
+# @TIMEOUT 30
+# @RETRY 1
+# @EXPORT GREETING=stdout
+log "block 1: local with export"
+echo "Hello from Shellflow!"
+
+# Block 2: Local execution reading exported variable
+# Demonstrates: reading exported env vars
+# @LOCAL
+log "block 2: using exported variable"
+echo "Received: $GREETING"
+
+# Block 3: Local execution with SHELLFLOW_LAST_OUTPUT
+# Demonstrates: SHELLFLOW_LAST_OUTPUT handoff
+# @LOCAL
+log "block 3: passing data via SHELLFLOW_LAST_OUTPUT"
+echo "Data from block 2"
+
+# Block 4: Local reading SHELLFLOW_LAST_OUTPUT
+# Demonstrates: SHELLFLOW_LAST_OUTPUT
+# @LOCAL
+log "block 4: reading SHELLFLOW_LAST_OUTPUT"
+echo "Previous output: $SHELLFLOW_LAST_OUTPUT"
+
+# Block 5: Export exit_code
+# Demonstrates: @EXPORT with exit_code source
+# @LOCAL
+# @EXPORT COMMAND_STATUS=exit_code
+log "block 5: export exit_code"
+true
+
+# Block 6: Using exported exit_code
+# @LOCAL
+log "block 6: previous exit code was $COMMAND_STATUS"
+
+# Block 7: Export stderr
+# Demonstrates: @EXPORT with stderr source
+# @LOCAL
+# @EXPORT ERROR_OUTPUT=stderr
+log "block 7: exporting stderr"
+echo "normal output" >&2
+
+# Block 8: Using exported stderr
+# @LOCAL
+log "block 8: stderr was: $ERROR_OUTPUT"
+
+# Block 9: Export combined output
+# Demonstrates: @EXPORT with output source
+# @LOCAL
+# @EXPORT COMBINED=output
+log "block 9: exporting combined output"
+echo "stdout line"
+echo "stderr line" >&2
+
+# Block 10: Using exported combined output
 # @LOCAL
-echo "runs with the shared prelude"
+log "block 10: combined output:"
+echo "$COMBINED"
 
+# Block 11: Retry demonstration (will succeed on first try)
+# Demonstrates: @RETRY with successful execution
+# @LOCAL
+# @RETRY 3
+log "block 11: retry demo (succeeds)"
+echo "Retry successful!"
+
+# Block 12: Remote execution demonstration (requires SSH config)
+# Demonstrates: @REMOTE for remote execution
 # @REMOTE sui
 uname -a
+
+# Block 12: Final block
+# @LOCAL
+log "block 12: demo complete!"
+echo "All Shellflow features demonstrated."
+
+
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "shellflow"
-version = "0.1.1"
+version = "0.2.0"
 description = "A minimal shell script orchestrator with SSH support"
 readme = "README.md"
 license = "Apache-2.0"
diff --git a/uv.lock b/uv.lock
