Skip to content

lasp/adamant-skills / adamant-tools

adamant-tools

Verified

FileKindSize
SKILL.mdskill md8.0 KB
adamant_env.shexecutablescript2.5 KB
adamant_inspect.pyscript22.4 KB
adamant_scaffold.pyscript25.3 KB
adamant_style_check.pyexecutablescript12.4 KB
adamant_validate_yaml.pyscript15.8 KB
# adamant-tools

Development tools for Adamant component workflows. Three standalone Python scripts that require no Docker or build environment (except `adamant_inspect` which reads generated files).

## Tools

### adamant_inspect.py -- Generated API Extractor

**Purpose:** After `redo` generates a component, extract a concise summary of the generated API: connectors, methods to override, helpers to call, events, data products, commands, parameters, faults, data dependencies, and tester histories.

**When to use:** After first successful `redo` build of a component, before writing the implementation body or test body. Eliminates guessing at generated method names, parameter types, and tester API.

```
python3 adamant_inspect.py <component_dir>

# Example:
python3 adamant_inspect.py src/components/voltage_monitor
```

**Output sections:**
- INIT PARAMETERS -- `Init` procedure signature
- SET_ID_BASES -- which ID bases the component requires
- RECV CONNECTORS -- abstract procedures to override (handler implementations)
- SEND/GET/REQUEST CONNECTORS -- helper procedures/functions to call
- DROPPED HANDLERS -- abstract null procedures for each send connector
- DATA DEPENDENCY HELPERS -- private `Get_*` functions for data deps
- DATA DEPENDENCY ABSTRACTS -- `Get_Data_Dependency` and `Invalid_Data_Dependency`
- INSTANCE FIELDS -- `Self.*` record fields (Events, Data_Products, Faults, etc.)
- EVENTS/DATA_PRODUCTS/COMMANDS/FAULTS -- creation function signatures
- PARAMETERS -- table fields and `Validate_Parameters` signature
- TESTER API -- typed history names, connector histories, override fields

**Key value:** The #1 cold-start error is guessing at generated API names. This tool provides the exact signatures.

### adamant_scaffold.py -- Component Scaffolder

**Purpose:** Generate all YAML models, implementation stubs (.ads/.adb), and test infrastructure (tests.yaml, env.py) from a spec file.

**When to use:** Starting a new component. Write a simple YAML spec describing what the component needs, then scaffold generates all files.

```
python3 adamant_scaffold.py <spec_file.yaml> [output_dir]

# Example:
python3 adamant_scaffold.py watchdog_timer_spec.yaml
# Creates src/components/watchdog_timer/ with all files
```

**Spec file format:**
```yaml
name: watchdog_timer
description: Monitors heartbeats and triggers timeout faults
execution: passive
init:
  - name: Timeout_Ms
    type: Unsigned_32
    description: Timeout period in milliseconds
connectors:
  recv_sync:
    - type: Tick.T
      description: Periodic check
  send:
    - type: Event.T
      description: Event output
    - type: Data_Product.T
      description: Data product output
  get:
    - type: Sys_Time.T
      description: System time
events:
  - name: Heartbeat_Received
    description: Valid heartbeat detected
  - name: Timeout_Triggered
    description: Heartbeat timeout detected
    param_type: Packed_U32.T
data_products:
  - name: Heartbeat_Count
    type: Packed_U32.T
    description: Total heartbeats received
commands:
  - name: Reset
    description: Reset the watchdog timer
faults:
  - name: Heartbeat_Timeout
    description: No heartbeat within timeout period
parameters:
  description: Configurable parameters
  items:
    - name: Timeout_Threshold
      type: Packed_U32.T
      default: "5000"
      description: Timeout in milliseconds
data_dependencies:
  description: External data dependencies
  items:
    - name: System_Health
      type: Packed_Boolean.T
      description: Overall system health status
```

**Generated files:**
- `<name>.component.yaml` -- main component model
- `<name>.events.yaml` -- event definitions (if events specified)
- `<name>.data_products.yaml` -- data product definitions (if DPs specified)
- `<name>.commands.yaml` -- command definitions (if commands specified)
- `<name>.parameters.yaml` -- parameter definitions (if parameters specified)
- `<name>.faults.yaml` -- fault definitions (if faults specified)
- `<name>.data_dependencies.yaml` -- data dependency definitions (if data deps specified)
- `component-<name>-implementation.ads` -- implementation spec stub
- `component-<name>-implementation.adb` -- implementation body stub with TODO markers
- `test/<name>.tests.yaml` -- test configuration
- `test/env.py` -- test environment

**After scaffolding:**
1. Review and edit generated files (fill in TODOs)
2. `admt build <component_dir>/build/src/component-<name>.ads` (generate base class)
3. Run `adamant_inspect.py` to see the full generated API
4. `admt build <component_dir>/test/build/template/` (generate test templates) -- or use `admt templates <component_dir>` which runs this plus the stub copy
5. `cp <component_dir>/test/build/template/*.ads <component_dir>/test/`  (skipped when `admt templates` handles the copy)
6. Write test body, then `cd test && admt test`

### adamant_validate_yaml.py -- YAML Pre-flight Checker

**Purpose:** Fast structural validation of component YAML files without Docker. Catches the errors that most commonly cause build failures.

**When to use:** After writing or editing YAML files, before running `admt build`. Saves a Docker round-trip per error.

```
python3 adamant_validate_yaml.py <component_dir>

# Example:
python3 adamant_validate_yaml.py src/components/voltage_monitor
```

**What it checks:**
- Required fields in component YAML (description, execution, connector types/kinds)
- Framework component name collisions (58 known names)
- Init parameter structure and string defaults
- Feature YAML field names (`param_type` not `type` for events, `arg_type` not `type` for commands)
- Cross-file consistency (feature YAML exists but matching connector missing)
- File naming conventions (implementation spec/body, test directory structure)
- Test directory rules (env.py content, no .all_path in test dirs)

**What it does NOT check:**
- Full JSON Schema validation (requires Adamant Python environment)
- Ada compilation correctness
- Connector count or wiring validity

## Integration with Skills

These tools complement the existing skills:
- **adamant-component-dev**: Use `adamant_scaffold` to create files, `adamant_validate_yaml` before building
- **adamant-testing**: Use `adamant_inspect` after first build to see tester API before writing tests
- **adamant-build-system**: Tools run outside Docker; `admt` (and the underlying `redo`) handle all in-container code generation

## Environment Caching

admt owns a cached environment snapshot per registered project (`/tmp/admt/<project>/env_snapshot.sh` + `exec.sh`) and restores it in milliseconds on every call. The legacy `adamant_env.sh` wrapper still provides its own `/tmp/.<project>_env_snapshot` as a fallback.

```bash
# Run any in-container command through admt (snapshot-cached):
admt env exec "python3 /tmp/adamant_validate_yaml.py src/components/foo"

# Force snapshot regeneration after container recreation:
admt env refresh
```

**Sub-agent workflow pattern:**
```bash
# Step 1: Copy tools into container (once per container start)
docker cp adamant-tools/*.py <project>_container:/tmp/

# Step 2: Validate YAML (uses pykwalify if SCHEMAPATH set)
admt env exec "python3 /tmp/adamant_validate_yaml.py $COMP_DIR"

# Step 3: Build component
admt build $COMP_DIR/build/src/component-$NAME.ads

# Step 4: Inspect generated API
admt env exec "python3 /tmp/adamant_inspect.py $COMP_DIR"

# Step 5: Build and test
admt test $COMP_DIR/test
```

Fallback form (when admt is not applicable):

```bash
bash <project_dir>/docker/adamant_env.sh exec "python3 /tmp/adamant_validate_yaml.py src/components/foo"
```

## pykwalify Schema Validation

Inside Docker (with `source activate`), the validator automatically uses Adamant's real pykwalify schemas from `$SCHEMAPATH`. This catches all YAML structural errors authoritatively -- no heuristic guessing.

Outside Docker, the validator falls back to heuristic checks (field names, connector consistency, naming conventions). These catch the most common errors but are not exhaustive.

## Location

Tools are in the `adamant-tools/` directory of the skills repository. Copy into Docker containers or run from the host against mounted volumes.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall