Building Packs

Overview

Packs are Greentic’s distribution unit for application logic, extension logic, flows, components, and assets. Create them through gtc wizard first. The wizard delegates to greentic-pack, and the pack wizard can in turn delegate to greentic-flow and greentic-component, so pack metadata, flow edits, component scaffolding, assets, capability declarations, doctor checks, and optional build/sign steps live in one replayable JSON workflow.

Use direct developer passthroughs such as gtc dev pack build --in ... only after the wizard has created the pack or when you are doing a narrow maintenance task.

Create with gtc wizard

Run the interactive launcher when you are exploring:

gtc wizard

Choose the pack workflow from the launcher. For automation and coding agents, start with the live schema:

gtc wizard --schema

gtc wizard --schema returns the launcher schema and embeds the delegated pack schema. For pack work, set answers.selected_action to pack and place a greentic-pack.wizard.answers document in answers.delegate_answer_document.

Note

Running gtc wizard --dry-run --non-interactive --yes without an answers file is not enough. The launcher requires interactive input, or an AnswerDocument passed with --answers, validate, or apply.

AnswerDocument Shape

Use this shape when you want the top-level gtc wizard launcher to delegate into the pack wizard:

pack-create-answers.json

{
  "wizard_id": "greentic-dev.wizard.launcher.main",
  "schema_id": "greentic-dev.launcher.main",
  "schema_version": "1.0.0",
  "locale": "en",
  "answers": {
    "selected_action": "pack",
    "delegate_answer_document": {
      "wizard_id": "greentic-pack.wizard.run",
      "schema_id": "greentic-pack.wizard.answers",
      "schema_version": "1.0.0",
      "answers": {
        "pack_dir": "./packs/research-assistant",
        "mode": "create",
        "create_pack_id": "research-assistant",
        "create_pack_scaffold": true,
        "run_doctor": true,
        "run_build": false,
        "sign": false
      }
    }
  }
}

Validate the AnswerDocument and preview the plan before writing files:

gtc wizard validate --answers pack-create-answers.json
gtc wizard --answers pack-create-answers.json --dry-run --yes --non-interactive

Apply it when the plan is correct:

gtc wizard apply --answers pack-create-answers.json --yes --non-interactive

The pack wizard can delegate to flow and component wizards. Use these fields inside the nested pack AnswerDocument when needed:

Field	Purpose
asset_staging	Copy files or directories into the pack before validation/build steps run.
flow_wizard_answers	Add, update, or delete flows and steps through the embedded greentic-flow plan schema.
component_wizard_answers	Create or update WASM component projects through the embedded greentic-component schema.
run_delegate_flow	Run the nested flow wizard step.
run_delegate_component	Run the nested component wizard step.
run_doctor	Run pack validation from the wizard workflow.
run_build	Build the pack from the wizard workflow.
sign and sign_key_path	Sign the pack after building.

Nested Flow and Component Work

Use gtc wizard --schema as the starting point when an agent is creating the entire pack. For lower-level contracts, inspect the delegated schemas before composing the nested answers:

gtc dev pack wizard run --schema
gtc dev flow wizard --help
gtc dev component wizard --help

For component-backed flow steps, fetch the exact step-answer schema from the component before writing flow_wizard_answers:

gtc dev flow component-schema <component-ref> --mode default

This keeps the pack creation workflow schema-aware. The coding agent writes JSON answers, gtc wizard validate catches contract drift, and gtc wizard apply performs the actual pack, flow, and component mutations.

Direct Pack Commands

The local gtc dev pack --help command exposes these pack operations:

Command	Purpose
build	Build a pack component and supporting artifacts
lint	Lint a pack manifest, flows, and templates
components	Sync pack.yaml components with files under components/
update	Sync pack.yaml components and flows with files under the pack root
new	Scaffold a new pack directory
sign	Sign a pack manifest using an Ed25519 private key
verify	Verify a pack manifest signature
gui	GUI-related pack tooling
doctor	Diagnose a pack archive or source directory
inspect	Deprecated alias for doctor
inspect-lock	Inspect pack.lock.cbor as stable JSON
qa	Run component QA and store answers
config	Inspect resolved configuration, provenance, and warnings
info	Describe a .gtpack archive
plan	Generate a deployment plan from a pack archive or source directory
providers	Legacy provider-extension helpers
add-extension	Add extension data to a pack; provider extension path is legacy/schema-core
resolve	Resolve component references and write pack.lock.cbor
wizard	Pack wizard helpers

Run gtc dev pack <command> --help before scripting a direct command in CI. These commands are useful for validation, inspection, and maintenance, but pack creation should stay in the wizard workflow whenever possible.

Build After Wizard Creation

Prefer run_build: true in the pack wizard when the build should be part of a replayable creation/update workflow. For an existing pack source directory, build with:

gtc dev pack build --in ./packs/research-assistant

Validate the source directory or generated archive:

gtc dev pack doctor --in ./packs/research-assistant
gtc dev pack info ./dist/research-assistant.gtpack

gtc dev pack info supports human and JSON output:

gtc dev pack info ./dist/research-assistant.gtpack --format json

Flow Validation

Prefer run_doctor: true in the pack wizard. For standalone checks, use gtc dev flow doctor; it delegates to greentic-flow doctor and accepts flow files or directories.

# Validate all flows in a directory
gtc dev flow doctor ./my-pack/flows/

# Validate a specific flow
gtc dev flow doctor ./my-pack/flows/main.ygtc

# Emit machine-readable diagnostics for one flow
gtc dev flow doctor ./my-pack/flows/main.ygtc --json

Component Work

Components are WASM components. Create and maintain them through the pack wizard’s component_wizard_answers or the component wizard directly. Coding agents should use the wizard schema and answers workflow instead of hand-writing every manifest and binding:

gtc dev pack wizard run --schema
gtc dev component wizard --help
gtc dev component new --help
gtc dev component build --help
gtc dev component doctor --help

Signing and Verification

The pack CLI includes sign and verify commands:

gtc dev pack sign --help
gtc dev pack verify --help

Attention

Use the installed command help when wiring signing into automation. The current local binary exposes the signing commands, but the exact key and archive flags should be taken from gtc dev pack sign --help and gtc dev pack verify --help for the toolchain you are running.

CI/CD Example

.github/workflows/pack.yml

name: Build Pack

on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@1.95.0

      - name: Install GTC
        run: |
          cargo install cargo-binstall
          cargo binstall gtc
          gtc install
          gtc doctor

      - name: Build pack
        run: gtc dev pack build --in ./packs/research-assistant

      - name: Validate pack
        run: gtc dev pack doctor --in ./packs/research-assistant

Next Steps

• Pack Format Reference - Complete specification
• Flow Schema Reference - YAML flow schema
• Components Guide - Building WASM components