Skip to content

feat: optimize CLI output for AI agent consumption #944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stack72 merged 1 commit into from
Mar 30, 2026
Merged

feat: optimize CLI output for AI agent consumption #944

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions .claude/skills/issue-lifecycle/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ systeminit/swamp#850":

2. **Fetch the issue context**:
```
swamp model method run issue-<N> start --json
swamp model method run issue-<N> start
```

3. **Read the issue context** from the model output, then **read the codebase**:
Expand All @@ -49,7 +49,7 @@ systeminit/swamp#850":
swamp model method run issue-<N> triage \
--input type=<bug|feature|unclear> \
--input confidence=<high|medium|low> \
--input reasoning="<your analysis>" --json
--input reasoning="<your analysis>"
```

5. **Generate an implementation plan**:
Expand Down Expand Up @@ -85,7 +85,7 @@ systeminit/swamp#850":
--input summary="..." \
--input dddAnalysis="..." \
--input testingStrategy="..." \
--input-file /tmp/plan.yaml --json
--input-file /tmp/plan.yaml
```

6. **Check for documentation impact.** Before presenting the plan, evaluate
Expand Down Expand Up @@ -162,7 +162,7 @@ Then record them:

```
swamp model method run issue-<N> adversarial_review \
--input-file /tmp/findings.yaml --json
--input-file /tmp/findings.yaml
```

Each finding must have:
Expand Down Expand Up @@ -208,7 +208,7 @@ When the human gives feedback OR adversarial findings need addressing:
--input summary="..." \
--input dddAnalysis="..." \
--input testingStrategy="..." \
--input-file /tmp/plan.yaml --json
--input-file /tmp/plan.yaml
```

2. **Resolve addressed findings**. Write resolutions to a YAML file:
Expand All @@ -224,7 +224,7 @@ When the human gives feedback OR adversarial findings need addressing:

```
swamp model method run issue-<N> resolve_findings \
--input-file /tmp/resolutions.yaml --json
--input-file /tmp/resolutions.yaml
```

3. **Re-run adversarial review** on the new plan version. The review must be
Expand All @@ -242,7 +242,7 @@ When the human gives feedback OR adversarial findings need addressing:

6. Only then call `approve`:
```
swamp model method run issue-<N> approve --json
swamp model method run issue-<N> approve
```

**The `approve` method will fail** if critical/high findings are unresolved or
Expand All @@ -258,7 +258,7 @@ After plan approval, when the human says to implement:
3. **Record the PR number**:
```
swamp model method run issue-<N> implement \
--input prNumber=<N> --json
--input prNumber=<N>
```

4. **Wait 3 minutes for CI to start.** Use `sleep 180` — CI takes at least this
Expand All @@ -270,7 +270,7 @@ After plan approval, when the human says to implement:
during this wait — stay in the loop.

```
swamp model method run issue-<N> ci_status --json
swamp model method run issue-<N> ci_status
```

6. **Show the CI results** to the human, grouped by reviewer and severity:
Expand All @@ -281,7 +281,7 @@ After plan approval, when the human says to implement:
7. **If everything is green and approved**, the PR will auto-merge. Call
`complete` immediately — no need to ask the human:
```
swamp model method run issue-<N> complete --json
swamp model method run issue-<N> complete
```

8. **If there are failures or review comments**, present them and wait for the
Expand All @@ -295,7 +295,7 @@ After plan approval, when the human says to implement:
swamp model method run issue-<N> fix \
--input directive="<human's instruction>" \
--input targetReview="<reviewer>" \
--input targetSeverity="<severity>" --json
--input targetSeverity="<severity>"
```

9. **After pushing fixes, loop back to step 4.** Wait 3 minutes, poll for CI,
Expand All @@ -312,7 +312,7 @@ immediately — but it must be their decision, never yours.
To review a specific plan version:

```
swamp model method run issue-<N> review --input version=<V> --json
swamp model method run issue-<N> review --input version=<V>
```

To see all model data:
Expand Down
4 changes: 2 additions & 2 deletions .claude/skills/swamp-data/references/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ swamp data list <model-name> --json
swamp data get <model-name> <data-name> --json

# 3. Run the create method first
swamp model method run <model-name> create --json
swamp model method run <model-name> create
```

**CEL path anatomy**:
Expand Down Expand Up @@ -68,7 +68,7 @@ model.my-vpc.resource.vpc.main.attributes.VpcId
swamp model search --json

# Run a method to produce data
swamp model method run <model-name> <method> --json
swamp model method run <model-name> <method>

# Check if model input exists
swamp model get <model-name> --json
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/swamp-extension-driver/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,7 @@ After creating your driver:

```bash
rm -rf .swamp/driver-bundles/
swamp model method run my-instance run --json
swamp model method run my-instance run
```

If it still fails after clearing bundles, check for TypeScript errors in your
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/swamp-extension-model/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ than wrapping CLI commands.
| Check schema | `swamp model type describe @myorg/my-model --json` |
| Create instance | `swamp model create @myorg/my-model my-instance --json` |
| Create with args | `swamp model create @myorg/my-model inst --global-arg message=hi -j` |
| Run method | `swamp model method run my-instance run --json` |
| Run method | `swamp model method run my-instance run` |
| Next version | `swamp extension version @myorg/my-model --json` |
| Create manifest | Create `manifest.yaml` with model/workflow entries |
| Format extension | `swamp extension fmt manifest.yaml --json` |
Expand Down
8 changes: 4 additions & 4 deletions .claude/skills/swamp-extension-model/references/scenarios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ methods:
**4. Run and reference in other models**

```bash
swamp model method run my-customer create --json
swamp model method run my-customer create
```

```yaml
Expand Down Expand Up @@ -608,7 +608,7 @@ export const model = {

```bash
swamp model create @user/vpc-scanner my-scanner --json
swamp model method run my-scanner scan --json
swamp model method run my-scanner scan
```

**3. Query discovered VPCs**
Expand Down Expand Up @@ -752,10 +752,10 @@ swamp model edit my-script
# Add: methods.execute.arguments.run = "echo 'Hello'"

# Use the new audit method
swamp model method run my-script audit --json
swamp model method run my-script audit

# Use the new dryRun method
swamp model method run my-script dryRun --json
swamp model method run my-script dryRun
```

### Extension Rules
Expand Down
20 changes: 9 additions & 11 deletions .claude/skills/swamp-extension-model/references/smoke_testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,8 +49,8 @@ If any mismatch is found, fix the model source **before** proceeding to Phase 1.
- Connection errors or 500s = **stop**, API config is broken

```bash
swamp model method run <name> list --json
swamp model method run <name> list --arg resource_type=<type> --json
swamp model method run <name> list
swamp model method run <name> list --arg resource_type=<type>
```

### Phase 2: Read methods
Expand All @@ -59,7 +59,7 @@ swamp model method run <name> list --arg resource_type=<type> --json
- Verify response matches declared schema

```bash
swamp model method run <name> get --arg id=<id-from-list> --json
swamp model method run <name> get --arg id=<id-from-list>
```

### Phase 3: Create lifecycle
Expand All @@ -75,8 +75,7 @@ For each resource type supporting create:
```bash
swamp model method run <name> create \
--arg name=smoke-test-widget-1711100000 \
--arg <other-required-fields> \
--json
--arg <other-required-fields>
```

### Phase 4: Update lifecycle
Expand All @@ -87,8 +86,7 @@ swamp model method run <name> create \
```bash
swamp model method run <name> update \
--arg id=<created-id> \
--arg description="smoke test update" \
--json
--arg description="smoke test update"
```

### Phase 5: Delete / cleanup (ALWAYS runs)
Expand All @@ -99,9 +97,9 @@ swamp model method run <name> update \
- Verify deletion via read returning 404/not-found

```bash
swamp model method run <name> delete --arg id=<created-id> --json
swamp model method run <name> delete --arg id=<created-id>
# Verify deletion
swamp model method run <name> get --arg id=<created-id> --json
swamp model method run <name> get --arg id=<created-id>
```

### Phase 6: Report
Expand Down Expand Up @@ -208,8 +206,8 @@ or invalid fields. Update the model's create/update method to include them.
delete:

```bash
swamp model method run <name> update --arg id=<id> --arg delete_protected=false --json
swamp model method run <name> delete --arg id=<id> --json
swamp model method run <name> update --arg id=<id> --arg delete_protected=false
swamp model method run <name> delete --arg id=<id>
```

### Read-only resource guards (HTTP 405)
Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/swamp-extension-model/references/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,5 +250,5 @@ swamp model type describe @myorg/my-model --json

# Test the model
swamp model create @myorg/my-model test --set fieldName="test" --json
swamp model method run test methodName --json
swamp model method run test methodName
```
81 changes: 45 additions & 36 deletions .claude/skills/swamp-model/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,17 @@ description: >

# Swamp Model Skill

Work with swamp models through the CLI. All commands support `--json` for
machine-readable output.
Work with swamp models through the CLI.

## Output Modes

- **Execution** (`method run`): Use default log output. Results are persisted in
the datastore — use `report get --json` for structured detail (narrative,
schema, pointers) or `data get --json` for specific resources.
- **Retrieval** (`model get`, `data get`, `report get`, `output search`): Use
`--json` when you need structured data for action.
- **Mutation** (`model create`, `model delete`): Use `--json` to capture the
structured result.

## CRITICAL: Model Creation Rules

Expand All @@ -35,29 +44,29 @@ Correct flow: `swamp model create <type> <name> --json` → set global args with

## Quick Reference

| Task | Command |
| ------------------- | ------------------------------------------------------------------ |
| Search model types | `swamp model type search [query] --json` |
| Describe a type | `swamp model type describe <type> --json` |
| Create model input | `swamp model create <type> <name> --json` |
| Create with args | `swamp model create <type> <name> --global-arg key=value --json` |
| Search models | `swamp model search [query] --json` |
| Get model details | `swamp model get <id_or_name> --json` |
| Edit model input | `swamp model edit [id_or_name]` |
| Delete a model | `swamp model delete <id_or_name> --json` |
| Validate model | `swamp model validate [id_or_name] --json` |
| Validate by label | `swamp model validate [id_or_name] --label policy --json` |
| Validate by method | `swamp model validate [id_or_name] --method create --json` |
| Evaluate input(s) | `swamp model evaluate [id_or_name] --json` |
| Run a method | `swamp model method run <id_or_name> <method> --json` |
| Run with inputs | `swamp model method run <name> <method> --input key=value -j` |
| Skip all checks | `swamp model method run <name> <method> --skip-checks -j` |
| Skip check by name | `swamp model method run <name> <method> --skip-check <n> -j` |
| Skip check by label | `swamp model method run <name> <method> --skip-check-label <l> -j` |
| Search outputs | `swamp model output search [query] --json` |
| Get output details | `swamp model output get <output_or_model> --json` |
| View output logs | `swamp model output logs <output_id> --json` |
| View output data | `swamp model output data <output_id> --json` |
| Task | Command |
| ------------------- | ---------------------------------------------------------------- |
| Search model types | `swamp model type search [query] --json` |
| Describe a type | `swamp model type describe <type> --json` |
| Create model input | `swamp model create <type> <name> --json` |
| Create with args | `swamp model create <type> <name> --global-arg key=value --json` |
| Search models | `swamp model search [query] --json` |
| Get model details | `swamp model get <id_or_name> --json` |
| Edit model input | `swamp model edit [id_or_name]` |
| Delete a model | `swamp model delete <id_or_name> --json` |
| Validate model | `swamp model validate [id_or_name] --json` |
| Validate by label | `swamp model validate [id_or_name] --label policy --json` |
| Validate by method | `swamp model validate [id_or_name] --method create --json` |
| Evaluate input(s) | `swamp model evaluate [id_or_name] --json` |
| Run a method | `swamp model method run <id_or_name> <method>` |
| Run with inputs | `swamp model method run <name> <method> --input key=value` |
| Skip all checks | `swamp model method run <name> <method> --skip-checks` |
| Skip check by name | `swamp model method run <name> <method> --skip-check <n>` |
| Skip check by label | `swamp model method run <name> <method> --skip-check-label <l>` |
| Search outputs | `swamp model output search [query] --json` |
| Get output details | `swamp model output get <output_or_model> --json` |
| View output logs | `swamp model output logs <output_id> --json` |
| View output data | `swamp model output data <output_id> --json` |

## Repository Structure

Expand Down Expand Up @@ -376,16 +385,16 @@ swamp model evaluate --all --json
Execute a method on a model input.

```bash
swamp model method run my-shell execute --json
swamp model method run my-deploy create --input environment=prod --json
swamp model method run my-deploy create --input environment=prod --input replicas=3 --json
swamp model method run my-deploy create --input config.timeout=30 --json # dot notation for nesting
swamp model method run my-deploy create --input '{"environment": "prod"}' --json # JSON also supported
swamp model method run my-deploy create --input-file inputs.yaml --json
swamp model method run my-deploy create --last-evaluated --json
swamp model method run my-deploy create --skip-checks --json
swamp model method run my-deploy create --skip-check valid-region --json
swamp model method run my-deploy create --skip-check-label live --json
swamp model method run my-shell execute
swamp model method run my-deploy create --input environment=prod
swamp model method run my-deploy create --input environment=prod --input replicas=3
swamp model method run my-deploy create --input config.timeout=30 # dot notation for nesting
swamp model method run my-deploy create --input '{"environment": "prod"}' # JSON also supported
swamp model method run my-deploy create --input-file inputs.yaml
swamp model method run my-deploy create --last-evaluated
swamp model method run my-deploy create --skip-checks
swamp model method run my-deploy create --skip-check valid-region
swamp model method run my-deploy create --skip-check-label live
```

Pre-flight checks run automatically before mutating methods (`create`, `update`,
Expand Down Expand Up @@ -447,7 +456,7 @@ to inspect method execution results. See
7. **Check warnings** — if the validation output has non-empty `warnings`, stop
and ask the user before proceeding (see
[Handling Validation Warnings](#important-handling-validation-warnings))
8. **Run** the method: `swamp model method run my-shell execute --json`
8. **Run** the method: `swamp model method run my-shell execute`
9. **View** the output: `swamp model output get my-shell --json`

## Data Ownership
Expand Down
14 changes: 7 additions & 7 deletions .claude/skills/swamp-model/references/examples.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ methods:
**Step 3: Run and access output**

```bash
swamp model method run my-shell execute --json
swamp model method run my-shell execute
```

**Output data path**: `model.my-shell.resource.result.result.attributes.stdout`
Expand Down Expand Up @@ -107,7 +107,7 @@ methods:
```

```bash
swamp model method run vpc-lookup execute --json
swamp model method run vpc-lookup execute
```

**Step 2: Subnet Lookup (references VPC)**
Expand Down Expand Up @@ -190,19 +190,19 @@ methods:

```bash
# Key-value inputs (preferred for simple values)
swamp model method run my-deploy deploy --input environment=production --json
swamp model method run my-deploy deploy --input environment=production

# Multiple inputs
swamp model method run my-deploy deploy --input environment=production --input dryRun=true --json
swamp model method run my-deploy deploy --input environment=production --input dryRun=true

# Dot notation for nested values
swamp model method run my-deploy deploy --input config.timeout=30 --json
swamp model method run my-deploy deploy --input config.timeout=30

# JSON input (useful for complex structures)
swamp model method run my-deploy deploy --input '{"environment": "production"}' --json
swamp model method run my-deploy deploy --input '{"environment": "production"}'

# YAML file input
swamp model method run my-deploy deploy --input-file inputs.yaml --json
swamp model method run my-deploy deploy --input-file inputs.yaml
```

**Input file format (inputs.yaml)**:
Expand Down
Loading
Loading