# Dagger Design Proposals

> Write design proposals for Dagger features. Use when asked to draft, review, or iterate on Dagger design documents, RFCs, or proposals. Use when this capability is needed.

- Skill: `tomevault-io/dagger-design-proposals` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/dagger-design-proposals`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dagger-design-proposals/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/dagger-design-proposals

---


# Dagger Design Proposals

Guidelines for writing design proposals for Dagger features.

## Before Writing

**Always research first:**

1. Check relevant internal docs, such as `internal-docs/dagger-codegen.md`, for context
2. Look at related code in the Dagger codebase:
   - GraphQL schema: `core/schema/*.go`
   - CLI commands: `cmd/dagger/*.go`
   - Core types: `core/*.go`
3. For public API or workspace proposals, read `internal-docs/version-gating.md`
4. Understand existing patterns before proposing new ones

## Structure

````markdown
# Part N: Title

*Builds on [Part N-1: Title](link)*

## Table of Contents
- [Problem](#problem)
- [Solution](#solution)
- [Core Concept](#core-concept)
- [CLI](#cli)
- [Status](#status)

## Problem

Numbered, concise limitations:

1. **Short title** - One sentence explanation.
2. **Short title** - One sentence explanation.

## Solution

One paragraph summary.

## Core Concept

GraphQL type definitions with inline docstrings:

```graphql
"""
Type description here.
"""
type Example {
  """Method description."""
  method(arg: String!): Result!
}
```

Go for implementation examples:

```go
func New(ws dagger.Workspace) *Example {
    // ...
}
```

## CLI

Real command examples:

```bash
$ dagger command --flag
OUTPUT
```

## Status

One line.

---

- Previous: [Part N-1](link)
- Next: [Part N+1](link) or "Part N+1: Title (coming soon)"

````

## Style

- **Concise** - Trust the reader. Remove fluff.
- **Tables** - Use for comparisons.
- **GraphQL for APIs** - Type definitions, not Go interfaces.
- **Go for implementation** - Examples showing how modules use the API.
- **Real examples** - go-toolchain, node-toolchain, not abstract Foo/Bar.
- **Less is more** - Remove sections when challenged.

## What to Avoid

- Separate "Methods" sections (use GraphQL docstrings)
- "Design Rationale" sections unless specifically valuable
- "Open Questions" that aren't real blockers
- Go for type definitions (use GraphQL)
- Layout examples that might confuse
- Over-explaining

## Process

1. **Gists as source of truth** - Publish early, iterate in gist
2. **Link parts together** - Previous/Next at bottom, "Builds on" at top
3. **Each part stands alone** - But builds on previous
4. **Iterate quickly** - User feedback drives changes

## Iterating with User

When you have clarifying questions or notes:

1. **List them first** - Present a high-level numbered list of all questions/notes
2. **One at a time** - Walk through each item individually, waiting for user response
3. **Don't dump** - Never present all questions with full details at once

## Codebase References

When writing proposals, reference actual Dagger code:

| Topic | Location |
|-------|----------|
| GraphQL schema definitions | `core/schema/*.go` |
| CLI commands | `cmd/dagger/*.go` |
| Core types (Directory, File, etc.) | `core/*.go` |
| Engine internals | `engine/*.go` |
| SDK codegen | `internal-docs/dagger-codegen.md`, `cmd/codegen/*.go` |
| API version gates | `internal-docs/version-gating.md`, `core/schema/*.go` |

Example: To understand how `Host.findUp` works before proposing `Workspace.findUp`:

```bash
# Find the schema definition
grep -r "findUp" core/schema/host.go

# Find the implementation
grep -r "FindUp" core/host.go
```

## Publishing

```bash
# Create new gist
gh gist create file.md --desc "Dagger Design: Part N - Title" --public

# Update existing gist
gh gist edit GIST_ID file.md

# Post changelog comment (always do this after updates)
gh api --method POST /gists/GIST_ID/comments -f body="## Changelog
- Change 1
- Change 2"
```

**Always post a changelog comment** after updating a gist with significant changes.

## Related Skills

Check for other Dagger skills that may help with research:

- `engine-debugging` - Engine debugging workflows, trace replay, cache snapshots
- `internal-docs/dagger-codegen.md` - SDK codegen, templates, bindings
- `internal-docs/version-gating.md` - schema views and public API version gates
- `internal-docs/` - Cache and engine implementation references

---
> Source: [dagger/dagger](https://github.com/dagger/dagger) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-06-27 -->