Campfire #1: What Should the Gas City Role Format Look Like?

[Mnikley]

Campfire #1: What Should the Gas City Role Format Look Like?

Gas City wants to make agent roles declarative — describe what an agent does in a file, and the system figures out the rest. Think Dockerfile for agent behavior. The role format is the foundation (w-gc-001), so before anything gets built, let's talk about what it should look like.

Questions

1. Format: YAML, TOML, JSON, or something else?

• YAML is everywhere (K8s, GitHub Actions, CLAUDE.md)
• TOML is stricter, harder to mess up
• JSON is universal but verbose — no comments, lots of braces
• Something else?

2. What goes in a role definition?

Strawman:

role: code-reviewer
description: Reviews PRs for quality, security, and style

tools:
  - read
  - grep
  - glob
  - bash:read-only

context:
  - CONTRIBUTING.md
  - docs/style-guide.md

constraints:
  - never modify files
  - flag security issues as blocking
  - max response length: 2000 tokens

triggers:
  - on: pull_request
    action: review

What's missing? What's unnecessary? Should the system auto-discover well-known files (CONTRIBUTING.md, README.md) from both root and docs/, or should everything be explicit?

3. Composition: how do roles build on each other?

• Inheritance? (extends: base-reviewer)
• Mixins? (uses: [security-checks, style-checks])
• Keep roles flat and self-contained?

4. Runtime vs. static: where's the line?

• Should roles reference runtime values? e.g., context: ${repo.contributing_guide}
• Or keep everything static and let the system figure it out?

5. What existing formats feel right to you?

• CLAUDE.md, AGENTS.md
• Kubernetes manifests
• GitHub Actions workflows
• Ansible playbooks
• Something else?

How to participate

Reply with your takes on any of the above. One sentence per question is fine. Goal is to surface preferences and blind spots before committing to a design.