Standard Library

std.CreateFile

Example

package:
    name: create

    tasks:
    - name: TemplateFile
        uses: std.CreateFile
        with:
          type: text
          filename: template.txt
          content: |
            This is a template file
            with multiple lines
            of text.

Consumes

Produces

Produces a std.FileSet parameter set containing a single file

Parameters

  • type - [Required] Specifies the filetype of the produced fileset

  • filename - [Required] Name of the file to produce

  • incdir - [Optional] If ‘true’, adds the output directory as an include directory

std.FileSet

Creates a ‘FileSet’ parameter set from a specification. This task is primarily used to build up list of files for processing by HDL compilation tools.

Example

package:
    name: fileset.example

    tasks:
    - name: rtlsrc
        uses: std.FileSet
        with:
          include: '*.v'
          base: 'src/rtl'
          type: 'verilogSource'

The example above finds all files with a .v extension in the src/rtl subdirectory of the task’s source directory. The task emits a FileSet parameter set having the filetype of verilogSource.

Consumes

None by default (consumes: none)

Produces

Produces a std.FileSet parameter set containing files matched by the parameter specification.

Parameters

  • type - [Required] Specifies the filetype of the produced fileset

  • base - [Optional] Base directory for the fileset. Defaults to the task’s source directory

  • include - [Required] Set of file patterns to include in the fileset. Glob patterns may be used

  • exclude - [Optional] Set of file patterns to exclude from the fileset. Glob patterns may be used

  • incdirs - [Optional] Set of include directories that consumers of the fileset must use

  • defines - [Optional] Set of pre-processor defines that consumers of the fileset must use

  • attributes - [Optional] Set of attributes to tag the fileset with (e.g., [‘uvm’, ‘testbench’])

Running Shell Commands

Shell commands are executed by specifying shell: bash (or another shell) and providing the command with run:. This is useful for running external tools, scripts, or commands that don’t have dedicated task implementations.

Example

package:
    name: exec.example

    tasks:
    - name: run_script
      shell: bash
      run: ./scripts/process_data.sh

    - name: inline_commands
      shell: bash
      run: |
        echo "Processing data..."
        ./scripts/process.sh
        echo "Done"

Shell Tasks

Shell tasks support all standard shells. Common options:

  • bash - Bourne Again Shell (most common)

  • sh - POSIX shell

  • python - Python interpreter

  • pytask - Python task with context (for custom tasks)

The run: field specifies the command or script to execute. For inline scripts, use YAML’s multi-line syntax (| or >).

std.SetEnv

Sets environment variables for use by downstream tasks. Supports glob pattern expansion for paths, making it easy to configure tool paths and directories.

Example

package:
    name: setenv.example

    tasks:
    - name: tool_env
      uses: std.SetEnv
      with:
        setenv:
          TOOL_HOME: /opt/tools/my_tool
          PYTHONPATH: "lib/python/site-packages"
        append_path:
          PATH: /opt/tools/my_tool/bin
        prepend_path:
          LD_LIBRARY_PATH: /opt/tools/my_tool/lib

Glob Expansion

Values containing glob patterns (*, ?, [...]) are expanded relative to the task’s source directory:

tasks:
- name: lib_paths
  uses: std.SetEnv
  with:
    setenv:
      MY_LIBS: "libs/*/lib"  # Expands to all lib dirs

If multiple paths match, they are joined with the platform path separator (: on Unix, ; on Windows).

Consumes

All inputs by default (consumes: all)

Produces

Produces a std.Env data item containing the environment variable mappings.

Parameters

  • setenv - [Optional] Map of environment variable names to values

  • append_path - [Optional] Map of environment variables to values that should be appended

  • prepend_path - [Optional] Map of environment variables to values that should be prepended

The append_path and prepend_path parameters automatically handle path separator logic for PATH-like environment variables.

std.SetFileType

Modifies the file type of input filesets. This is useful when you need to reinterpret files with a different type for different tools.

Example

package:
    name: setfiletype.example

    tasks:
    - name: verilog_files
      uses: std.FileSet
      with:
        include: "*.v"
        type: verilogSource

    - name: reinterpret
      uses: std.SetFileType
      needs: [verilog_files]
      with:
        filetype: systemVerilogSource

Consumes

Only std.FileSet data items (consumes: [{type: std.FileSet}])

Produces

Produces new std.FileSet data items with the updated file type.

Parameters

  • filetype - [Required] The new file type to assign to all consumed filesets

std.IncDirs

Extracts include directories from input filesets and produces them as a structured list. This is useful for passing include paths to compilation tools.

Example

package:
    name: incdirs.example

    tasks:
    - name: rtl_files
      uses: std.FileSet
      with:
        include: "*.sv"
        incdirs:
          - include
          - rtl/include

    - name: extract_dirs
      uses: std.IncDirs
      needs: [rtl_files]

Consumes

std.FileSet data items

Produces

Produces a data item containing the collected include directories.

Parameters

None. The task operates entirely on input filesets.

std.Message

Displays a message during task execution. Useful for logging, debugging, and providing user feedback during flow execution.

Example

package:
    name: message.example

    tasks:
    - name: hello
      uses: std.Message
      with:
        msg: "Hello, World!"

    - name: status
      uses: std.Message
      with:
        msg: "Build completed successfully"
      needs: [build]

Consumes

All inputs by default (consumes: all)

Produces

Passes through all inputs. Does not produce additional data items.

Parameters

  • msg - [Optional] The message to display (default: empty string)

Messages support expression syntax for dynamic content:

package:
  name: example
  with:
    version:
      type: str
      value: "1.0"

  tasks:
  - name: version_msg
    uses: std.Message
    with:
      msg: "Building version ${{ version }}"

std.Agent

Executes an AI assistant with a specified prompt and collects structured results. The AI assistant must create a valid JSON result file or the task will fail with an error.

This task enables AI-assisted workflows for code generation, documentation, test creation, and other automated tasks that benefit from large language model capabilities.

Example

Basic usage:

package:
    name: agent.example

    tasks:
    - name: generate_code
      uses: std.Agent
      with:
        user_prompt: "Generate a Python function to parse CSV files"
        assistant: copilot

Custom system prompt:

package:
    name: agent.custom

    tasks:
    - name: generate_test
      uses: std.Agent
      with:
        system_prompt: |
          You are a test generation assistant.
          Input data: ${{ inputs }}

          Generate unit tests for the code and write results to ${{ result_file }}
          in JSON format with the following structure:
          {
            "status": 0,
            "changed": true,
            "output": [],
            "markers": []
          }
        user_prompt: "Create comprehensive unit tests"
        result_file: "tests.result.json"

Consumes

All inputs by default (consumes: all). Input data is available in the prompt via the ${{ inputs }} variable.

Produces

Outputs are determined by the AI assistant’s result JSON file. Typically produces std.FileSet items for generated files, but can produce any data type specified in the result.

Parameters

  • system_prompt - [Optional] System prompt template. Can include variable references:

    • ${{ inputs }} - JSON of input data from upstream tasks

    • ${{ name }} - Current task name

    • ${{ result_file }} - Expected result filename

    If empty, uses a default template that describes the expected JSON result format.

  • user_prompt - [Optional] User’s prompt content. This is appended to the system prompt with a “User Request:” header.

  • result_file - [Optional] Name of the JSON result file the AI must create (default: {name}.result.json). The task fails if this file is missing or contains invalid JSON.

  • assistant - [Optional] AI assistant to use. Options:

    • copilot - GitHub Copilot CLI (default)

    • openai - OpenAI API (not yet implemented)

    • claude - Claude API (not yet implemented)

  • assistant_config - [Optional] Map of assistant-specific configuration (e.g., API keys, model settings)

Required Result Format

The AI assistant must create a JSON file with the following structure:

{
  "status": 0,
  "changed": true,
  "output": [
    {
      "type": "std.FileSet",
      "filetype": "pythonSource",
      "basedir": ".",
      "files": ["generated.py"]
    }
  ],
  "markers": [
    {
      "msg": "Generated 1 file",
      "severity": "info"
    }
  ]
}

Fields:

  • status - Exit code (0 = success, non-zero = failure)

  • changed - Whether the task produced new/modified outputs

  • output - Array of output data items (e.g., FileSets)

  • markers - Array of diagnostic messages with severity levels

Error Handling

The Agent task uses strict validation:

  • Missing result file → Task fails with status=1

  • Invalid JSON syntax → Task fails with status=1

  • Result is not a JSON object → Task fails with status=1

  • Assistant not available → Task fails with status=1

  • Assistant execution fails → Task fails with assistant’s exit code

Debugging

When the Agent task runs, it creates several files in the task’s run directory:

  • {name}.prompt.txt - The complete prompt sent to the AI assistant

  • {name}.result.json - The structured result from the AI (if created)

  • assistant.stdout.log - Standard output from the AI assistant

  • assistant.stderr.log - Standard error from the AI assistant

These files are invaluable for debugging when the AI assistant doesn’t produce the expected result or when result parsing fails.

Setup Requirements

GitHub Copilot CLI

To use the default copilot assistant:

  1. Install GitHub CLI: https://cli.github.com/

  2. Install Copilot extension:

    gh extension install github/gh-copilot

  3. Authenticate:

    gh auth login

Other Assistants

OpenAI and Claude assistants are placeholders for future implementation. Contributions are welcome!