documenting action spec

packs/examples/README.md

@@ -0,0 +1,106 @@
+# Examples Pack
+
+**Demonstration actions and workflows for learning Attune**
+
+## Overview
+
+The Examples pack provides reference implementations that demonstrate various Attune features and best practices. These examples are designed for learning and can be used as templates for building your own actions.
+
+## Contents
+
+### Actions
+
+#### `list_example` - JSON Lines Output Demo
+
+Demonstrates the JSON Lines (JSONL) output format for streaming results.
+
+**Features:**
+- Streams multiple JSON objects as output
+- Each line is a separate JSON object
+- Results are collected into an array
+- Useful for processing lists or progress updates
+
+**Usage:**
+```bash
+attune action execute examples.list_example --param count=10
+```
+
+**Parameters:**
+- `count` (integer): Number of items to generate (default: 5, range: 1-100)
+
+**Output Format:** JSONL - Each line is parsed as JSON and collected into an array
+
+**Example Output:**
+```json
+[
+  {"id": 0, "value": "item-0", "timestamp": "2024-01-20T10:30:00Z"},
+  {"id": 1, "value": "item-1", "timestamp": "2024-01-20T10:30:01Z"},
+  {"id": 2, "value": "item-2", "timestamp": "2024-01-20T10:30:02Z"}
+]
+```
+
+## Use Cases
+
+### Learning Attune
+- Study action structure and metadata
+- Understand parameter schemas
+- Learn about different output formats
+- See working implementations
+
+### Templates
+- Copy and modify examples for your own actions
+- Reference implementations for common patterns
+- Starting point for new packs
+
+## Installation
+
+The examples pack is not installed by default but can be easily added:
+
+```bash
+# Via pack registry (if published)
+attune pack install examples
+
+# Via local directory
+attune pack install --local ./packs/examples
+```
+
+## Development
+
+### Adding New Examples
+
+When adding new example actions:
+
+1. Create action metadata in `actions/<name>.yaml`
+2. Implement the action script in `actions/<name>.sh` (or .py, .js)
+3. Use ref format: `examples.<action_name>`
+4. Add documentation to this README
+5. Include clear comments in the code
+6. Demonstrate a specific feature or pattern
+
+### Guidelines
+
+- **Keep it simple** - Examples should be easy to understand
+- **One concept per example** - Focus on demonstrating one feature clearly
+- **Well-commented** - Explain what the code does and why
+- **Self-contained** - Minimize external dependencies
+- **Documented** - Update this README with usage examples
+
+## Related Documentation
+
+- [Action Development Guide](../../docs/action-development-guide.md)
+- [Pack Structure](../../docs/packs/pack-structure.md)
+- [Parameter Configuration](../../docs/action-development-guide.md#parameter-configuration)
+- [Output Formats](../../docs/action-development-guide.md#output-configuration)
+
+## Contributing
+
+Have an idea for a useful example? Contributions are welcome! Please ensure:
+
+- Examples are educational and demonstrate best practices
+- Code is well-commented and easy to follow
+- Documentation is updated
+- Examples are tested and working
+
+## License
+
+This pack is part of the Attune project and follows the same license terms.

packs/examples/actions/list_example.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# List Example Action
+# Demonstrates JSON Lines output format for streaming results
+
+set -euo pipefail
+
+# Read parameters from stdin (JSON format)
+read -r params_json
+
+# Extract count parameter (default to 5 if not provided)
+count=$(echo "$params_json" | jq -r '.count // 5')
+
+# Generate JSON Lines output (one JSON object per line)
+for i in $(seq 1 "$count"); do
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "{\"id\": $i, \"value\": \"item_$i\", \"timestamp\": \"$timestamp\"}"
+done

packs/examples/actions/list_example.yaml

@@ -0,0 +1,58 @@
+# List Example Action
+# Demonstrates JSON Lines output format for streaming results
+
+ref: examples.list_example
+label: "List Example"
+description: "Example action that outputs multiple JSON objects as JSON Lines"
+enabled: true
+
+# Runner type determines how the action is executed
+runner_type: shell
+
+# Entry point is the shell script to execute
+entry_point: list_example.sh
+
+# Parameter delivery: stdin for secure parameter passing
+parameter_delivery: stdin
+parameter_format: json
+
+# Output format: jsonl (each line is a JSON object, collected into array)
+output_format: jsonl
+
+# Action parameters schema (standard JSON Schema format)
+parameters:
+  type: object
+  properties:
+    count:
+      type: integer
+      description: "Number of items to generate"
+      default: 5
+      minimum: 1
+      maximum: 100
+
+# Output schema: array of objects (required for jsonl format)
+# Each line in stdout will be parsed as JSON and collected into this array
+output_schema:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: integer
+        description: "Item identifier"
+      value:
+        type: string
+        description: "Item value"
+      timestamp:
+        type: string
+        description: "ISO 8601 timestamp"
+    required:
+      - id
+      - value
+
+# Tags for categorization
+tags:
+  - utility
+  - example
+  - jsonl
+  - streaming

packs/examples/pack.yaml

@@ -0,0 +1,54 @@
+# Examples Pack
+# Demonstrates various Attune features and patterns
+
+ref: examples
+label: "Examples Pack"
+description: "Example actions and workflows demonstrating Attune capabilities"
+version: "1.0.0"
+author: "Attune Team"
+email: "support@attune.io"
+
+# System pack flag
+system: false
+enabled: true
+
+# Configuration schema
+conf_schema:
+  type: object
+  properties:
+    example_setting:
+      type: string
+      description: "Example configuration setting"
+      default: "default_value"
+
+# Default pack configuration
+config:
+  example_setting: "default_value"
+
+# Pack metadata
+meta:
+  category: "examples"
+  keywords:
+    - "examples"
+    - "demos"
+    - "tutorials"
+    - "learning"
+  documentation_url: "https://docs.attune.io/packs/examples"
+  repository_url: "https://github.com/attune/attune"
+  description: |
+    The Examples pack provides reference implementations and demonstrations
+    of Attune features including:
+
+    - JSON Lines (JSONL) output format for streaming results
+    - Various parameter delivery methods
+    - Different output formats
+    - Best practices for action development
+
+# Tags for categorization
+tags:
+  - examples
+  - demos
+  - documentation
+
+# Runtime dependencies (none for examples)
+runtime_deps: []